1) Czyste, logiczne nazewnictwo
Używaj nazw, które jasno opisują ich funkcję. Na przykład: jeśli API służy do pobierania listy produktów, ścieżka powinna być /products
. To sprawia, że API łatwe do zrozumienia.
2) Idempotentność: Niezawodność przez powtarzalność
- Operacje idempotentne (np. GET, PUT, DELETE) powinny dawać ten sam wynik przy każdym wywołaniu, co zwiększa niezawodność API,
- Operacje nieidempotentne (POST, PATCH) mogą zwracać różne wyniki, więc ich użycie powinno być dobrze przemyślane.
Przykład: Użycie PUT
do aktualizacji danych użytkownika zawsze zwróci ten sam wynik, niezależnie od liczby prób aktualizacji.
3) Wersjonowanie API
Używaj wersjonowania (np. /api/v1
, /api/v2
) aby unikać problemów z kompatybilnością przy wprowadzaniu zmian.
4) Czyste zapytania: Sortowanie i filtrowanie
Wykorzystuj parametry URL do filtrowania i sortowania danych, co ułatwia manipulację i pobieranie konkretnych zestawów danych.
Przykład:
Filtrowanie użytkowników: /users?filter=id:10
,
Sortowanie produktów: /products?sort=price:asc
.
5) Bezpieczeństwo i autentykacja w API
Zawsze stosuj mechanizmy autentykacji (np. tokeny JWT) i szyfruj dane przesyłane przez API.
Jak Zaimplementować Autentykację?
1. Użyj Tokenów JWT (JSON Web Tokens)
Użytkownik loguje się za pomocą swojego loginu i hasła. Serwer weryfikuje te dane i, jeśli są poprawne, generuje token JWT, który jest zwracany użytkownikowi. Token ten musi być następnie przesyłany z każdym żądaniem do API w celu weryfikacji tożsamości użytkownika.
6) Proste odniesienia do zasobów
Twórz przejrzyste i logiczne ścieżki dostępu do zasobów, co ułatwia ich znajdowanie i interakcję.
Przykład:
Dobrze: /api/v1/carts/123/items/321
– prosto i czytelnie.
Źle: /api/v1/items?cart_id=123&item_id=321
– skomplikowane i mylące.
7) Ograniczenia zapytań: Chroń serwer
Stosuj ograniczenia liczby zapytań, które użytkownik może wysłać do API w określonym czasie, aby zapobiec przeciążeniu serwera.
Przykład: Użytkownicy w darmowym planie mogą wykonać 1000 zapytań na dzień.
8) Paginacja: Nie obciążaj serwera
Używaj paginacji do zwracania danych w mniejszych porcjach, co zapewnia szybsze ładowanie i mniej obciąża serwer.
Przykład: /products?page=1&limit=10
– zwraca pierwsze 10 produktów.