Introduction

The api honors the Accept header for content type negotiation. All documentation use application/json, but many requests also support application/xml. Some requests support additional content types. Please refer to the documentation for each request to learn about supported content types.

JavaScript Object Notation

JSON is the preferred content type when communicating with the API. Your request must send the appropriate Accept header to receive responses in this format.

Accept: application/json

Object References

All api methods preserve object references by including $id and $ref parameters in the returned data. If data references a previously used entity within the same request, this functionality must be used. This inlcudes data sent as part of a request.In the following example, the same address is referenced by two subbookings. Note: $id can be defined as a number or any string, where $ref has to be a string that would evaluate as true when compared with $id in a string comparison. 


{
    subBookings: [
        {
            collectionAddress: {
                $id: "1",
                id: 17
            }
            deliveryAddress: {
                $id: "2",
                id: 1245
            }
        },
        {
            collectionAddress: {
                $ref: "1",
            }
            deliveryAddress: {
                $id: "3",
                id: 9426
            }    
        }
    ]
}

Primitive Data Types

The documentation refers to a fixed set of possible primitive values. Complex values are documented in the individual api sections.

Type Description
date Dates are represented as a ISO 8601 string. Timezone handling is specified in the documentation for the specific api. Example: 2017-11-04T14:21.
time Time may refer to time of day or a span of time. In both cases it is represented as a string formatted as hh:MM. Example: "17:45"
url Refers to a url as specified by RFC 3986 in string format. Example: "https://www.dfds.com"
number Numbers do not accept 1000-seperators. Decimals are seperated by '.'. Example: 56212.7

Entity Tree Data

Some sections of the api rely on entity data. This is clearly indicated in the documentation when applicable.

Concurrency

All entity data contains a property called "concurrencyToken" as string value. Data returned from the api will always contain this value, and it may be optionally provided when posting data to the api. When a concurrency token is included in a post it will be validated to make sure no other changes have been made to that entity since it was retrieved from the api. If a change is detected, a 409 Conflict is returned.

HTTP/1.1 409 Conflict

You must get the latest version of data you are posting to resolve the conflict. A conflict may occur even if you have not provided a concurrency token value. When this happens you may retry the operation to resolve the issue.

Identifiers and absent properties

Entity data always includes an id attribute. New entities should have an id value of 0 or the attribute may be omitted. Any id value of 1 or greater refers to existing data. Full objects are always returned from the API, but posted data does not need to include all attributes. The following example specified a country by only provided an id to an existing entity. 


{
    country: {
        id: 17
    }    
}

If attributes are included anyway, they are interpreted as a request for modification. This may cause an authorization exception if modification is not allowed.


{
    country: {
        id: 17,
        name: "Some updated name"
    }    
}

Assuming you do not have permission to change values on countries, but are allowed to reference existing countries, the above request will return an error.

HTTP/1.1 403 Forbidden