Nagłówki zapytania
Podczas wykonywania zapytania można określić następujące nagłówki
| Nagłowek | Opis |
|---|---|
| Authorization | Nagłówek autoryzacji, w którym należy przesyłać wszelkie dane związane z autoryzacją. Szczegóły zostały opisane w rozdziale Autoryzacja. |
| X-User-Agent | Nagłówek ten pozawala na określenie nazwy klienta/platformy i/lub innych informacji z nim związanych. |
| X-User-Agent-Version | Nagłówek ten pozwala na określenie wersji klienta/platformy, który wykonuje zapytania. Jego zawartość nie wpływa na funkcjonowanie API. |
| X-Request-ID | Nagłówek ten pozwala na określenie identyfikator zapytania. Jest on przydatny przy debugowaniu błędów i problemów, które mogą zdarzyć się przy integracji z API. Jego podanie nie wpływa na funkcjonowanie API. |
| Accept-Language | Nagłówek pozwala na zmianę formatu komunikatów błędów. Dostępne:
|
Nagłówki odpowiedzi
W odpowiedzi serwer zwraca następujące nagłówki:
| Nagłówek | Opis |
|---|---|
| X-Request-ID | Identyfikator zapytania. Przydatny podczas debugowania problemów z API. W przypadku gdy zostanie on określony podczas zapytania, API nie będzie generowało własnego IID, a w odpowiedzi zostanie zwrócony ten podany podczas zapytania. |
Kolekcje
Atrybuty kolekcji
| Atrybut | Typ | Opis |
|---|---|---|
href | String | Absolutny adres URL do kolekcji. |
count | Integer | Łączna ilość elementów kolekcji. |
page | Integer | Aktualna strona wyników kolekcji. |
per_page | Integer | Ilość wyników (na stronę) zwracanych w odpowiedzi. |
items | Array | Elementy kolekcji. |
Przykład kolekcji w formacie JSON:
{
"href": "https://api-pl-shipx.easypack24.net/v1/points",
"count": 1024,
"page": 10,
"per_page": 100,
"items": [
{
"href": "https://api-shipx-pl.easypack24.net/v1/points/KRA010",
"id": "KRA010",
... other resource's params ...
}
]
}
Stronicowanie
Kolekcje wspierają stronicowanie (chyba, że zostało zaznaczone inaczej w dokumentacji właściwej dla zasobu).
Przewijanie po kolejnych stronach kolekcji obywa się poprzez przekazanie w zapytaniu parametrów (page) i/lub (page_page). Przykład zapytania:
GET /v1/points?page=10 HTTP/1.1 Host: api-shipx-pl.easypack24.net Content-Type: application/json
Autoryzacja
Wszystkie zapytania wysyłane do serwera wymagają podania prawidłowego i ważnego access tokenu, który należy do określonego właściciela (owner) organizacji.
Access token należy przekazać w nagłówku Authorization.
Przykład zapytania:
GET /v1/users HTTP/1.1 Host: api-shipx-pl.easypack24.net Content-Type: application/json Authorization: Bearer W-TYM-MIEJSCU-NALEZY-UMIESCIC-TOKEN
Błędy
Przykład błędu
HTTP/1.1 400 Bad Request
Content-Type: application/json
{
"status": 400,
"error": "invalid_parameter",
"description": "Passed unsupported value (value of the parameter here) to parameter (parameter name)",
"details": null
}
Poniżej znajduje się lista kluczy błędów, które mogą wystąpić.
| Klucz | Opis |
|---|---|
resource_not_found | Szukany zasób nie został odnaleziony. |
access_forbidden | Dostęp do określonego zasobu jest zabroniony. |
invalid_parameter | Przekazano niepoprawną wartość dla określonego parametru w URI. Szczegóły dostępne pod kluczem description odpowiedzi błędu. |
validation_failed | Błąd walidacji. Dane przesłane w ciele zapytania metodą POST są niepoprawne. Szczegóły błędu zawarte w odpowiedzi pod kluczem details. Zobacz poniżej przykład błędu walidacji. |
offer_expired | Zakupienie oferty jest niemożliwe, ponieważ upłynął termin jej ważności. |
Przykład błędu validation_failed
HTTP/1.1 400 Bad Request
Content-Type: application/json
{
"status": 400,
"error": "validation_failed",
"description": "Some of data sent in payload are invalid. Check details for more information.",
"details": {
"email": ["invalid"]
}
}
Obit details zawiera w tym przypadku kolekcję, w której klucze odpowiadają nazwom przesłanych w ciele zapytania parametrów, natomiast wartości to tablica z kluczami określającymi jakie błędy walidacji wystąpiły dla określonego parametru.
Możliwe błędy walidacji to:
| Błąd walidacji | Opis |
|---|---|
required | Wartość dla określonego parametru jest wymagana. |
too_short | Ilość znaków zbyt mała. Sprawdź szczegóły w dokumentacji określonego zasobu. |
too_long | Ilość znaków zbyt duża. Sprawdź szczegóły w dokumentacji określonego zasobu. |
not_a_number | Wprowadzona wartość powinna być liczbą. |
not_an_integer | Wprowadzona wartość powinna być liczbą całkowitą. |
invalid | Wprowadzona wartość jest niepoprawna. Sprawdź szczegóły w dokumentacji określonego zasobu. |