REST

REST (Representational State Transfer) — архитектурный стиль от Roy Fielding (диссертация 2000 г.). Про использование HTTP по-настоящему: ресурсы, методы, коды, гипермедиа. Большинство "REST API" в реальности — не REST, а RPC поверх HTTP.

6 принципов Филдинга

1. Client-Server — разделение UI и данных
2. Stateless — каждый запрос содержит всё необходимое
3. Cacheable — ответы могут кешироваться
4. Uniform Interface — единый интерфейс: URI + методы + типы
5. Layered System — прокси, CDN прозрачны
6. Code on Demand (опционально) — сервер может отдать JS

Уровни зрелости Ричардсона

Типовой ресурсный дизайн

GET    /articles           список
POST   /articles           создать
GET    /articles/42        один
PUT    /articles/42        заменить
PATCH  /articles/42        обновить
DELETE /articles/42        удалить

GET    /articles/42/comments      подколлекция
POST   /articles/42/comments      добавить коммент

HATEOAS

В ответе — ссылки на возможные действия. Клиент не должен знать URL-схему заранее.

{
  "id": 42,
  "title": "Hello",
  "_links": {
    "self":     { "href": "/articles/42" },
    "comments": { "href": "/articles/42/comments" },
    "publish":  { "href": "/articles/42/publish", "method": "POST" }
  }
}

HATEOAS почти никто не делает. GraphQL, JSON:API, HAL — попытки решить.

Спецификации

• JSON:API — жёсткий контракт JSON REST
• HAL — Hypertext Application Language
• OData — Microsoft OData
• OpenAPI (Swagger) — не спека REST, а описание любого HTTP API

REST vs GraphQL vs gRPC

См. также

• API, GraphQL, GET, POST, методы