API Versioning

How to handle versioning in the CargoDocs API

From time to time, we may need to make breaking changes to our API functionality. We try very hard to avoid this, but it is sometimes necessary, e.g., to fix bugs when some users may have code that relies on incorrect behaviour.

📘

Changelog

Looking for the latest changes? Check them out in the ChangeLog.

We offer a versioned API to improve our APIs while preventing existing code from breaking. The URL of every API call includes an explicit version as the first path segment. The following call uses API version v3.

HTTP

http://api.domain.cargodocs.com/v3/exchange/customers

To the best of our ability, we try to ensure that old API versions don't change, even as our services evolve. This may sometimes include "wrong" behaviour that we may choose to maintain if we deem that the fix might negatively impact users. As long as we don't see the change as a breaking change, we may choose to introduce it also in older versions of the API.

Deprecation and Removal

The burden of supporting older API versions grows as our services evolve. Sometimes we will have to deprecate and then remove certain older API versions. We will always give appropriate notice when this is necessary.

Backward-compatible changes

We consider the following changes to be backwards-compatible and may therefore introduce them retroactively in old API versions:

• Add new object attributes in JSON responses (outside documents or query results).
• Changing the order of object attributes in JSON responses.
• Adding new prefixed metadata attributes to stored or modified documents.
• Adding new functionality to endpoints, e.g., operators, functions, and data types.
• Adding new, optional parameters to API calls.
• Adding new HTTP headers in responses.
• Adding new endpoints to the API or new methods to the existing API endpoint.