Форматы ответов API: лучшие практики для согласованных API
Несогласованные ответы API — одна из главных жалоб фронтенд-разработчиков. Когда каждый эндпоинт возвращает данные в разной структуре, клиентский код обрастает множеством частных случаев. Единый формат ответа улучшает опыт разработчика, сокращает количество ошибок и делает ваш API самодокументируемым.
Обёртка ответа
Оборачивайте каждый ответ в единообразную структуру:
Успешный ответ (единичный ресурс)
{
"data": {
"id": "user_123",
"name": "Alice",
"email": "[email protected]",
"createdAt": "2024-01-15T10:30:00Z"
},
"meta": {
"requestId": "req_abc123"
}
}
Успешный ответ (коллекция)
{
"data": [
{ "id": "user_123", "name": "Alice" },
{ "id": "user_456", "name": "Bob" }
],
"meta": {
"total": 142,
"page": 1,
"perPage": 20,
"requestId": "req_def456"
}
}
Ошибка
{
"error": {
"code": "VALIDATION_ERROR",
"message": "Request validation failed",
"details": [
{ "field": "email", "message": "Invalid email format" }
]
},
"meta": {
"requestId": "req_ghi789"
}
}
Ключевой принцип: клиент всегда проверяет наличие data или error на верхнем уровне. Никогда не смешивайте данные об успешном выполнении и информацию об ошибке в одном ответе.
Проверьте формат вашего ответа с помощью нашего JSON Валидатора.
Коды состояния HTTP
Используйте коды состояния правильно — это первое, что проверяет клиент:
Коды успеха
| Код | Когда использовать |
|---|---|
| 200 OK | Успешный GET, PUT/PATCH |
| 201 Created | POST, создавший ресурс |
| 204 No Content | Успешный DELETE (без тела ответа) |
Коды ошибок клиента
| Код | Когда использовать |
|---|---|
| 400 Bad Request | Некорректный синтаксис запроса |
| 401 Unauthorized | Отсутствует или недействительна аутентификация |
| 403 Forbidden | Аутентифицирован, но не авторизован |
| 404 Not Found | Ресурс не существует |
| 409 Conflict | Конфликт состояния ресурса (дубликат) |
| 422 Unprocessable | Синтаксис корректен, но семантические ошибки |
| 429 Too Many Requests | Превышен лимит запросов |
Коды ошибок сервера
| Код | Когда использовать |
|---|---|
| 500 Internal Server Error | Неожиданный сбой сервера |
| 502 Bad Gateway | Сбой вышестоящего сервиса |
| 503 Service Unavailable | Временная перегрузка или обслуживание |
Проектирование ответов об ошибках
Хорошие ответы об ошибках помогают разработчикам быстро находить причину проблемы:
{
"error": {
"code": "RESOURCE_NOT_FOUND",
"message": "User with ID 'user_999' not found",
"details": [],
"documentationUrl": "https://api.example.com/docs/errors#RESOURCE_NOT_FOUND"
},
"meta": {
"requestId": "req_xyz789",
"timestamp": "2024-01-15T10:30:00Z"
}
}
Правила:
code— машиночитаемый код (постоянная строка, не HTTP-статус)message— человекочитаемое сообщение (может измениться без нарушения работы клиентов)details— ошибки на уровне полей при провале валидацииrequestId— позволяет службе поддержки отследить запрос в логах
Шаблоны пагинации
На основе смещения
Простая реализация, поддерживает переход к произвольной странице:
{
"data": ["..."],
"meta": {
"page": 2,
"perPage": 20,
"total": 142,
"totalPages": 8
},
"links": {
"first": "/api/users?page=1&per_page=20",
"prev": "/api/users?page=1&per_page=20",
"next": "/api/users?page=3&per_page=20",
"last": "/api/users?page=8&per_page=20"
}
}
На основе курсора
Лучше подходит для данных в реальном времени и больших наборов данных:
{
"data": ["..."],
"meta": {
"hasNext": true,
"hasPrev": true
},
"links": {
"next": "/api/users?cursor=eyJpZCI6MTQzfQ&limit=20",
"prev": "/api/users?cursor=eyJpZCI6MTIzfQ&limit=20&direction=prev"
}
}
Дата и время
Всегда используйте ISO 8601 с указанием часового пояса:
{
"createdAt": "2024-01-15T10:30:00Z",
"updatedAt": "2024-01-15T14:22:33+00:00",
"expiresAt": "2024-12-31T23:59:59Z"
}
Чего следует избегать:
- Unix-временные метки (неоднозначно: секунды или миллисекунды?)
- Локальные даты без часового пояса
- Нестандартные форматы вроде MM/DD/YYYY
Подробнее о работе с временными метками читайте в нашем руководстве по Unix Timestamps.
Null против отсутствующих полей
Два распространённых подхода:
Включать со значением null (явный):
{ "name": "Alice", "avatar": null, "bio": null }
Опускать отсутствующие поля (разреженный):
{ "name": "Alice" }
Рекомендация: Будьте последовательны в рамках вашего API. Явные значения null лучше для типизированных языков (клиенты знают, что поле существует). Разреженный формат лучше для сред с ограниченной пропускной способностью.
Версионирование ответов
Когда формат ответа меняется, используйте версионирование API:
GET /api/v2/users/123
Ломающие изменения, требующие версионирования:
- Удаление поля
- Изменение типа поля
- Переименование поля
- Изменение структуры обёртки ответа
Неломающие изменения (безопасны без версионирования):
- Добавление новых полей
- Добавление новых эндпоинтов
- Добавление новых значений перечислений
FAQ
Стоит ли оборачивать успешные ответы в ключ data или возвращать ресурс напрямую?
Использование обёртки data обеспечивает единообразную структуру для всех ответов и оставляет место для метаданных, пагинации и ссылок рядом с данными. Прямой возврат ресурса проще для эндпоинтов с одним ресурсом. Большинство современных API используют подход с обёрткой ради согласованности.
Как обрабатывать частичные сбои в пакетных операциях?
Возвращайте 200 с ответом, который включает как успешные, так и неудачные результаты в объекте data. Использование 207 Multi-Status (WebDAV) — альтернативный вариант, но он реже применяется в REST API.
Именование ресурсов
Ресурсы — это существительные, а не глаголы. Используйте существительные во множественном числе для коллекций и отдельные ресурсы через ID:
GET /api/users # Список пользователей
POST /api/users # Создать пользователя
GET /api/users/123 # Получить пользователя 123
PUT /api/users/123 # Обновить пользователя 123
DELETE /api/users/123 # Удалить пользователя 123
Соглашения об именовании:
- Используйте строчные буквы с дефисами:
/api/blog-posts(неblogPostsи неblog_posts) - Вкладывайте связанные ресурсы:
/api/users/123/orders - Ограничивайте вложенность 2 уровнями:
/api/users/123/orders/456(не глубже) - Избегайте глаголов в URL:
/api/users/123/activateдопустимо для действий, не соответствующих CRUD
Фильтрация и сортировка
Фильтрация
GET /api/users?status=active&role=admin
GET /api/users?created_after=2024-01-01
GET /api/users?search=alice
Для сложных фильтров рассмотрите выделенный параметр запроса:
GET /api/users?filter[status]=active&filter[role]=admin
Сортировка
GET /api/users?sort=name # По возрастанию
GET /api/users?sort=-created_at # По убыванию (префикс -)
GET /api/users?sort=-created_at,name # Несколько полей
Ограничение частоты запросов
Сообщайте лимиты запросов в заголовках ответа:
X-RateLimit-Limit: 100
X-RateLimit-Remaining: 67
X-RateLimit-Reset: 1705312800
Retry-After: 30
Возвращайте 429 Too Many Requests при превышении лимита с чётким сообщением об ошибке и заголовком Retry-After.
HATEOAS (необязательный, но мощный)
Включайте ссылки на связанные ресурсы и действия:
{
"data": {
"id": "123",
"name": "Alice",
"links": {
"self": "/api/users/123",
"orders": "/api/users/123/orders",
"avatar": "/api/users/123/avatar"
}
}
}
Это делает ваш API самодокументируемым и сокращает построение URL на стороне клиента.
Часто задаваемые вопросы
Как обрабатывать частичные обновления (PATCH vs PUT)?
Используйте PUT для полной замены ресурса (клиент отправляет все поля). Используйте PATCH для частичных обновлений (клиент отправляет только изменённые поля). PATCH с JSON Merge Patch (RFC 7396) — простейший подход: отправьте JSON-объект только с полями для обновления и null для удаления поля.
На основе набора ключей
GET /api/users?after_id=123&limit=20
Использует ID последнего элемента (или другое сортируемое поле) для получения следующей страницы. Похож на курсорный, но с прозрачными параметрами.
Рекомендация: Используйте курсорный для лент реального времени и больших наборов данных. Используйте на основе смещения для административных панелей, где важна навигация по страницам.
На основе заголовков
GET /api/users
Accept: application/vnd.myapi.v2+json
Плюс: Чистые URL. Минус: Сложнее тестировать, менее обнаруживаемый.
Параметр запроса
GET /api/users?version=2
Плюс: Легко тестировать. Минус: Семантика необязательного параметра.
Рекомендация: Версионирование через URL-путь — самый практичный выбор. Оно явное, кэшируемое и работает с любым HTTP-инструментом.
Следует ли использовать спецификацию JSON:API или разработать собственный формат?
Спецификация JSON:API (jsonapi.org) предоставляет всеобъемлющий стандарт, но может быть многословной для простых API. Для большинства проектов проектирование более простого собственного формата по паттернам из этого руководства более практично. Используйте JSON:API, если вам нужны автоматические клиентские библиотеки и строгий стандарт.
Связанные ресурсы
- JSON Форматирование — Форматирование ответов API
- Шаблоны проектирования JSON API — Полное руководство по проектированию API
- Валидация JSON Schema — Валидация структуры ответов
🛠️ Попробуйте сейчас: JSON Formatter | JSON Validator — 100% бесплатно, всё обрабатывается в вашем браузере. Никакие данные не загружаются.