Какой код ответа я должен использовать в REST API с несколькими шагами?

Question

Я работаю над REST API, который требует нескольких шагов / проверок для создания ресурса, затем создание POST /transfer может не создавать фактический ресурс передачи (потому что для этого нужны дополнительные шаги), но не вызывает сбоев, так как вызовет второй шаг / проверку.

В этом ответе ответом является незавершенная или ожидающая транзакция с идентификатором, а ресурс содержит конечные точки для завершения транзакции, например /transaction/123/commit или в моем случае /transaction/123/verification/432, где клиент может продолжить , отменить или завершить обработку транзакции.

Но каковы возможные коды ответа на этих конечных точках? /transaction/123/commit действительно возвращает 201 , потому что создает транзакцию или транзакция создается, когда достигает состояния pending?

Answer 1

201 (Создано)

Код состояния 201 (Создано) указывает на создание (хотя бы одного) нового ресурса HTTP .URL-адрес созданного ресурса отправляется в заголовке Location ответа.

Если POST /transfer создает ресурс /transaction/123/commit - то есть, если запросы к /transaction/123/commit теперь могут быть успешными там, где раньше вы это делалииметь 404 (не найдено) - тогда правильно ответить на POST /transfer с 201 и Location: /transaction/123/commit.

Если POST /transfer создает несколько ресурсов, то Location должен быть «основным» (в некотором смысле).

Если POST /transaction/123/commit не создает никакого нового ресурса, то неверно ответить 201, даже если он создает что-то еще (например, запись внутренней базы данных).

Если вы не можете придумать URL для отправки в Location, это, вероятно, означает, что вы не создаете никакого нового ресурса, в этом случае неверный 201.

Примечание: Location isвсегда относительно URL запроса, а не «корня API» или какой-либо подобной концепции, которая у вас может быть.Например, если POST /api/v1/foo/bar создает /api/v1/foo/bar/baz, правильные значения для Location будут включать bar/baz и /api/v1/foo/bar/baz, но не /foo/bar/baz.

200 (OK)

Код состояния 200 (ОК) указывает на общий успех.Это может быть использовано в большинстве успешных ответов.Это своего рода безопасный запасной вариант: он мало что говорит, поэтому гарантированно не скажет много неправильно и не запутает клиента.

Если POST /transaction/123/commit завершится успешно без создания нового ресурсатогда правильно ответить 200.

204 (без содержимого)

За исключением ответов на GET / HEAD, код состояния 204 (без содержимого) в основном совпадает с 200. Если вы используете 204, чтобы сказать что-то отличное от 200, вы, вероятно, составляете локальное соглашение - то же самое, что и свой собственный код состояния 275.

Другое

IANA ведет реестр стандартных кодов состояния .Вы можете найти там код состояния, который стандартизирован, чтобы означать именно то, что вы хотите сказать.

Как правило, вы не хотите использовать нестандартный код состояния или использовать стандартный код состояния неправильно , потому что это исключает унифицированный интерфейс , который является своего рода точкой REST.

Если вы все время пытаетесь поддерживать единый интерфейс,вполне возможно, что вам вообще не нужен REST, и вместо этого вы должны выполнять RPC.