API basics v2

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/v2 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/v2 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.

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 Healthcare Directory API :
  • Search requests are limited to 100 results (see FHIR _count parameter - default:_count=10)
• 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

When searching data through the API, by default, only 10 elements will be returned, even if there are more hits. The results are paginated.

You can choose the number of results per page with the parameter _count (example: ?_count=50 to display 50 elements per page). The maximum page size allowed is 50 000 elements.

If you want to navigate through those results, you can use the links previous or next to show the previous or next set of results. The self link displays the current page results.

{
    "resourceType": "Example",
    "type": "searchset",
    "total": 48,
    "link": [
        {
            "relation": "self",
            "url": "{LINK_TO_CURRENT_PAGE}"
        },
        {
            "relation": "previous",
            "url": "{LINK_TO_PREVIOUS_PAGE}"
        },
        {
            "relation": "next",
            "url": "{LINK_TO_NEXT_PAGE}"
        }
    ],
    "entry": [...]
}

The previous link is not available on the first results page, the next link is not available on the last results page and finally if there is no need for paging results, the previous and next links will not be available.

Warning: During navigation through the results, addition, edition or suppression of resources can impact the result set.

If you want a fixed result set, you can activate it with the param _pit=true. It will create a search context for 60 seconds extended every time a new request is made.

Once the search context is expired, you'll have an invalid request exception and have to launch a new request.

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.