Skip to content

API basics

Requests

Base URL

All API access are over HTTPS, and accessed from :

  • the login.public.lifen.fr domain for authentication
  • the api.lifen.fr domain for FHIR endpoint

HTTP verbs

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

  • GET: Search and recovery of a resource.
  • PUT: Update the value of some fields.
  • POST: Create a resource.
  • DELETE: The possibility of deletion is not given by security. However, some resources can be archived with an update of the resource.

Each operation has access control based on the authenticated user. Also, some resources restrict operations allowed, e.g, the FHIR Directory API is read-only to maintain a qualitative directory of healthcare professionals.

Parameters

Lifen supports the FHIR standard and respects the nomenclature developed by the standard for search parameters.

To find all the search parameters, follow this documentation : standard of search parameters in FHIR

HTTP status code

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 code Type Definition
200 OK Successful request
201 Created Returned on successful entity creation
400 Bad Request The request is malformed. Check the parameters or the syntax
401 Unauthorized Could not authenticate the request
403 Forbidden The request is not allowed
404 Not found The resource is not found
409 Conflict The 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)
410 Gone The resource does not exist any longer
412 Precondition Failed Returned for conditional requests or invalid search param value (invalid date)
413 Payload Too Large The request is too long to be processed
422 Unprocessable Entity The proposed resource violated applicable FHIR profiles or server business rules
429 Too many requests Too many requests hit the API too quickly. See Rate limit section
500 Internal Server Error Something went wrong on our end
501 Not Implemented Lifen cannot fulfill the request
503 Service Unavailable Lifen service is (temporarily) not available

Error response

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 FHIR Directory API :
  • On the FHIR Document API :
    • Binary size must be less than 30MB

Note: those limits are default ones defined by Lifen. If you need more, please contact your account manager.

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

Use two parameters to paginate:

  • _count: choose number of results per page
  • _getpagesoffset: choose where page begin

For example:

  • First page (start): GET /Patient?_count=10&_getpagesoffset=0
  • Second page: GET /Patient?_count=10&_getpagesoffset=10
  • Third page: GET /Patient?_count=10&_getpagesoffset=20

Tips: For usage of the parameter _include, the result will be on the same page as the parent resource.

See documentation here: Paginated search include

For a paginated search, the maximum result size is 50 000 for all pages