5.1. API Availability and versioningΒΆ

The API is available on the /api/ endpoint: https://cargox.digital/api/v3/.

Attention

As things progress, requirements and API may change. To make sure that the API is stable, it is versioned. At CargoX we have decided that our API will use URL versioning.

This means that each API endpoint includes a version of the interface in the URL. Changes between versions are always breaking changes and upgrading to a new version of the API requires changes in the code.

CargoX guarantees that the APIs under the same version are constant. No breaking changes to the available APIs will happen. However, the following are still permitted and your code must be able to handle the transitions gracefully:

  • Input object (e.g. JSON) that you POST or PUT onto the platform might get new (non-mandatory) fields;

  • Output objects (e.g. JSON) that you GET or receive as a result of an action might get new fields;

  • New methods may appear in the API.

  • Error messages might get more defined - e.g. instead of returning a generic 400 or 500 error, the system might decide to return 403, or a custom code (e.g. 515).