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.4.0 on August 28, 2024​

  • Add new filters keywordsCondition (or & and) parameter to let users filter posts matching one or all of the keywords passed in input. This parameter is added on all the routes where keywords parameter can be used.
  • Raise limit for keywords parameter, now 5 keywords can be passed instead of 3

v1.3.0 on June 06, 2024​

  • Add new filters keywords on get sentiment (/sentiment) and get sentiment history (/sentiment/history). Allow users to get sentiment based on keywords instead of topics only.
  • Add new filters keywords on get volume (/volume) and get sentiment history (/volume/history). Allow users to get volume based on keywords instead of topics only.
  • Add new filters keywords on get emotions (/emotions) and get emotions history (/emotions/history). Allow users to get emotions based on keywords instead of topics only.

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