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 developers 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 parameter 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.2.0 on February 09, 2024​

  • List topics (/topics) and get topic (/topic) now returns also keywords in items response.
  • name parameter in list topics endpoint (/topics) is accepted if its length is superior or equal to 1 (instead of 3 before).
  • Add new endpoint to get trending topics related to another topic (/topics/{id}/related/trending).
  • Add new endpoint to get rising topics related to another topic (/topics/{id}/related/rising).
  • Add new endpoint to get rising topics (/topics/rising).

v1.1.0 on January 18, 2024​

  • Time series endpoints (/emotions/history, /sentiment/history, and /volume/history) now return up to 1000 items per request. The limit query parameter maximum value has changed from 100 to 1000.
  • The interval query parameter for time series endpoints (/emotions/history, /sentiment/history, and /volume/history) now accepts values in minutes and in human readable format. For example, interval=1440 and interval=1d are equivalent. The maximum value for interval is 10 years.

v1.0.0 on January 01, 2024​

  • First official release of Exorde API.

v1.0.0-beta4 on December 28, 2023​

  • Field plan can be undefined in User object.
  • Remove field actualInterval from time series responses (endpoints /emotions/history, /sentiment/history, and /volume/history). Data granularity doesn't decrease over time anymore, so the requested interval is always the actual interval.
  • Remove the global history limit of the API, the limit is now set per user. This change has no impact on requests or responses.

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.
Last updated on