Dobre API vs Złe API: 8 wskazówek projektowania API

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.