REST API и OpenAPI: урок по Системный анализ к собеседованию

Контракт API это договор между системами. Аналитик проектирует его до кода: ресурсы, методы, поля, ошибки. Хороший контракт разработчики реализуют без вопросов, а смежная команда интегрируется по нему, не дожидаясь готового сервиса.

Принципы REST

REST (Рой Филдинг, 2000) это архитектурный стиль: клиент-сервер, отсутствие состояния на сервере между запросами (stateless), кешируемость, единообразный интерфейс, слоистая система. На практике «REST API» значит: ресурсы адресуются URL, действия выражаются HTTP-методами.

Ресурсы и URL

Существительные во множественном числе: /orders, /orders/{id}, /orders/{id}/items.
Глаголы в URL плохо: /getOrders, /createOrder.
Действие, которое не ложится на CRUD, оформляют подресурсом: POST /orders/{id}/cancel или меняют статус PATCH /orders/{id} { "status": "cancelled" }.

Методы

Метод	Смысл	Безопасный	Идемпотентный
GET	прочитать	да	да
POST	создать, запустить действие	нет	нет
PUT	заменить целиком	нет	да
PATCH	изменить часть	нет	не гарантирован
DELETE	удалить	нет	да

Идемпотентность: повтор запроса даёт тот же эффект на сервере, что и один. Важно при ретраях: сеть оборвалась, клиент не знает, создан ли платёж. Для POST вводят заголовок Idempotency-Key: сервер запоминает ключ и на повтор возвращает прежний результат.

Статусы

200 OK, 201 Created (+ Location), 204 No Content.
400 некорректный запрос, 401 не аутентифицирован, 403 нет прав, 404 нет ресурса, 409 конфликт состояния (заказ уже отменён), 422 данные не прошли бизнес-валидацию, 429 слишком много запросов.
500 ошибка сервера, 502/504 проблема шлюза или таймаут вышестоящего, 503 недоступен.

Формат ошибки единый для всего API, например RFC 9457 (Problem Details): type, title, status, detail, плюс свои поля (код ошибки, список невалидных полей).

Пагинация, фильтры, сортировка

Offset: ?limit=20&offset=40. Просто, но медленно на больших смещениях и «прыгает» при вставках.
Cursor (keyset): ?limit=20&after=eyJpZCI6MTIzfQ. Стабильно и быстро, нельзя перейти на страницу 57.
Фильтры и сортировка в query: ?status=paid&sort=-created_at.

Версионирование и совместимость

Версия в пути /v1/ или в заголовке.
Обратно совместимые изменения: новое необязательное поле в ответе, новый эндпоинт, новый необязательный параметр.
Ломающие: удалить или переименовать поле, сменить тип, сделать поле обязательным в запросе, изменить смысл. Требуют новой версии и периода поддержки старой.

OpenAPI

OpenAPI (актуальная ветка 3.1, вышла 3.2) описывает REST API в YAML или JSON: пути, параметры, тела запросов и ответов, схемы (JSON Schema), безопасность. Из спецификации генерируют документацию (Swagger UI, Redoc), клиентов, серверные заглушки, моки и контрактные тесты.

paths:
  /orders/{id}:
    get:
      summary: Получить заказ
      parameters:
        - name: id
          in: path
          required: true
          schema: { type: string, format: uuid }
      responses:
        '200':
          content:
            application/json:
              schema: { $ref: '#/components/schemas/Order' }
        '404':
          description: Заказ не найден

Подход API first (design first): сначала контракт, ревью, моки, потом код.

Безопасность (что знать аналитику)

Аутентификация: OAuth 2.0 + токены (JWT), API-ключи для сервер-сервер, mTLS.
Авторизация на уровне объекта: клиент не должен получить чужой заказ, подставив id. Это самая частая уязвимость API по OWASP API Security Top 10 (BOLA).
Не класть персональные данные и токены в URL: они оседают в логах.

Частые ошибки

200 с {"error": "..."} в теле.
Глаголы в путях и разные стили именования (order_id и orderId в одном API).
Деньги числом с плавающей точкой (лучше строка-десятичное или целые копейки + валюта).
Нет пагинации у списков.
Дата без часового пояса (используйте ISO 8601 с зоной: 2026-03-01T10:00:00+03:00).

Что спросят на собесе

Что такое REST? Какие ограничения он накладывает?
Чем PUT отличается от PATCH? Что такое идемпотентность?
Какой статус вернуть, если заказ уже отменён, а его отменяют повторно?
Как сделать безопасный повтор создания платежа?
Какие изменения API ломают клиентов?

REST API и OpenAPI для аналитика