Кратко и по существу — дизайн REST API для библиотеки с версионированием, аутентификацией, пагинацией и обработкой ошибок, плюс необходимые компромиссы.
1) Версионирование
- Основная схема: URI-versioning — примеры путей `/api/v$1$/books`, `/api/v$1$/members`.
- Плюсы: простота, кэширование, прозрачность для клиентов.
- Минусы: URL меняется при мажорных изменениях.
- Дополнительно поддержать header-based для эволюции (Accept: `application/vnd.mylib.v$2$+json`) — использовать только для минорных запусков, если хотим избегать изменения URL.
- Политика: мажорные нес назад-совместимые изменения → новая версия в URI; обратная совместимость — через заголовки/feature flags.
2) Аутентификация и авторизация
- Протокол: OAuth $2.0$ с Bearer JWT для ресурса (stateless).
- Access token lifetime: $15\text{min}$ (пример).
- Refresh token lifetime: $7\text{days}$.
- Scopes/roles: `scope=books:write`, `members:read` и роли (`librarian`, `member`).
- Реvoke: хранить blacklist/allowlist для refresh-токенов и короткий TTL для access JWT (чтобы не держать долгосрочные JWT).
- Защищённые эндпоинты требуют заголовок `Authorization: Bearer `.
3) Ресурсы и основные эндпоинты (пример)
- Books:
- GET `/api/v$1$/books` — список (пагинация).
- POST `/api/v$1$/books` — создать (`201`).
- GET `/api/v$1$/books/{id}` — получить.
- PATCH `/api/v$1$/books/{id}` — частичное обновление.
- DELETE `/api/v$1$/books/{id}` — удалить (`204`).
- Authors, Members, Loans, Reservations — аналогично CRUD; для выдач/возвратов использовать POST `/api/v$1$/loans` и PATCH `/api/v$1$/loans/{id}/return`.
Статусы: успешные ответы — `200/201/204`; ошибки подробно ниже. (см. секцию ошибок)
4) Пагинация
- Рекомендуемый дефолт: cursor-based pagination (для масштабируемых списков).
- Параметры: `?limit=&cursor=`
- Дефолты/ограничения: `limit` default $20$, max $100$.
- Ответная обёртка:
{
"items": [ ... ],
"next_cursor": "",
"has_more": true|false,
"meta": { "limit": }
}
- Причина: курсор даёт стабильность при изменениях данных, лучше чем offset при больших таблицах.
- Для простых внутренних или админских запросов можно поддержать offset/limit (совместимость): `?offset=&limit=` — компромисс простоты.
5) Схема ошибок (единый формат)
- Формат ответа при ошибке (пример полей):
{
"status": ,
"error_code": "string_machine_code",
"message": "Читабельное сообщение",
"details": [ { "field": "title", "message": "required" } ],
"trace_id": "uuid"
}
- Маппинг HTTP-статусов: $200$, $201$, $204$, $400$ (validation), $401$ (unauth), $403$ (forbidden), $404$ (not found), $409$ (conflict), $422$ (semantic), $429$ (rate limit), $500$ (server).
- `trace_id` — для логирования и поддержки; возвращать клиенту для обращения в поддержку.
6) Кэширование, conditional requests
- ETag/If-None-Match и Last-Modified для GET отдельных сущностей (уменьшает нагрузку).
- Cache-Control для публичных/неличных ресурсов.
- Для списков при cursor-пагинации кэш сложнее — использовать short TTL.
7) Rate limiting и мониторинг
- Rate limit headers: `X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset`.
- При превышении возвращать $429$ с объяснением и `retry_after`.
8) Дополнительно: валидация/идемпотентность
- PUT/PATCH/POST: поддерживать idempotency-key для критичных операций (создание заказов/резервов).
- Конфликты версий — использовать ETag + `If-Match` для безопасного обновления → возвращать $409$ при конфликте.
9) Лёгкие примеры ответов/заголовков (пояснительно)
- Создание книги → HTTP $201$, Location `/api/v$1$/books/{id}`
- Ошибка валидации → HTTP $400$ с телом по схеме ошибок.
- Список (cursor) → HTTP $200$ + body { "items": [...], "next_cursor": "abc" }.
10) Компромиссы (кратко)
- URI-versioning vs header-versioning: выбираю URI как основной (простота, кэширование); header — опция для мягкой эволюции (сложность для клиентов).
- Offset vs cursor: выбираю cursor как основной (масштабируемость, консистентность); поддержу offset для простоты тестов/админки.
- JWT stateless vs centralized sessions: JWT — простота и производительность; но сложнее отзыв — решается коротким TTL + refresh/revoke store.
- HATEOAS/JSON:API vs простые JSON-ресурсы: простые JSON быстрее принять и проще использовать; если требуется строгая совместимость/эволюция — рассмотреть JSON:API или OpenAPI/graphQL позже.
- Полная типизация контрактов (OpenAPI) — требуется время, но даёт автогенерацию клиентов; компромисс — начать с минимального OpenAPI и расширять.
Резюме (рекомендация)
- Использовать URI-versioning `/api/v$1$/...`, OAuth $2.0$/JWT, cursor-based pagination (limit default $20$, max $100$), единый error schema с `trace_id`, поддерживать ETag и rate-limit headers. Это даёт баланс между простотой использования и возможностью масштабной эволюции API.
Если нужно — пришлю пример OpenAPI-спецификации для начального набора эндпоинтов.