Учебник REST API для начинающих

Программа курса

1. 1 Основы REST

   1. Что такое API и зачем он нужен

      API как контракт между системами: что это, зачем нужно, веб-API, клиент-сервер, HTTP как транспорт и форматы обмена данными — на простых примерах.

   2. REST: ресурсы, представления, stateless

      Что такое REST: ресурс против представления, шесть ограничений архитектуры, stateless подробно — почему сервер не хранит сессию, client-server и uniform interface.

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

      Модель зрелости Ричардсона: уровень 0 (один URI и POST), 1 (ресурсы), 2 (HTTP-глаголы и статусы), 3 (HATEOAS) — и где находится типичное REST API.

   4. REST против RPC: разница в мышлении

      REST против RPC: ресурсный стиль против действий-эндпоинтов, GET /users/1 вместо /getUser, когда уместен RPC и gRPC, плюсы и минусы каждого подхода.

2. 2 Ресурсы и URI

   1. Проектирование URI: существительные, не глаголы

      Как проектировать URI в REST API: ресурсы как существительные во множественном числе, kebab-case, единый стиль, регистр и почему /users лучше /getUsers.

   2. Коллекции, элементы и вложенные ресурсы

      Коллекция vs элемент в REST API, вложенные ресурсы /users/1/orders, разумная глубина вложенности и выбор идентификатора: числовой id или slug.

   3. Действия, не вписывающиеся в CRUD

      Как моделировать в REST API действия вне CRUD — опубликовать, отменить, пересчитать: под-ресурсы, флаги через PATCH, controller-ресурсы и прагматичный компромисс.

3. 3 HTTP-методы и коды статуса

   1. HTTP-методы и их семантика

      GET, POST, PUT, PATCH, DELETE в REST API: что каждый метод означает по контракту, что возвращать, когда нужно тело и чем PUT отличается от PATCH.

   2. Безопасность и идемпотентность методов

      Safe и идемпотентные HTTP-методы: почему GET/HEAD не меняют состояние, почему PUT/DELETE можно повторять, а POST — нет, и при чём тут ретраи.

   3. Коды статуса: 2xx/3xx/4xx/5xx

      HTTP-коды статуса в REST API: классы 2xx/3xx/4xx/5xx и ключевые коды 200, 201, 204, 301, 304, 400, 401, 403, 404, 409, 422, 429, 500, 503 — когда какой.

   4. Частые ошибки с методами и статусами

      Антипаттерны REST: 200 на ошибку, 404 vs 403 и раскрытие существования, 401 vs 403, неверный 500 на ошибку клиента, POST вместо PUT, тело в ответе 204.

4. 4 Запросы и ответы

   1. Форматы и JSON-конвенции, конверты ответа

      Content-Type и Accept, JSON по умолчанию, camelCase vs snake_case, даты в ISO 8601, конверт ответа data/meta/errors и null против отсутствия поля.

   2. Пагинация: offset и cursor

      Зачем нужна пагинация, offset/limit и его проблемы на больших смещениях, cursor/keyset, page-based, метаданные total и next, заголовки против тела.

   3. Фильтрация, сортировка, поиск

      Query-параметры для фильтрации, диапазоны price_gte, сортировка sort=-created_at, выбор полей fields, полнотекстовый q, валидация, дефолты и контроль сложности.

5. 5 Эволюция API и ошибки

   1. Версионирование API

      Зачем версионировать REST API и как: версия в URL, в заголовке Accept, в query. Плюсы и минусы стратегий, семантическое версионирование.

   2. Обработка ошибок: единый формат и RFC 7807

      Единый формат ошибок REST API: поля code, message, details. Стандарт Problem Details RFC 7807, application/problem+json, ошибки валидации.

   3. Обратная совместимость и deprecation

      Что ломает обратную совместимость REST API, принцип толерантного читателя, процесс deprecation: заголовки Deprecation и Sunset, changelog, миграция.

6. 6 Безопасность и контроль доступа

   1. Аутентификация и авторизация

      Authn против authz в REST API: API-ключи, структура JWT (header.payload.signature), Bearer-токен, обзор OAuth2 и безопасное хранение токена на клиенте.

   2. Ограничение частоты (rate limiting)

      Rate limiting в REST API: зачем нужен, алгоритмы fixed/sliding window и token bucket, код 429, заголовки X-RateLimit и Retry-After, корректный backoff клиента.

   3. Кэширование: ETag и Cache-Control

      Кэширование в REST API: Cache-Control (max-age, no-store, private/public), валидаторы ETag и Last-Modified, условные запросы If-None-Match → 304 и If-Match → 412.

   4. Безопасность API: OWASP, CORS, HTTPS

      Безопасность REST API: OWASP API Top 10 (BOLA, broken auth, excessive data exposure, mass assignment), валидация входа, обязательный HTTPS и механика CORS с preflight.

7. 7 Продвинутое проектирование

   1. HATEOAS и гиперссылки: нужно ли

      HATEOAS и уровень 3 модели Ричардсона: ссылки в ответе, форматы HAL и JSON:API, плюсы обнаруживаемости и минусы сложности, прагматичный вывод.

   2. Идемпотентность на практике: Idempotency-Key и webhooks

      Двойные POST в платежах и заголовок Idempotency-Key: как сервер дедуплицирует запросы. Webhooks: подписка, доставка, ретраи, HMAC-подпись, идемпотентность.

   3. Проектирование под фронтенд: overfetching и GraphQL

      Overfetching и underfetching в REST: лишние поля и водопад запросов. Приёмы ?fields=, ?expand=, составные эндпоинты, BFF и связь с GraphQL.

8. 8 Документация, тестирование и выбор стиля

   1. Документация: OpenAPI и Swagger

      OpenAPI (бывший Swagger) как машинночитаемый контракт REST API: структура спеки, Swagger UI и Redoc, design-first против генерации из кода.

   2. Тестирование API: Postman и контрактные тесты

      Как тестировать REST API: ручная проверка в Postman, автотесты статусов и схем, контрактные тесты по идее Pact, edge cases и smoke в CI.

   3. REST vs GraphQL vs gRPC и чек-лист хорошего API

      Сравнение REST, GraphQL и gRPC: ресурсы и кэш против гибкой выборки и бинарного protobuf. Когда что выбирать и финальный чек-лист хорошего REST API.