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.