🛰️ REST API

Принципы REST, HTTP-методы, коды ответов, проектирование путей, пагинация и ошибки.

Шпаргалки · Аналитика · #rest #api #http #web

Принципы

REST (Representational State Transfer) это стиль API поверх HTTP: ресурсы с адресами, стандартные методы, без хранения состояния клиента на сервере (stateless).

Методы

Дизайн путей

GET    /users                  список
GET    /users/42               один
POST   /users                  создать
PUT    /users/42               заменить
PATCH  /users/42               изменить поля
DELETE /users/42               удалить
GET    /users/42/orders        вложенный ресурс
GET    /orders?status=paid&sort=-created&limit=20&page=2

Существительные во множественном числе, без глаголов в пути, нижний регистр, дефисы.

Коды ответов

Запрос и ответ

POST /users HTTP/1.1
Host: api.example.com
Authorization: Bearer <token>
Content-Type: application/json

{ "name": "Аня", "email": "a@x.ru" }

HTTP/1.1 201 Created
Location: /users/42
Content-Type: application/json

{ "id": 42, "name": "Аня", "email": "a@x.ru" }

Формат ошибки

{ "error": { "code": "VALIDATION", "message": "Некорректный email", "details": [{ "field": "email" }] } }

Стандарт: RFC 9457 (application/problem+json).

Практики

• Версионирование: /v1/users или заголовок.
• Пагинация: limit/offset, курсор (next_cursor) для больших выборок.
• Идемпотентность для POST платежей: заголовок Idempotency-Key.
• Кэширование: ETag, Cache-Control.
• Безопасность: HTTPS, токены (OAuth 2.0, JWT), ограничение частоты, валидация входа.
• HATEOAS (ссылки в ответах) на практике используют редко.