JSON API: успешное сообщение без ресурса

Мы используем стандарт JSON-API для разработки нашего API, и мы столкнулись с проблемой, которая не имеет очевидного решения в соответствии со стандартом, как кажется.

Вариант использования следующий:

Существует конечная точка API, которая позволяет вам подписываться на списки рассылки. Один из возможных вариантов заключается в том, что пользователь добавляется как ОЖИДАНИЕ, что означает, что пользователь получит электронное письмо для подтверждения и подтвердит его.

Если это так, мы хотим вернуть внешнему интерфейсу сообщение, которое может отображаться пользователю, призывая его щелкнуть ссылку.

С моей точки зрения, это на самом деле не состояние ошибки, а дополнительная метаинформация. Таким образом, это означает, что концептуально нелогично помещать его в сообщения об ошибках. Кроме того, если мы помещаем его в сообщения об ошибках, интерфейс должен каким-то образом отличать его от «настоящих ошибок» (статус-коды имеют такое низкое разрешение, что коллизии кажутся неизбежными).

Однако мы не возвращаем ресурс, поэтому мы не можем добавить его в качестве метаинформации к ресурсу. Так что прямо сейчас я понятия не имею, куда поместить эту информацию.

Одним из возможных решений было бы определить какой-то ресурс «Ответ» и поместить его туда, но это просто похоже на банку с червями.

Любые идеи? Ввод был бы очень ценен


person Tim Strijdhorst    schedule 20.03.2017    source источник


Ответы (1)


Если результатом вызова является добавление пользователя в список рассылки, вернуть 200 OK. Если в результате звонка пользователь должен подписаться по электронной почте, верните 202 принято. Верните объект ответа с 202, содержащим соответствующую информацию.

Из спецификации:

Код состояния 202 (Принято) указывает на то, что запрос принят к обработке, но обработка еще не завершена. Запрос может быть или не быть обработан в конечном итоге, поскольку он может быть запрещен, когда обработка действительно происходит. В HTTP нет средства для повторной отправки кода состояния из асинхронной операции.

Ответ 202 намеренно уклончив. Его цель состоит в том, чтобы позволить серверу принять запрос для какого-либо другого процесса (возможно, пакетно-ориентированного процесса, который запускается только один раз в день), не требуя, чтобы соединение пользовательского агента с сервером сохранялось до завершения процесса. Представление, отправленное с этим ответом, должно описывать текущий статус запроса и указывать (или встраивать) монитор состояния, который может предоставить пользователю оценку того, когда запрос будет выполнен.

person Eric Stein    schedule 20.03.2017
comment
Я только что увидел, что согласно спецификации вы можете вернуть объект Response без ресурса, но с категорией _meta верхнего уровня. Это то, что вы бы поощряли в сообщении об успехе, или у вас есть другой вариант? - person Tim Strijdhorst; 20.03.2017
comment
Я бы вернул 200/204 для запросов, у которых нет дополнительного электронного письма (200, если вы хотите тело, 204, если нет). Для запросов, которые требуют последующего электронного письма, я бы вернул 202 с телом, содержащим любую соответствующую информацию, например сообщение, которое вы хотите предоставить. Я не считаю ободряющее сообщение метаинформацией, нет. - person Eric Stein; 20.03.2017
comment
Я не совсем уверен, что вы имеете в виду под последним предложением. Вы говорите, что вернете тело, содержащее ободряющее сообщение, но не в метаполе? Куда бы вы его положили? Или вы не рассматриваете спецификацию json-api? - person Tim Strijdhorst; 20.03.2017
comment
Правильный. Я бы сделал это атрибутом данных, потому что это не то, что я бы считал метаданными. - person Eric Stein; 20.03.2017
comment
Глядя на спецификацию, я не думаю, что это позволяет, и вам нужно использовать метаобъект. jsonapi.org/format/#document-top-level - person Tim Strijdhorst; 20.03.2017
comment
:-) Я говорю, что сделал бы { данные: { атрибуты: { поощрениеСообщение: проверьте свою электронную почту!, ...}, ...}, ...} Ну, действительно, я просто оставил бы это на усмотрение клиента и не передавал бы сообщение обратно с сервера, но я предполагаю, что это не вариант для вас. - person Eric Stein; 20.03.2017