API basics

Requests

Base URL

All API access are over HTTPS, and accessed for :

production environment:

• the https://authentication.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.ramsay.lifen.fr/fhir/v3

test environment:

• the https://authentication.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.

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 :

• Global limit : 10 calls/seconds
• On the Access Patient Information & Access Encounter Information APIs, search requests are limited to 10 results.
• On the Send document to the EHR API :
  • Binary size must be less than 15 MB
    • Please note that the limit on the DPI side may be lower

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:

Required fields depending on the case:

Date prefixes

Depending on the service, the search parameters for dates may support the prefixes : gt, lt, ge, le. A detailed definition is provided in the FHIR documentation. Please refer to the corresponding service documentation.