REST API to kelner w restauracji

// Klient (Ty, klient przy stoliku)
const odpowiedz = await fetch('https://api.restauracja.pl/menu');
const menu = await odpowiedz.json();
console.log(menu);
// { dania: ['pizza', 'pasta', 'sushi'], ceny: [35, 28, 42] }

REST jako styl architektoniczny #

REST nie jest protokołem. To zestaw ograniczeń opisanych przez Roya Fieldinga (2000). System który je spełnia dostaje konkretne własności: skalowalność, cache’owalność, prostotę ewolucji.

Sześć ograniczeń:

1. Client-Server - separacja UI od storage.
2. Stateless - każdy request zawiera cały kontekst, serwer nie trzyma sesji.
3. Cacheable - odpowiedzi oznaczają czy wolno je cache’ować.
4. Uniform interface - identyfikacja zasobów przez URI, manipulacja przez reprezentacje (JSON/XML), self-descriptive messages, HATEOAS.
5. Layered system - klient nie wie czy gada z serwerem końcowym czy proxy.
6. Code on demand (opcjonalne) - serwer może wysłać kod do wykonania.

W praktyce 99% “REST API” spełnia 4-5 z 6 (stateless + uniform interface to minimum). HATEOAS rzadko.

HTTP methods - semantyka #

Metoda	Idempotent	Safe	Typowe użycie
GET	tak	tak	odczyt zasobu, bez side effectów
HEAD	tak	tak	metadata (Content-Length, Last-Modified) bez body
POST	nie	nie	utworzenie zasobu, operacja bez naturalnego ID
PUT	tak	nie	zastąpienie zasobu (pełne)
PATCH	nie (zwykle)	nie	modyfikacja częściowa (JSON Patch / JSON Merge Patch)
DELETE	tak	nie	usunięcie zasobu

Idempotent = wielokrotne wywołanie daje ten sam efekt (klient może retry-ować bez skutków ubocznych). Safe = brak zmiany stanu serwera.

Status codes - używaj semantycznie #

Kod	Znaczenie
200 OK	sukces z body
201 Created	zasób utworzony, Location: /orders/42
204 No Content	sukces bez body (DELETE, PUT)
301 / 308	permanent redirect
400 Bad Request	klient wysłał niepoprawne dane
401 Unauthorized	brak / zły token
403 Forbidden	token OK, ale brak uprawnień
404 Not Found	zasób nie istnieje
409 Conflict	konflikt (np. unique constraint)
422 Unprocessable Entity	walidacja biznesowa
429 Too Many Requests	rate limit
500 Internal Server Error	błąd po stronie serwera
503 Service Unavailable	chwilowa niedostępność

Anti-pattern: 200 OK z {"success": false, "error": ...} w body. Używaj kodów statusu zgodnie z ich znaczeniem - pośrednicy (proxy, monitoring, retry) zależą od tego.

ASP.NET Core minimal API #

// title: Program.cs
var builder = WebApplication.CreateBuilder(args);
builder.Services.AddScoped<IOrderRepository, OrderRepository>();
builder.Services.AddProblemDetails();   // RFC 7807 error format

var app = builder.Build();

app.MapGet("/orders/{id:int}", async (int id, IOrderRepository repo) =>
{
    var order = await repo.GetAsync(id);
    return order is null ? Results.NotFound() : Results.Ok(order);
})
.WithName("GetOrder")
.Produces<Order>()
.Produces(StatusCodes.Status404NotFound);

app.MapPost("/orders", async (CreateOrderRequest req, IOrderRepository repo) =>
{
    var id = await repo.CreateAsync(req);
    return Results.CreatedAtRoute("GetOrder", new { id }, req);
})
.WithName("CreateOrder");

app.Run();

Uwagi:

• Binding z path / query / body dzieje się automatycznie.
• Results.* zwraca IResult - typesafe mapowanie na status code + body.
• WithName ustawia ID operacji (używane przez CreatedAtRoute, OpenAPI).

Idempotency keys #

POST nie jest idempotentny, ale pewne operacje (płatności, utworzenie zasobu) muszą być bezpieczne do retry. Wzorzec: klient generuje Idempotency-Key (UUID), serwer zapisuje (key, response) w cache. Drugi request z tym samym key zwraca cached response.

app.MapPost("/payments", async (HttpContext ctx, PaymentRequest req, IIdempotencyStore store) =>
{
    var key = ctx.Request.Headers["Idempotency-Key"].ToString();
    if (store.TryGet(key, out var cached)) return Results.Json(cached);

    var result = await ProcessPayment(req);
    store.Save(key, result, TimeSpan.FromHours(24));
    return Results.Ok(result);
});

Wersjonowanie #

Trzy popularne strategie:

1. URL path - /v1/orders, /v2/orders. Proste, widoczne.
2. Accept header - Accept: application/vnd.company.v2+json. Czystsze URI, trudniejsze testowanie przez curl.
3. Query param - /orders?api-version=2. Rzadziej, kompromis.

W ASP.NET Core - pakiet Asp.Versioning.Http.

Breaking vs non-breaking:

• Non-breaking: dodanie opcjonalnego pola, dodanie endpointu, rozszerzenie enum.
• Breaking: usunięcie pola, zmiana typu, zmiana semantyki error responses.

Zasada: nigdy nie usuwaj pola bez deprecation cycle (6-12 miesięcy), nawet jeśli “nikt tego nie używa”.

Paginacja #

• Offset-based - ?page=3&size=20. Prosto, ale wolne dla dużych offsetów (SQL OFFSET skanuje pominięte wiersze) i niestabilne przy insertach.
• Cursor-based - ?after=eyJpZCI6MTAwfQ==. Stabilne, O(log n), nie pozwala na “skok na stronę 500”.

Dla logów, feedów - cursor. Dla tabel administracyjnych - offset bywa OK.

OpenAPI / Swagger #

Dokumentacja machine-readable. W ASP.NET Core od .NET 9 wbudowane przez Microsoft.AspNetCore.OpenApi:

builder.Services.AddOpenApi();
app.MapOpenApi();  // /openapi/v1.json

OpenAPI spec daje: contract testing, generację klientów (NSwag, openapi-generator), UI do eksploracji (Swagger UI, Scalar).

Error format - RFC 7807 Problem Details #

{
  "type": "https://api.example.com/errors/out-of-stock",
  "title": "Out of stock",
  "status": 409,
  "detail": "Product SKU-42 has insufficient inventory.",
  "instance": "/orders/5123",
  "available": 0
}

Standardowy format, rozszerzalny. ASP.NET Core ma builtin (AddProblemDetails + IProblemDetailsService).

Pułapki #

• Chunky APIs - zbyt wiele round-tripów (klient pobiera user, potem orders, potem items). Rozwiązanie: projekcja (/users/42?include=orders), GraphQL, sparse fieldsets.
• Overfetching - 100kB JSON kiedy klient chce 3 pola. Projekcja / pagination / field selection.
• Chatty auth - weryfikacja tokenu w każdym serwisie osobno, synchronicznie. Rozwiązanie: validate lokalnie (JWKS cache), centralizuj tylko issuance.
• Breaking changes bez wersji - jeden deployment psuje wszystkich klientów. Wersjonuj od pierwszego dnia.

Skrótowo #

REST to nie JSON nad HTTP - to statelessness, uniform interface, proper HTTP semantics. Używaj metod i statusów zgodnie z ich znaczeniem, wersjonuj od początku, dokumentuj przez OpenAPI, błędy zwracaj w Problem Details. W ASP.NET Core minimal API - kilka linii, cała semantyka działa z pudełka.