Ship X API is the main interface for exchanging data with the central system.
Access to data is protected, authorization mechanism is based on OAuth 2.0 standard.
Requests are authenticate by Bearer token. API is stateless interface.
List of HTTP status codes which may occurs in response:
HTTP status code | Description |
---|---|
| Successful request. |
| New resource is created. |
| Server successfully processed the request, and is not returning any content. |
| Server cannot process the request. More info in response. |
| Proper authorization is required to access this resource. |
| Access to the requested resource is forbidden |
| Resource is not found. |
| The server failed to fulfil a request |
If error occurs, API will return object with following attributes:
Attribute | Typ | Opis | |
---|---|---|---|
| Integer | HTTP status code | |
| String | Error key | |
| String | Easy to understand description of error.
| |
| Object | Details of the error which occurred. |
Response example
HTTP/1.1 404 Not Found { "status": 404, "error": "resource_not_found", "message": "Resource you are looking for are not found", "details: {} } |
In POST or PUT query - validation errors may occur. Details about them are placed in "details" attribute.
HTTP/1.1 400 Bad Request { "status": 400, "error": "validation_failed", "message": "Data sent by POST or PUT request are not valid. Check details for more info", "details: { "name": ["required", "too_short"], "post_code": ["invalid_format"] } } |
Names of attributes with validation errors are keys for details object. Their value is a table with error keys which occured. Error keys are described below. |
The table below shows the error keys that may occurs with possible HTTP codes.
Error key | HTTP Code | Description |
---|---|---|
|
| The resource you are looking for was not found |
|
| There were validation errors when sending data via POST or PUT. More info in "details". |
|
| Access to the resource is impossible due to lack of or incorrect access token. |
|
| Access to the specified resource is denied due to lack of or incorrect permissions. |
The table below shows the validation error keys that may occurs in details attribute if validation is failed.
Error key | Description |
---|---|
| Value is required. |
| Value is invalid, more info in resource documentation. |
| Value is too short, more info in resource documentation. |
| Value is too long. |
| Value is too small, it concerns to numerical value. |
| Value is too big, it concerns to numerical value. |
| Given value has an invalid format, e.g word in phone number field. |
Besides the above errors, there may be others, for specific resources. More details in documentation specific to these resources. |