Урок 032 минуты чтения
Как выбрать method и status code в REST API?
На этой странице
Кратко
В REST method показывает намерение, а status code показывает результат. Хороший API последовательно связывает GET/POST/PATCH/DELETE с 200/201/204/400/401/403/404/409/422.
Вопрос
Как выбрать HTTP method и status code для типовых операций REST API?
Таблица выбора
| Endpoint | Успех | Ошибки |
|---|---|---|
GET /users | 200 + array/page | 401, 403 |
GET /users/:id | 200 + object | 401, 403, 404 |
POST /users | 201 + object | 400, 409, 422 |
PATCH /users/:id | 200 + object или 204 | 400, 401, 403, 404, 422 |
DELETE /users/:id | 204 | 401, 403, 404 |
Создание
POST /api/users
HTTP/1.1 201 Created
Location: /api/users/42Если email уже занят:
HTTP/1.1 409 ConflictЕсли email невалидный:
HTTP/1.1 422 Unprocessable ContentОбновление
PATCH обычно лучше для частичного обновления:
PATCH /api/users/42
{
"name": "Ann"
}Ответ может быть:
200+ обновленный объект;204без body.
В одном API лучше выбрать единый стиль.
Удаление
DELETE /api/users/42
HTTP/1.1 204 No ContentЕсли ресурс уже удален, команды могут выбрать:
404, потому что ресурса нет;204, если delete считают idempotent и не хотят раскрывать детали.
Главное - зафиксировать это в контракте.
Что важно помнить
- Ответ на ошибку тоже должен иметь предсказуемое тело: frontend не должен угадывать формат каждой ошибки.
- Не возвращайте
200с{ "error": ... }внутри: клиенты, cache и мониторинг сочтут запрос успешным. 405 Method Not Allowed— метод не поддерживается этим ресурсом; сервер должен вернуть headerAllow.- Выбранные соглашения фиксируйте в документации API, чтобы backend и frontend понимали коды одинаково.
Мини-шпаргалка
- Method отвечает за действие.
- Status code отвечает за результат.
POSTcreation -> часто201.DELETE-> часто204.401и403не взаимозаменяемы.409хорош для conflicts,422- для domain validation.
Документация
Дочитали до конца?
Отметьте урок — прогресс сохранится в браузере.