API v3

The API uses a self-documenting format. All documentation is available at the URLs, as explained below. We also prepared Postman collection for easier integration.

Slash at the end of the URL is ignored

All v3 endpoints ignore the trailing slash. This means that URIs /api/v3/companies/self/ and /api/v3/companies/self are considered equal.

API Availability and versioning

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

caution

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).

Endpoints

The following "well known" URLs are available within this API segment.

Environment	Endpoint
Entry point	https://cargox.digital/api/v3/
Redoc explorer	https://cargox.digital/open-api-schema/redoc/integrations/
Swagger client	https://cargox.digital/open-api-schema/swagger/integrations/

The endpoints are hierarchical and take on the following structure:

/{entity}/{query-type}[/{identifier}] # Get/act on a single entity
/{entity}/list/                       # Get the list of entities

where:

• {entity} is the plural name of the entity, e.g companies, users etc.
• {query-type} is the query by which the entity can be uniquely identified. Check the specific API call for which queries are supported. Most of the time, at least these two types will be available:
  • .../self/... refers to the entity of the caller. e.g. /companies/self will return the company connected with the credentials of the caller.
  • .../by-id/{id}/... will find the given entity by id, if the caller has access to it. E.g. /companies/by-id/7 returns the company with id=7.
• /list returns a list of all entities matching the given criteria. This criteria is sometimes defined with the query string and sometimes inferred from the context. Check specific API calls for description.

Postman Collection

Postman Collections are simply a collection of pre-built requests that can be organized into folders, and they can be easily exported and shared with others. Below is exported CargoX collection which you can start using immediately.

The following URLs are available within this Postman Collection. They are already set up in collection.

Environment	Endpoint
Base Url	https://cargox.digital/api/v3/
Access Token Url	https://cargox.digital/oauth/token/

Download Postman Collection

Here is a json collection file: ⬇️ JSON. You can easily import it into Postman via File->Import command.

Postman will import collection and you can try it after setting up OAuth for authentication.

Setting up OAuth for authentication

CargoX Platform uses OAuth for authentication. Each application is issued a custom client_id and client_secret which it uses then to identify itself against the CargoX application and authorize users.

Before using Postman collection you need to obtain client_id and client_secret and insert them into Postman collection variables as shown below:

You can test OAuth with a "Get new access token" button from Authorization tab. If all is set up, you should get "Authentication complete" notification. This authorization method will be used for every request in this collection.