API Versioning

How CargoDocs API implements versioning.

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 the incorrect behavior.

📘

Changelog

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

To improve our APIs while also preventing existing code from breaking, we offer a versioned API. 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/

To the best of our ability, we try to ensure that old versions of the API don't change, even as our services evolve. This may sometimes include "wrong" behavior 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 versions of the API grows as our services evolve. At times we will have to deprecate and then remove certain older versions of the API. We will always give appropriate notice when this is necessary.

Backward-compatible changes

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

• Adding new object attributes in JSON responses (outside of 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.