The API of Ship X platform is the primary interface for data exchange with the central system. It allows you to read and modify data.
Access to data is protected. Authorization mechanism is based on OAuth 2.0 standard. Requests are signed by using the access token of so-called Bearer Token, i.e. anyone using the correct token gains the access to specific resources through the API.
The API is a stateless interface.
HTTP response codes
HTTP response codes that may occur in the response from the server:
The resource was created.
204 NO CONTENT
Correct response, no value was returned. May occur e.g. when removing resources.
400 BAD REQUEST
Data sent using the POST or PUT method is incorrect. The response from the server includes more details.
Access to the resource requires authorization.
No or insufficient authorization to access the particular resource.
404 NOT FOUND
The resource was not found.
500 SERVER ERROR
An error occurred on server side.
If an error occurs, the API returns an error object that contains the following attributes:
HTTP response code. See the table above.
Error key, clearly identifying the problem.
Simple, easy to understand description of the error.
Description of the error may vary and should not be a base for conditions in the code.
|Object||Details of error that occurred, e.g. a list of validation errors. It may be empty in case of unrelated errors.|
Example of response:
HTTP/1.1 404 Not Found
"message": "Resource you are looking for are not found",
For requests sent by POST or PUT method, validation errors may occur. Details related to them are under details attribute in the response:
HTTP/1.1 400 Bad Request
"message": "Data sent by POST or PUT request are not valid. Check details for more info",
"name": ["required", "too_short"],
The keys of details object are names of attributes sent by POST or PUT method, for which validation errors occurred. Their value is presented in the table of error keys that are true for the sent value. Below we present a list of generic validation error keys.
The following table shows error keys that can be returned by the server with the possible HTTP codes:
|The searched resource was not found e.g. URL is invalid or resource does not exist.|
|When sending data using POST or PUT method, validation errors occurred. Detailed validation errors are included under details attribute.|
|Access to the resource is impossible because the request has not been signed with access token key.|
|Access to the specified resource is closed for this request type (e.g. due to lack or insufficient authorization).|
Keys of validation errors
The following table shows generic keys of validation errors that can be returned under details attribute for response of validation_failed error:
Stating a value is required.
The specified value is invalid. Details in the documentation describing the resource.
The value entered is too high. This applies mainly to numerical values. Details in the documentation describing the resource.
The value entered is too long. Details in the documentation describing the resource.
|The specified value is too low. This applies mainly to numerical values. Details in the documentation describing the resource.|
|The value entered is too high. This applies mainly to numerical values. Details in the documentation describing the resource.|
|The specified value has an incorrect format, e.g. digits entered in the field of telephone no. Details in the documentation describing the resource.|
In addition to these validation errors, others may occur that are specific to certain resources. For details refer to the appropriate chapters for these resources.
Stating a value is required.