REST API Style Guide
Свод правил для проектирования REST API: URL, ресурсы, ответы, ошибки, OpenAPI.
Свод правил для проектирования REST API: именование URL-путей, формат запросов и ответов, пагинация, обработка ошибок. Правила применимы к любому домену и стеку.
Содержание
| # | Раздел | Что внутри |
|---|---|---|
| 1-5 | URL и ресурсы | Общие принципы, формат URL, kebab-case, HTTP-методы, вложенность |
| 6-7 | Alias и Action-эндпоинты | me, latest, default; доменные команды |
| 8 | Версионирование и breaking changes | Версия в URL, что ломает контракт |
| 9 | Query-параметры и пагинация | Фильтрация, offset vs cursor, POST /search |
| 10-11 | JSON и формат ответов | camelCase, ISO 8601, null-поля, envelope |
| 12 | Заголовки и трассировка | Idempotency-Key, traceparent (W3C) |
| 13 | Ошибки RFC 9457 | Problem Details, violations, OpenAPI-схема |
| 14-16 | Rate limiting, файлы, deprecation | 429, multipart upload, Sunset |
| 17-19 | Batch, async, локализация | Массовые операции, polling, Accept-Language |
| 20-21 | OpenAPI-метаданные и антипаттерны | operationId, tags; типичные ошибки |
Как пользоваться
- Проектируете новый API? -- начните с разделов 1-5 и OpenAPI-метаданных
- Описываете ошибки? -- раздел 13 (RFC 9457) с готовой OpenAPI-схемой
- Ревью контракта? -- антипаттерны как чеклист
- Выпускаете новую версию? -- breaking changes и deprecation