Skip to main content

Versioning

API version

The Exorde API uses Semantic Versioning in the format major.minor.patch.

The major part of the version represents the public API version. The minor and patch numbers are used to track the API evolution in release notes. For example, versions 1.0.0, 1.0.3 and 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.

caution

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:

curl \
--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 400 error.

If you specify an API version that is no longer supported, you will receive a 400 error.

Deprecation​

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:

{
// ...
"status": {
"cost": 1,
"apiDeprecationNotice": {
"message": "The version 1 of the API is deprecated and will be shut down the 2022-02-02 at 00:00:00 UTC.",
"shutdownDate": "2022-02-02T00:00:00.000Z"
}
}
}

Release note

v1.0.0-beta3 on October 25, 2023

  • Add new filters on endpoints /posts, /topics/trending, /emotions, /emotions/history, /sentiment, /sentiment/history, /volume,/volume/history, keywords/trending :
    • sourceType
    • domainName
    • language

v1.0.0-beta2 on September 20, 2023

  • Remove fields gender and ageRange from Post object.
  • Add field sourceType to Post object.

v1.0.0-beta1 on July 05, 2023

  • First release