API Updates

• Ship
• api
• data contracts

In order to use Ship's APIs, you must specify an API version by providing an x-api-version header with all requests.

Tip

The x-api-version header is explicitly required so that the API version used is always a conscious decision - i.e. you explicitly tell the API which specification version you wish to use.

Sorted will frequently make enhancements and improvements to our platform, including after an API version is officially released. However, we will make all changes in a backwards-compatible way, without breaking or removing any existing API functionality. This makes it straightforward for you to continue to use our APIs without any risk of any API endpoints or data contracts changing without your knowledge.

Backwards-Compatible Changes

Sorted considers the following changes to be backwards-compatible. As such, your integration must be able to handle these types of changes:

• Adding new API resources (e.g. new API endpoints).
• Adding new optional request parameters to existing API endpoints (e.g. query strings, route segments).
• Adding new properties to existing API responses.
• Adding new optional properties to existing API requests.
• Changing the order of properties in API responses.
• Changing the length or format of system-generated strings, such as object references or identifiers. This includes adding new prefixes to Sorted's standard reference format ([a-z]_[0-9]{32}).
• Adding new values to enumerations. This includes, for example, new API error codes and new shipment states, etc.

Warning

As a multi-tenant platform, Sorted must be able to make changes and introduce new functionality without providing advance notice to customers or seeking customer approval or sign-off. Your integration must be able to handle Sorted's industry-standard backwards-compatible changes.

Example Changes

This section gives examples of changes that Sorted consider to be backwards-compatible.

Note

These examples are not necessarily indicative of actual or planned changes and are used for purely illustrative purposes.

New API Resource

Sorted may add new API endpoints that do not clash with or override existing API endpoints.

For example, the following API endpoint could be added and would not be considered a breaking change because its URL does not conflict with any existing API endpoint:

https://api.sorted.com/pro/orders/{order-ref}

New Optional Route Parameters

Sorted may add new optional parameters to any existing API endpoint.

For example, Sorted might choose to add a new type of document such as a VP44. (This is not a real document. It is used for illustrative purposes only).

The existing customs document endpoint could be updated to accept this new document as a route parameter:

https://api.sorted.com/pro/documents/{shipment-ref}/VP44

New Optional Query String Parameters

Sorted might also add new optional query string parameters to existing API endpoints. This could be in addition to route parameters or instead of route parameters, as long as the existing URL continues to operate.

For example, a new optional format={x} could be added to the label API endpoint to allow the label format to be specified using a query string as opposed to a route parameter:

https://api.sorted.com/pro/labels/{shipment-ref}?format=zpl

New Resource Properties

Whilst all existing properties will remain unchanged, Sorted may add new properties to API responses at any time.

For example, Sorted might choose to add a new event_id property to error responses:

{
  "event": { //<- new property
    "id": 10001,
    "name": "Sample"
  },
  "correlation_id": "6c4e6a77-feab-42ab-9d7b-f559dc1b90ca",
  "code": "validation_error",
  "message": "A provided property has an invalid format",
  "details": [
    {
      "property": "addresses[0].contact.contact_details.email",
      "code": "invalid_format",
      "message": "'test@something' is not a valid email address"
    }
  ],
  "_links": [
    {
      "href": "https://api.sorted.comerrors/400_invalid_format.html",
      "rel": "documentation",
      "reference": "invalid_format" 
    }
  ]
}

New Optional Request Properties

Sometimes new properties might need to be added to API requests in order to accommodate new optional functionality. For example, new customs requirements may need to be introduced due to Brexit.

As long as such properties are optional, this is not considered a breaking API change and is therefore backwards-compatible.

For example, a new eori_number property could be added to a create_shipment_request. As long as this property is optional, this is considered a backwards-compatible change.

New Enumeration Values

Sorted may need to add new values to enumerations in line with business requirements.

For example, the Document object contains a DocumentType enum listing valid document types. If Sorted were to add the (hypothetical) VP44 document given in an earlier example, then vp44 would be added to that enum.