REST - zasady projektowania API

REST (Representational State Transfer) to styl architektoniczny definiujacy zasady projektowania rozproszonych systemow, w szczegolnosci API webowych. Został zdefiniowany przez Roya Fieldinga w jego rozprawie doktorskiej w 2000 roku. REST nie jest protokołem ani standardem - to zbior ograniczeń architektonicznych, które gdy sa przestrzegane, prowadza do tworzenia skalowalnych i elastycznych systemow.

Współczesne aplikacje webowe intensywnie korzystaja z API RESTful do komunikacji miedzy frontendem a backendem, integracji z usługami zewnetrznymi oraz budowania mikrouslug.

W REST wszystko jest zasobem (resource). Zasob to dowolna informacja, która może być nazwana - użytkownik, produkt, zamowienie. Każdy zasob ma unikalny identyfikator URI (Uniform Resource Identifier).

REST wykorzystuje standardowe metody HTTP do wykonywania operacji CRUD na zasobach:

1. GET - Pobieranie zasobow

   Pobiera reprezentacje zasobu. Jest bezpieczna (safe) i idempotentna - wielokrotne wywołanie daje ten sam wynik.

2. POST - Tworzenie zasobow

   Tworzy nowy zasob w kolekcji. Nie jest idempotentna - każde wywołanie tworzy nowy zasob.

3. PUT - Aktualizacja zasobow

   Zastepuje cały zasob nowa wersja. Jest idempotentna - wielokrotne wywołanie z tymi samymi danymi daje ten sam wynik.

4. PATCH - Czesciowa aktualizacja

   Modyfikuje tylko wybrane pola zasobu. Przydatne gdy nie chcemy wysyłać całego obiektu.

5. DELETE - Usuwanie zasobow

   Usuwa zasob. Jest idempotentna - usuniecie już usunietego zasobu nie zmienia stanu.

Idempotentnosc to kluczowa właściwość w REST. Operacja jest idempotentna, jeśli wielokrotne jej wykonanie daje ten sam rezultat co pojedyncze wykonanie.

*PATCH może być idempotentna w zależności od implementacji.

GET    /api/users          - lista użytkowników
GET    /api/users/123      - szczegóły użytkownika 123
POST   /api/users          - utworzenie nowego użytkownika
PUT    /api/users/123      - aktualizacja użytkownika 123
DELETE /api/users/123      - usuniecie użytkownika 123

// Pobranie listy użytkowników
fetch('/api/users')
  .then(response => response.json())
  .then(data => console.log(data));

// Pobranie pojedynczego użytkownika
fetch('/api/users/123')
  .then(response => {
    if (!response.ok) {
      throw new Error(`HTTP error! status: ${response.status}`);
    }
    return response.json();
  })
  .then(user => console.log(user));

fetch('/api/users', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    name: 'Jan Kowalski',
    email: 'jan@example.com'
  })
})
.then(response => response.json())
.then(newUser => console.log('Utworzono:', newUser));

{
  "id": 123,
  "name": "Jan Kowalski",
  "email": "jan@example.com",
  "createdAt": "2024-01-15T10:30:00Z",
  "links": {
    "self": "/api/users/123",
    "orders": "/api/users/123/orders"
  }
}

// POST - tworzenie nowego zasobu (serwer przydziela ID)
POST /api/users
{ "name": "Anna Nowak" }
// Odpowiedz: 201 Created, Location: /api/users/124

// PUT - zastapienie zasobu o znanym ID
PUT /api/users/124
{ "name": "Anna Nowak-Kowalska", "email": "anna@example.com" }
// Odpowiedz: 200 OK

REST jest odpowiedni gdy:

• Budujesz publiczne API dla zewnętrznych deweloperow
• Potrzebujesz prostej, stateless komunikacji
• Twoja aplikacja operuje na jasno zdefiniowanych zasobach
• Wymagasz dobrej cachowalnosci i skalowalnosci
• Integrujesz różne systemy przez HTTP

REST to sprawdzony styl architektoniczny dla API webowych, który gdy jest prawidłowo zaimplementowany, prowadzi do tworzenia skalowalnych, elastycznych i łatwo utrzymywalnych systemow. Kluczowe zasady to bezstanowość, jednolity interfejs oparty na zasobach i metodach HTTP oraz prawidłowe wykorzystanie kodow odpowiedzi.

Najważniejsze do zapamietania:

• REST to styl architektoniczny, nie protokół
• Zasoby identyfikowane przez URI, operacje przez metody HTTP
• Bezstanowość umozliwia skalowanie
• Idempotentnosc ważna dla niezawodnosci