- We follow the REST architectural style.
We use the GET, POST, PUT and DELETE HTTP methods.
The general meaning of each method is as follows:ResourceGET (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
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.
- 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
- Query string parameter
The URL identifies the resource so positional parameters are used to identify the resource e.g.:
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
There are three main components where errors can occur:
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 codeDescription
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
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 codeDescription
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.
Serialization - Errors should not occur here.HTTP codeDescription
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)
There are two situations possible when calling the API:
- An error occurs - in this scenario, the response carries an error message (this code corresponds to the HTTP response code).
- 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.
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).
Required field is missing:
Invalid field value:
Shipment between submitted locations is not supported, eg. Brazil to Mexico:
Shipment for given number does not exist:
Object is required.