Skip to content

API Versions and Upgrades

API changelog

Whenever updates are made to Gainly API, they are documented in our API changelog.

Breaking changes

A breaking change refers to any API update that causes your existing code to stop functioning as expected, requiring you to update your code to continue using the API.

Most of our API updates do not involve breaking changes.

Non-breaking changes

We consider the following to be non-breaking or backward-compatible changes:

  • Adding new API endpoints.
  • Adding new optional parameters to API requests.
  • Adding new properties to API responses, or changing the order of existing properties.
  • Changing the length and/or format of opaque strings such as document IDs.
  • Changing the format and/or content of error messages and other strings meant for human consumption.
  • Expanding functionality with backward-compatible features.
    • For instance, adding a new format for an API request parameter while also supporting the old format.
  • Deprecating but not removing functionality.
    • Marking features as deprecated but still supporting them to give API clients time to migrate without breaking existing implementations.

API versions

Gainly API uses date-versioning, such as v20241104. The date-version is included in almost all of your API endpoint paths, for example:

POST /v20241104/search

Info

Certain utility endpoints, such as GET /versions, are global and do not use a version in the endpoint path.

When you start using the Gainly API, we recommend that you use the latest available version. You can do this by simply including that version in your endpoint paths:

POST /v20241104/search

You'll automatically have access to API updates released after that as long as they are non-breaking changes. This will continue until a new date-version is released that includes breaking changes.

date-versions

Certain API updates introduce breaking changes. These updates are tagged in the changelog with a date-version, such as:

  • Version: v20241104

A detailed list of specific breaking changes will also be included in the changelog.

Upgrade your API version

You can upgrade your API version at any time by simply using a newer API version in your endpoint paths.

Best Practices

Before upgrading your API version, please make sure you've updated your code to address all the breaking changes and tested thoroughly.

You can retrieve a list of available API versions using the Versions endpoint.