re:re:actable
Урок 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 /users200 + array/page401, 403
GET /users/:id200 + object401, 403, 404
POST /users201 + object400, 409, 422
PATCH /users/:id200 + object или 204400, 401, 403, 404, 422
DELETE /users/:id204401, 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 — метод не поддерживается этим ресурсом; сервер должен вернуть header Allow.
  • Выбранные соглашения фиксируйте в документации API, чтобы backend и frontend понимали коды одинаково.

Мини-шпаргалка

  • Method отвечает за действие.
  • Status code отвечает за результат.
  • POST creation -> часто 201.
  • DELETE -> часто 204.
  • 401 и 403 не взаимозаменяемы.
  • 409 хорош для conflicts, 422 - для domain validation.

Документация

MDN: HTTP-методы, MDN: Коды ответа.

Дочитали до конца?
Отметьте урок — прогресс сохранится в браузере.

Поиск

Поиск по урокам