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

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

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 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 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

Pagination will soon be available for some Platform Services. Stay tuned!

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.