---

Jakie są zasady?

1. Zasoby jako punkty końcowe:
   • Każdy zasób jest identyfikowany przez unikalny URL.
2. Stateless:
   • Każde żądanie powinno zawierać wszystkie informacje niezbędne do jego realizacji – serwer nie przechowuje stanu sesji użytkownika.
3. REST API wykorzystuje metody HTTP:
   • GET do pobierania danych,
   • POST do tworzenia nowych zasobów,
   • PUT/PATCH do aktualizacji
     • PUT – aktualizujemy cały obiekt, nadpisując go
     • PATCH – aktualizujemy np. jeden parametr
   • DELETE do usuwania.
4. Format danych:
   • Dane są zazwyczaj przesyłane w formacie JSON lub XML.
5. HATEOAS (Hypermedia As The Engine Of Application State):
   • Klient powinien być w stanie odkrywać dostępne operacje dzięki dostarczanym hiperlinkom (choć nie jest to zawsze wymagane).

---

Poziomy dojrzałości REST API (Model R. Fieldinga)

Richard Fielding zaproponował 4-poziomowy model dojrzałości który określa, jak dobrze interfejs spełnia zasady REST:

• Level 0: Remote Procedure Call (RPC)
  API jest zbiorem punktów końcowych wykonujących określone operacje, ale nie wykorzystuje w pełni potencjału HTTP.
  • Przykład: /getUser lub /deleteProduct.
• Level 1: Zasoby
  API zaczyna traktować zasoby jako centralny element. Zasoby mają swoje unikalne identyfikatory,
  • np. /users/123.
• Level 2: Wykorzystanie metod HTTP
  API korzysta z metod HTTP zgodnie z ich przeznaczeniem (GET, POST, PUT, DELETE), co upraszcza interakcję z zasobami.
• Level 3: HATEOAS
  Najwyższy poziom dojrzałości – API zwraca odpowiedzi zawierające linki do dalszych możliwych akcji, co pozwala na dynamiczne odkrywanie możliwości API.

---

Wersjonowanie API

Wersjonowanie API jest kluczowe, aby umożliwić zmiany w interfejsie bez przerywania działania starszych aplikacji korzystających z niego.

Najpopularniejsze metody wersjonowania to:

1. W URL-u
   • /v1/users /v2/users
     • Proste w użyciu i zrozumiałe, choć może prowadzić do nadmiarowości.
2. W nagłówkach HTTP:
   • GET /users Headers: X-API-Version: 1
     • Wygodne, ale mniej widoczne dla użytkowników.
3. W parametrach zapytania:
   • /users?version=1
     • Rzadziej stosowane, ale możliwe.

---

Konwencje nazewnicze w REST API

1. Zasoby w liczbie mnogiej:
   • ✅ /users
   • ❌ /user
2. Unikanie czasowników w nazwach zasobów:
   • ✅ /orders/123
   • ❌ /getOrder
3. Użycie identyfikatorów:
   • ✅ /products/456/reviews (podzasoby)
4. Czytelne nazwy:
   • Używaj czytelnych, krótkich i anglojęzycznych nazw zasobów.
5. HTTP status codes:
   • Zwracaj odpowiednie kody statusu:
     • 200 (OK),
     • 201 (Created),
     • 400 (Bad Request),
     • 404 (Not Found),
     • 500 (Internal Server Error).