The Exorde API uses Semantic Versioning in the format
major part of the version represents the public API version. The
patch numbers are used to track the API evolution in release notes. For example, versions
1.2.4 all correspond to the public version
v1 of the API.
Non-breaking minor and patch updates to the API are released regularly. They have no impact on existing API clients, as long as they follow our best practices. These may include:
- Adding a new endpoint (new path or new HTTP verb)
- Adding a new response header or a new field in response body
- Adding a new value in a request parameter enumeration
- Adding a new optional request header or request parameter
- Adding a new HTTP response code
API clients must expect new properties to become available in existing endpoints or to receive an unknown HTTP status code.
Any breaking change will be introduced under a new major version of the API. They require changes to be made to the clients to support the change. Existing clients will still work with the legacy version of the API, while developpers implement changes to support the new API version.
Legacy API version will have a limited support in time. All API calls will state the deprecation of the API and the expected shutdown date.
Breaking changes may include:
- Adding a new mandatory request header or request paramater to existing endpoints
- Adding a new validation rule to existing endpoints
- Changing a parameter or attribute type (ex: from integer to float)
- Changing the request or response format
- Changing authentication mechanism
- Making mandatory a parameter that was optional
- Renaming an attribute, a parameter or a header
- Deleting an attribute, a parameter or a header
- Deleting an endpoint, a HTTP verb or a header
- Deleting a value from a request parameter enumeration
Specifying an API version
You should use the
X-Exorde-Api-Version header to specify an API version. For example:
--url https://api.exorde.io/posts \
--header "X-Exorde-Api-Version: v1" \
--header "Accept: application/json" \
--header "Authorization: Bearer <api-key>"
Requests without the
X-Exorde-Api-Version header will be rejected, you will receive a
If you specify an API version that is no longer supported, you will receive a
All API responses have a
status field with metadata about the request. When a deprecated API version is called, the
status object contains deprecation fields with information about the removal date of the API version.
A response with deprecation notice has the following shape:
"message": "The version 1 of the API is deprecated and will be shut down the 2022-02-02 at 00:00:00 UTC.",
v1.0.0-beta3 on October 25, 2023
- Add new filters on endpoints
v1.0.0-beta2 on September 20, 2023
- Remove fields
- Add field
v1.0.0-beta1 on July 05, 2023
- First release