Page tree
Skip to end of metadata
Go to start of metadata

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:

HTTP code

Description

200 OK

Correct response.

201 CREATED

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.

401 UNAUTHORIZED

Access to the resource requires authorization.

403 FORBIDDEN

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.

Errors 

If an error occurs, the API returns an error object that contains the following attributes: 

Attribute

Type

Description

status

Integer

HTTP response code. See the table above.

error

String

Error key, clearly identifying the problem.

messageString

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.

detailsObjectDetails 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
 
{
	"status": 404,
	"error": "resource_not_found",
	"message": "Resource you are looking for are not found",
	"details: {}
} 

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
 
{
	"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"]
	}
} 

(warning) 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.


Errors keys 

The following table shows error keys that can be returned by the server with the possible HTTP codes:

Error key

HTTP code

Description

resource_not_found404The searched resource was not found e.g. URL is invalid or resource does not exist.
validation_failed400When sending data using POST or PUT method, validation errors occurred. Detailed validation errors are included under details attribute.
unauthorized401Access to the resource is impossible because the request has not been signed with access token key.
access_forbidden403Access 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:

Error key

Description

required

Stating a value is required.

invalid

The specified value is invalid. Details in the documentation describing the resource.

too_short

The value entered is too high. This applies mainly to numerical values. Details in the documentation describing the resource.

too_long

The value entered is too long. Details in the documentation describing the resource.

too_smallThe specified value is too low. This applies mainly to numerical values. Details in the documentation describing the resource.
too_bigThe value entered is too high. This applies mainly to numerical values. Details in the documentation describing the resource.
invalid_formatThe 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.


  • No labels