Your browser does not support Java Script or javascript is disabled. Please ensure that your browser supports it for full compatibility with our services.

General Rules

General rules

  1. We follow the REST architectural style.

  2. We use the GET, POST, PUT and DELETE HTTP methods. 

    The general meaning of each method is as follows:  

    Resource
    GET (read)
    POST (create)
    PUT (update)
    DELETE (delete)
    /resource_name List all Create new Bulk update

    Delete all resources

    /resource_name/1 List resource identified by id 1 ERROR If resource exists then update it, error otherwise Delete resource identified by id

    Note

    In some cases the meaning might be slightly changed and/or amended, for instance method DELETE on /orders/1/ cannot delete an order (there are no allowances for this) so instead it will cancel it. Another example is DELETE on /shipments/ which is totally forbidden, so it will be treated as a non-allowed method.

  3. We use OAuth2.0 for authentication.
    In order to make a service call, an authorization token is required. The access token can be used at either of the addresses below: 
    • HTTP authorization header
Authorization: Bearer 05ca632953f05d3f831a
    • Query string parameter

Parameters

Positional parameters

The URL identifies the resource so positional parameters are used to identify the resource e.g.:

Query string

Other parameters are normally passed in a URL query string:

Big request data

In a case where a query string would be too long, parameters should be applied tp request content as JSON structured data. Normally this happens when a POST request is performed. For instance, for a booking service the POST method is used and content of the POST request contains structured data in JSON (instead of standard POST form data).

Returning values and errors

Errors

There are three main components where errors can occur:

  1. Request validation - If an error occurs during the first step of an API call, it means that there is something wrong with the request.

    HTTP code
    Description
    400 (Bad Request) Validation exception eg. missing parameter, wrong parameter value
    403 (Forbidden) User lacks permission to access requested service.
    405 (Method Not Allowed) Wrong http method used eg. POST instead of GET
  2. Service logic: if an error occurs during the second step of an API call, it means there is a logic problem with the request. 

    HTTP code
    Description
    404 (Not Found) Requested resource could not be found.
    412 (Precondition Failed)

    The server does not meet one of the preconditions that the requester has put in the request. This status code can be used for logical errors which are different to a missing resource.

  3. Serialization - Errors should not occur here.

    HTTP code
    Description
     500 (Internal Server Error)

    Generic error as serialization should not fail.

Other HTTP codes are described here: http://en.wikipedia.org/wiki/List_of_HTTP_status_codes

All errors/exceptions which are not covered in one of the described categories are treated as a 500 (Internal Server Error) and a general message is returned (without internal details).

Successful requests are always returned with status code 200 (OK)

Response format

There are two situations possible when calling the API:

  1. An error occurs - in this scenario, the response carries an error message (this code corresponds to the HTTP response code).
  2. The request is processed successfully, in which case the response carries a result.

In both cases a response is guaranteed to be returned in the requested format (or default when no specific format is chosen).

General response structure

There are always three elements returned in a response:

  • code - corresponds to HTTP status code
  • message - contains a detailed error message or some additional message related to the response. This field might be empty in cases of a successful response, however, even then it will be present.
  • result - this field carries the result of the requested action. It may be empty in cases of an error but even so, it will be present.

Examples

Here are example responses in JSON and XML formats. Each presents both error and success cases.

JSON - response is returned as associative array (JSON object).

  • Error response:

{
    "message" : Missing parameter: collection.first_name,
    "code": "400",
    "result": {}
}

          Successful response:

{
    "code" : 200,
    "message": "OK",
    "result": {...}
}

 

Error messages

Required field is missing:

Missing parameter: collection.city

Invalid field value:

Invalid value, parameter: collection.city, value: 1231232

Shipment between submitted locations is not supported, eg. Brazil to Mexico:

Operation not supported: shipment between given countries not allowed

Shipment for given number does not exist:

Not found: shipment doesn't exist, number: S2AS123

Object is required.

Required at least one package.