проектирование REST API: как это работает на практике

REST: ресурсы — существительные в URL, действия — HTTP-методы, statelessness и честные status codes. Cross-cutting concerns — query params и headers, не новые endpoints.

Разбор

Resources are nouns. URL — множественные коллекции (/users, не /user) с ID для members (/users/7). Глаголы в URL (/getUser, /users/7/delete) — антипаттерн: метод уже несёт verb, path ломает кэш (GET /deleteUser cacheable и prefetchable).

Statelessness. Каждый request несёт всё нужное серверу — обычно Authorization token — сервер не держит session между вызовами. Это позволяет любой server за load balancer без sticky session.

Status codes честно. 201 для create (+ Location), 204 для delete без body, 400/422 для bad input, 401 vs 403, 409 для conflicts, 429 для rate limits. 200 { "error": ... } для всего выбрасывает главную фичу HTTP.

Cross-cutting concerns как params & headers:

• Filtering/sorting/pagination: GET /orders?status=paid&sort=-created&limit=20&cursor=…
• Versioning: /v2/orders (просто, cache-friendly) или Accept header. URL versioning выигрывает в debuggability.
• Idempotency: POST не идемпотентен — принимайте Idempotency-Key, чтобы retry create не double-charge.

Слабость REST: chattiness. Dashboard = GET /user, потом GET /user/orders, потом items для каждого — N+1 / waterfall. Каждый endpoint — fixed shape → mobile over-fetch. Именно это лечат GraphQL и BFF.

Итог

Хороший REST предсказуем: nouns + verbs HTTP, status codes и idempotency keys; chattiness — сигнал, что пора BFF или GraphQL.