Adresy URL, metody i błędy API

Adres URL, metoda, konwencje błędów („GET”, „POST”, „PUT”, „DELETE”)

Ostatnia aktualizacja:
Stanislav Anisimov
Adres URL, metoda, konwencje błędów („GET”, „POST”, „PUT”, „DELETE”)
Click to expand / collapse

Niezawodny i intuicyjny interfejs API zaczyna się od jasnych zasad dotyczących interfejsów budowlanych. Stosujemy się do najlepszych praktyk REST, aby każdy deweloper wiedział, czego się spodziewać: struktura URL jest logiczna, metody są odpowiednie do działania, a błędy są łatwo interpretowane.

To obniża próg wejścia, upraszcza integracje i pozwala systemowi skalować się bez chaosu.

Konwencje dotyczące metod URL i HTTP

MetodaPowołanieZapytanie próbki
„GET”Zdobycie zasobu„GET/użytkownicy/42”
„PO”Utwórz nowy zasób„POST/użytkownicy”
„PUT”Pełna aktualizacja zasobów„PUT/użytkownicy/42”
„PATCH”Częściowa aktualizacja zasobów (Opt) 'PATCH/users/42'
„SKREŚLIĆ”Usuń zasób„USUŃ/użytkowników/42”

Stosuje się rzeczowniki liczby mnogiej ('/users ', '/devices', '/games ')

Podmioty gniazdowane są opisane jako hierarchia ('/users/42/sessions ')

Wszystkie żądania przechodzą przez HTTPS

Standardy obsługi błędów

KodWartośćKomunikat dotyczący próbki
`400`nieprawidłowe żądanie„Brakujące wymagane pole: e-mail”
`401`Niedozwolone„Nieprawidłowy token lub wygasła sesja”
`403`Odmowa dostępu„Odmowa dostępu do zasobów”
`404`nie znaleziono„Użytkownik z identyfikatorem 42 nie jest założony”
`409`Konflikt (np. powielanie)„E-mail już w użyciu”
`422`Błąd walidacji"Wiek pola" musi być numerem "
`500`Błąd serwera wewnętrznego„Nieoczekiwany wyjątek, wsparcie kontaktowe”
Struktura odpowiedzi na błąd: 
json
{
"error": {
"code": 400,   "message": "Missing required field: email",   "details": {...}
}
}

Korzyści dla deweloperów

Szybkie zrozumienie logiki API bez zbędnej dokumentacji

Jednolite podejście do wszystkich modułów i podmiotów

Łatwe debugowanie i rejestrowanie dzięki standardowym kodom i formatom

Kompatybilność z OpenAPI/Swagger, Listman, Autogeneracja SDK

Upraszcza obsługę, testowanie i CI/CD

Gdzie szczególnie ważne

Otwarte lub partnerskie platformy API

Projekty z wieloma zespołami rozwojowymi

Architektura mikroprzedsiębiorstw lub pierwsze podejście API

Systemy z wieloma podmiotami i interakcje

Jednolite konwencje sprawiają, że API jest niezawodny, zrozumiały i wygodny. Stosujemy się do najlepszych praktyk REST, tak aby każda integracja odbywała się szybko, bez nieporozumień i z maksymalną przewidywalnością.

Popularne tematy

Główne tematy