• General
  • Versioning

Documentation

Welcome to the API Documentation Page

Thank you for visiting our API documentation page. We're excited to provide you with comprehensive information about our API and its capabilities.

Currently, our documentation is under construction, and we are diligently working to bring you more detailed information. However, for now, we encourage you to refer to the OpenAPI specifications provided. These specifications should serve as a valuable resource to navigate and understand the functionality of our APIs.

Rest assured, additional documentation, including detailed guides, usage examples, and endpoint descriptions, will be added soon to enhance your understanding and usage of our API.

We appreciate your patience and understanding as we continue to improve our documentation to better serve your needs. If you have any questions or need assistance, please don't hesitate to contact our support team.

Thank you for choosing our API. We look forward to providing you with an exceptional experience.

Versioning

DG-SANTE APIs leverage versioning to provide developers control over the specific API functionality they interact with. This ensures compatibility with your application even as the APIs evolve over time.

Versioning with the api-version Parameter

The api-version parameter, specified as a query parameter in your requests, dictates the API version you expect. It essentially allows you to define a point in time representing the API functionalities you're prepared for.

Here's how versioning benefits you:

  • Gradual Adoption of Changes: By setting the api-version parameter, you can adapt to API changes at your own pace. New features and functionalities introduced after your chosen version won't be reflected in your responses until you update the parameter.

Example: Suppose DG-SANTE introduces a new field named extendedData in a future update. If your API requests consistently use api-version=v1.0 or an earlier version, you won't see this new field in responses. However, updating the api-version parameter to a later version will include the extendedData field in subsequent responses.

Including the api-version Parameter

The api-version parameter is mandatory for all DG-SANTE API requests. This empowers developers to manage their integration with the continuously evolving API platform. We recommend keeping your version parameter as up-to-date as possible to benefit from the latest features and functionalities.

Example of a Valid Request:

https://....datalake.sante.service.ec.europa.eu/resources/search?api-version=v1.0

Recommended Approach:

  1. Set a Single Version: We recommend establishing a single api-version parameter across all your API calls and launching your application with that version.

  2. Regular Updates: Aim to increase the api-version value periodically (ideally every few months).

  3. Change Management: After updating the version, check for any API changes introduced since your previous version.

  4. Gradual Adoption: Modify your application logic to accommodate any new functionalities or breaking changes introduced in the newer API version.

Important Note:

  • Avoid dynamically setting the api-version parameter to the latest version with every request. Choose a specific version and only update it when you're ready to handle potential changes.

Deprecation Policy

As DG-SANTE APIs evolve, certain versions or endpoints might become deprecated over time. In such cases, responses to requests using deprecated versions or endpoints will include informative messages within the response's meta section. These messages will typically include a field indicating the deprecation.

A unique identifier to see that an endpoint will be deprecated is the sunset header

DG-SANTE offers a smooth transition for developers by:

  • API Brownouts: Simulated disruptions mimicking the effects of upcoming changes will be conducted before they go live.

  • Sunset Headers and Messages: In the API Reponses the Sunset header will be included, this specifies the date and time after which the deprecated version or endpoint will no longer be functional.

For these reasons, it's crucial to stay updated by monitoring the email address associated with your DG-SANTE developer account.