Шпаргалка по RESTful API

1. Основные концепции (6 ограничений)

Чтобы система считалась RESTful, она должна соблюдать эти ограничения:

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

2. Нейминг ресурсов (URI Design)

Ресурс — это ключевое понятие (Существительное, а не Глагол).

3. HTTP Методы (Глаголы)

*Идемпотентность: Повторение одного и того же запроса много раз приводит к тому же состоянию сервера, что и однократный запрос. (Пример: Удалить запись ID 5 — сколько ни вызывай, записи 5 в итоге не будет).

4. Коды состояния HTTP (Status Codes)

2xx — Успех (Success)

• 200 OK: Стандартный успешный ответ (для GET, PUT, PATCH).
• 201 Created: Ресурс успешно создан (обычно ответ на POST). Должен включать заголовок Location.
• 202 Accepted: Запрос принят в обработку (фоновая задача), но не завершен.
• 204 No Content: Успешно, но тела ответа нет (часто для DELETE или PUT).

3xx — Перенаправление (Redirection)

• 301 Moved Permanently: Ресурс переехал навсегда (новый URL).
• 304 Not Modified: Ресурс не изменился (используется для кэширования).

4xx — Ошибки клиента (Client Error)

• 400 Bad Request: Невалидный запрос (ошибка валидации JSON и т.д.).
• 401 Unauthorized: Не аутентифицирован (нет токена или он неверен). Это про "Кто ты?".
• 403 Forbidden: Аутентифицирован, но нет прав. Это про "Что тебе можно?".
• 404 Not Found: Ресурс не найден.
• 405 Method Not Allowed: Метод не поддерживается (например, POST на /users/1).
• 409 Conflict: Конфликт состояния (например, создание дубликата email).
• 429 Too Many Requests: Превышен лимит запросов (Rate Limiting).

5xx — Ошибки сервера (Server Error)

• 500 Internal Server Error: Общая ошибка сервера (баг в коде, упала БД).
• 502 Bad Gateway: Неверный ответ от вышестоящего сервера (Nginx -> App).
• 503 Service Unavailable: Сервер перегружен или на обслуживании.

5. Форматирование запросов

Фильтрация, Сортировка, Пагинация

Используй Query Parameters (параметры строки запроса) для действий, не меняющих ресурс.

• Фильтрация: GET /users?role=admin&active=true
• Сортировка: GET /users?sort=-created_at (- для desc, + для asc)
• Пагинация: GET /users?page=2&limit=20 или ?offset=20&limit=10
• Поиск: GET /users?q=search_term
• Выбор полей: GET /users?fields=id,name,email

Заголовки (Headers)

• Content-Type: application/json — формат отправляемых данных.
• Accept: application/json — формат ожидаемого ответа.
• Authorization: Bearer <token> — передача токена доступа.

6. Версионирование

API меняется, но нельзя ломать старых клиентов.

1. URI Versioning (Самый частый): /api/v1/users
2. Header Versioning: Accept-version: v1
3. Media Type Versioning: Accept: application/vnd.myapi.v1+json

7. Структура JSON ответа (Best Practice)

Лучше всегда возвращать предсказуемую структуру.

Успех (GET Collection):

Ошибка:

8. HATEOAS (Hypermedia as the Engine of Application State)

Продвинутый уровень. Сервер возвращает не только данные, но и ссылки на возможные действия с ними.

Короткий чеклист для Code Review

1. URL — это существительные?
2. Используются правильные HTTP методы (GET не меняет данные)?
3. Возвращаются правильные статус-коды (не всегда 200)?
4. Вложенность ресурсов не глубже 2-3 уровней?
5. Есть пагинация для списков?
6. Даты в формате ISO 8601 (2023-10-05T14:48:00Z)?