Dokumentacja API ShipX

API platformy Ship X jest głównym interfejsem wymiany danych z systemem centralnym. Przy jego użyciu można odczytywać i modyfikować dane.

Dostęp do danych jest chroniony. Mechanizm autoryzacji oparty jest o standard OAuth 2.0.
Zapytania podpisywane są przy użyciu access tokena, na tzw. okaziciela (ang. Bearer Token), tzn. że ktokolwiek użyje prawidłowego tokenu, uzyska dostęp do określonych zasobów przez API.

API jest interfejsem stateless.


Kody odpowiedzi HTTP

Kody odpowiedzi HTTP, które mogą wystąpić w odpowiedzi od serwera:

Kod HTTP

Opis

Kod HTTP

Opis

200 OK

Odpowiedź prawidłowa.

201 CREATED

Zasób został utworzony.

204 NO CONTENT

Odpowiedź prawidłowa, żadna wartość nie została zwrócona. Spotykane np. podczas usuwania zasobów.

400 BAD REQUEST

Dane przesłane metodą POST lub PUT są niepoprawne. W odpowiedzi z serwera znajduje się więcej szczegółów.

401 UNAUTHORIZED

Dostęp do zasobu wymaga autoryzacji.

403 FORBIDDEN

Brak lub zestaw uprawnień jest niewystarczający, aby uzyskać dostęp do określonego zasobu.

404 NOT FOUND

Zasób nie został odnaleziony.

500 SERVER ERROR

Wystąpił błąd po stronie serwera.


 

Błędy

W przypadku wystąpienia błędu API zwraca obiekt błędu, który zawiera następujące atrybuty:

Atrybut

Typ

Opis

Atrybut

Typ

Opis

status

Integer

Kod odpowiedzi HTTP. Zobacz tabelę powyżej.

error

String

Klucz błędu, jednoznacznie identyfikujący problem.

message

String

Prosty, łatwy do zrozumienia opis błędu.

Opis błędu może ulegać zmianie i nie należy opierać na nim warunków w kodzie.

 

details

Object

Szczegóły dotyczące błędu, który wystąpił, np. lista błędów walidacji. Może być puste w przypadku błędów, których nie dotyczy.

Przykładowa odpowiedź:

1 2 3 4 5 6 7 8 HTTP/1.1 404 Not Found   { "status": 404, "error": "resource_not_found", "message": "Resource you are looking for are not found", "details: {} } 

W przypadku zapytania przesłanego metodą POST lub PUT mogą wystąpić błędy walidacji. Szczegóły na ich temat umieszczane są pod atrybutem details w odpowiedzi:

1 2 3 4 5 6 7 8 9 10 11 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"] } }

 Kluczami obiektu details są nazwy atrybutów przesłanych metodą POST lub PUT, dla których wystąpiły błędy walidacji. Natomiast ich wartości to tablica kluczy błędów, które są prawdziwe dla przesłanej wartości. Poniżej opisana jest lista generycznych kluczy błędów walidacji.

Klucze błędów

Poniższa tabela przedstawia klucze błędów, które mogą zostać zwrócone przez serwer, wraz z możliwymi kodami HTTP:

Klucz błędu

Kod HTTP

Opis

Klucz błędu

Kod HTTP

Opis

resource_not_found

404

Szukany zasób nie został odnaleziony, np. adres URL jest niepoprawny lub zasób nie istnieje.

validation_failed

400

Przy przesyłaniu danych metodą POST lub PUT wystąpiły błędy w walidacji. Szczegółowe błędy walidacji zawarte są pod atrybutem details.

unauthorized

401

Dostęp do zasobu jest niemożliwy, ponieważ zapytanie nie zostało podpisane kluczem access token.

access_forbidden

403

Dostęp do określone zasobu jest zabroniony dla tego zapytania (np. z powodu braku lub niewłaściwego zakresu uprawnień).

Klucze błędów walidacji

Poniższa tabela przedstawia generyczne klucze błędów walidacji, które zwracane są pod atrybutem details dla odpowiedzi błędu validation_failed:

Klucz błędu

Opis

Klucz błędu

Opis

required

Podanie wartości jest wymagane.

invalid

Podana wartość jest nieprawidłowa. Szczegóły w dokumentacji opisującej zasób.

too_short

Podana wartość jest zbyt krótka. Szczegóły w dokumentacji opisującej zasób.

too_long

Podana wartość jest zbyt długa. Szczegóły w dokumentacji opisującej zasób.

too_small

Podana wartość jest zbyt mała. Dotyczy głównie wartości liczbowych. Szczegóły w dokumentacji opisującej zasób.

too_big

Podana wartość jest zbyt duża. Dotyczy głównie wartości liczbowych. Szczegóły w dokumentacji opisującej zasób.

invalid_format

Podana wartość ma niepoprawny format, np. gdy w pole numer telefonu zostały wpisane cyfry.
Szczegóły w dokumentacji opisującej zasób. 

 

Oprócz powyższych błędów walidacji mogą wystąpić inne, które są specyficzne dla określonych zasobów. Szczegółów należy szukać w rozdziałach właściwych dla tych zasobów.