Konwencje adresów URL, metod i błędów: przewidywalne i znormalizowane API

Ostatnia edycja:

Diana Romanova

—

Czerwiec 25, 2025

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

Niezawodny i zrozumiały 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

Metoda	Powołanie	Zapytanie 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

Kod	Wartość	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
{
„błąd”: {
„kod”: 400, „wiadomość”: „Brakujące wymagane pole: e-mail”, „szczegóły”: {...}
}
}

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ą.