Обработайте случаи, когда пользователи вводят все один из необязательных параметров в ответ API

Question

Конечная точка API, которую я написал, поддерживает два однопараметрических параметра, и пользователям предлагается указывать значения только для одного из них, но в идеале они не должны указывать оба.

{"A": "something", "B": "something"}

Если пользователи не предоставляют ни один из этих двух параметров, возникает исключение.

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

Для контекста, A, в общем и целом, является подмножеством B. У моего партнера по команде есть два мнения:

1. Когда пользователи вводят оба, преобладает A.
2. Когда пользователи вводят оба, генерируется исключение 400, чтобы напомнить пользователям, что нам нужен только один из двух.

Спасибо!

Answer 1

Если разумно / целесообразно ожидать одно свойство, вы должны разрешить только одно свойство.

Строгие API полезны, потому что они намного лучше направляют пользователей к цели сервера и ресурса.

Одним из отличных инструментов для такого рода вещей является использование чего-то вроде json-schema, чтобы точно указать, что ваш сервер делает и чего не ожидает. Возможность указать, что только 1 из 2 свойств может появиться, является одной из его возможностей.

Answer 2

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

Вы можете рассматривать типы мультимедиа как аналог.

То есть предположим, что у нас была спецификация для application/vnd.example.AorB+json, которая определяла поле A, поле B и явновыразил, что должен присутствовать ровно один из этих двух вариантов.

Теперь, когда наша конечная точка получает POST или PUT с типом содержимого application/vnd.example.AorB+json, мы знаем, что сущность, включенная в тело запроса, должнабыть документом json с дополнительными ограничениями на ключи и значения.

По аналогии, если ключи и значения неверны, наша конечная точка должна отклонить документ так же, как если бы сама структура JSON былане правильно сформирован.

Если вы купите эту логику, то практический ответ - развернуть конечную точку, которая ожидает json, отправить что-то сломанное и посмотреть, какой ответ вы получите.Затем смоделируйте свой собственный дизайн.

В стандарте WebDAV есть интересная дискуссия, связанная с определением кода состояния 422 .

The 422 (не обрабатываетсяКод состояния объекта) означает, что сервер понимает тип содержимого объекта запроса (следовательно, код состояния 415 (неподдерживаемый тип носителя) не подходит), и синтаксис объекта запроса является правильным (таким образом, код состояния 400 (неверный запрос)неуместно), но не смог обработать содержащиеся в нем инструкции.

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

На практике это действительно не имеет большого значения.Вы ДОЛЖНЫ объяснить конкретную проблему в теле ответа , чтобы люди могли понять, что произошло.Разные коды состояния на самом деле являются метаданными, поэтому универсальные компоненты могут выяснить, что делать, но в стандарте нет ничего, что указывало бы универсальным компонентам обрабатывать 422 иначе, чем 400.

Так что не переусердствуйте.