API basics

Requests

Base URL

All API access are over HTTPS, and accessed for :

production environment:

  • the https://login.lifen.fr domain for authentication
  • the https://production.platform-apis/ audience for authentication
  • the https://api.lifen.fr/fhir/v3 domain for FHIR endpoint
    • For Ramsay hospitals : https://api.lifen.ramsaygds.fr/fhir/v3

test environment:

  • the https://login.public.post-prod.lifen.fr domain for authentication
  • the https://post-prod.platform-apis/ audience for authentication
  • the https://api.post-prod.lifen.fr/fhir/v3 domain for FHIR endpoint
    • For Ramsay hospitals : https://api-ramsay.post-prod.lifen.fr/fhir/v3

HTTP verbs

Lifen APIs are REST-compliant. You can operate resources with the following HTTP methods:

  • GET: Recovery of a resource.
  • POST: Create or search a resource.
  • DELETE: The possibility of deletion is not given by security. However, some resources can be archived with an update of the resource.

HTTP status codes

Supported status

All responses use standard HTTP status codes.

Usually, codes in the 2xx range indicate success, codes in the 4xx range are for client-related failures, and 5xx codes are for Lifen-related issues.

Status codeTypeDefinition
200OKSuccessful request
201CreatedReturned on successful entity creation
400Bad RequestThe request is malformed. Check the parameters or the syntax
401UnauthorizedCould not authenticate the request
403ForbiddenThe request is not allowed
404Not foundThe resource is not found
409ConflictThe request cannot be completed due to conflict (when two clients try to create the same resource or if there are concurrent, conflicting updates or not the right version of the resource)
410GoneThe resource does not exist any longer
412Precondition FailedReturned for conditional requests or invalid search param value (invalid date)
413Payload Too LargeThe request is too long to be processed
422Unprocessable EntityThe proposed resource violated applicable FHIR profiles or server business rules
429Too many requestsToo many requests hit the API too quickly. See Rate limit section
500Internal Server ErrorSomething went wrong on our end
501Not ImplementedLifen cannot fulfill the request
503Service UnavailableLifen service is (temporarily) not available

Error responses

On Lifen API, the body format of an error response is a JSON object corresponding to the OperationOutcome FHIR resource.

Each issue contains this following fields :

  • severity: enum to qualify the level of the error (fatal | error | warning | information)
  • code: type of the issue (all possible code here)
  • diagnostics (optional) : human readable error message.
{
  "resourceType": "OperationOutcome",
  "issue": [
    {
      "severity": "error",
      "code": "processing",
      "diagnostics": "Operation forbidden (insufficient scope)"
    }
  ]
}

Rate Limit

To ensure the availability of the Lifen API, certain limits must be respected :

Indexing

In order to ensure all data is indexed in a way thay guarantees the best possible search experience, the process is by default performed asynchronously. This means, that in certain cases the updated or created resource will not necessarily be available in search results immediately, but with a few seconds (or minutes in extreme cases) delay.

Pagination

📘

This pagination is not available on Ramsay and Vivalto

All endpoints which return an object list, support pagination with pagination information inside a link object.

Lifen uses a cursor based pagination via the index and searchAfter/searchBefore parameters.

Reminder

  • A _count search parameter already exists and allows to vary the number of results per page. The maximum authorized is 100. The default value is 10 (except for the organization and practitioner which is 100) if this parameter is not filled in.
  • The _count = 0 proposed by FHIR is not supported on the Lifen Platform at the moment. This parameter with this value provides access only to the total number of results that this query would return.

Request example

curl --location --request POST 'https://**api**.post-prod.lifen.fr/fhir/v3/Patient/_search' \
--header 'Authorization: bearer XXX' \
--header 'Content-Type: application/x-www-form-urlencoded' \
--data-urlencode 'name=Paulette Michue' \
--data-urlencode '_count=2'

Response

{
    "resourceType": "Bundle",
    "id": "a42f5788-b9ec-44bc-8051-4e2ff54f1fd6",
    "type": "searchset",
    "total": 390,
    "link": [
        {
            "relation": "self",
            "url": "https://api.lifen.fr/fhir/v3/Bundle?_id=a42f5788-b9ec-44bc-8051-4e2ff54f1fd6"
        },
        {
            "relation": "previous",
            "url": "https://api.post-prod.lifen.fr/fhir/v3/Bundle?_id=42f5788-b9ec-44bc-8051-4e2ff54f1fd6&_index=1&_searchBefore=16.771122-7440439"
        },
        {
            "relation": "next",
            "url": "https://api.lifen.fr/fhir/v3/Bundle?_id=a42f5788-b9ec-44bc-8051-4e2ff54f1fd6&_index=2&_searchAfter=16.771122-7440439"
        }
    ],
    "entry": [
      {
        "fullUrl": "https://api.lifen.fr/fhir/v3/Patient/7830625",
        "resource": {}
      },
      {
        "fullUrl": "https://api.lifen.fr/fhir/v3/Patient/7830626",
        "resource": {}
      }
    ]
}

In the link object, you will have the link of the next page on the next relation accessible in GET

📘

You can rely on the total field to know the total number of results for this search (divided into several pages according to the _count chosen)

Link details:

LinkDescription
selfgo to current page
previousgo to the previous page (present only if there is a previous page)
nextgo to the next page (present only if there is a next page)

Required fields depending on the case:

Champsselfpreviousnext
_idrequiredrequiredrequired
_index-requiredrequired
_searchAfter--required
_searchBefore-required-

Date prefixes

The following prefixes are supported for period fields : eq, ne, gt, lt, ge, le. A detailed definition is provided in the FHIR documentation.

They will soon be supported for date fields and for Ramsay and Vivalto hospitals too.