Как предлагать списки допустимых значений параметров в API RESTful?

Question

Это скорее концептуальный, чем технический вопрос, я думаю. Предположим, у меня есть REST API для работы с огромным автопарком.

API-интерфейс моделируется вокруг бизнес-сущностей/ресурсов в очень стандартной и последовательной (даже если спорный) способ, как что:

• /cars/1234 - подробные данные об определенном автомобиле
• /clients/5678 - подробные данные об определенном клиенте
• /cars - список автомобилей и их URIs
• /clients - список клиентов

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

GET /cars?type=minivan 

Для правильного с помощью параметра «type», я должен иметь список допустимых значений, такие как «минивэн», «кабриолет», «универсал», " хэтчбек "," седан "и т. д. Хорошо, там не так много видов автомобилей, но предположим, что этот список слишком велик для перечисления в определении Swagger API.

Итак ... Что было бы самым последовательным и естественным способом для API REST предложить список допустимых значений для параметра запроса, подобного этому?

• Как субординированный ресурс, как /cars/types? Это нарушит шаблон URL-адреса /cars/{id}, не так ли?

• В качестве отдельного ресурса, такого как /tables/cars/types? Это нарушит согласованность основных ресурсов самой бизнес-модели, верно?

• В качестве части тела ответа для OPTIONS /cars? Это похоже на «RESTfullest» способ для меня, но некоторые из моих коллег не согласны, и ВАРИАНТЫ, похоже, редко используются для подобных вещей.

• Может быть, как часть ответа на GET /cars?&metadata=values или что-то в этом роде? «Значения» здесь выглядят более семантически связанными с возвращаемыми данными, чем с параметрами запроса, не так ли?

• Что-нибудь еще?

Я гугл и искал в SO для некоторых рекомендаций по данной конкретной теме, но я не мог найти что-нибудь, чтобы помочь мне с аргументами для такого решения ...

Спасибо!

Фабрисио Rocha

Бразилиа, Бразилия

Answer 1

"хороший REST API, как уродливый сайт" - Rickard Öberg

Так как бы вы сделали это в веб-сайт? Ну, у вас, вероятно, есть ссылка, которая идет в форму, и форма будет иметь элементы управления списком/радиокнопками с семантическими репликами для каждой опции, с ожиданием, что пользователь выберет значение из доступных вариантов, и пользовательский агент будет кодировать это значение в URL-адрес запроса GET, когда форма была отправлена.

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

Но вы, вероятно, не выполняете REST: это колоссальная PITA, и преимущества ограничений архитектуры REST, вероятно, не окупаются в вашем контексте. Таким образом, вы, скорее всего, просто ищете разумное написание идентификатора для ресурса, который возвращает сообщение со списком параметров.

Как субординированный ресурс типа/cars/types? Это сломает шаблон/cars/{id} URL, не так ли?

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

В качестве отдельного ресурса, такого как/tables/cars/types? Это нарушит согласованность основных ресурсов самой бизнес-модели, верно?

Помните о программировании и инкапсуляции OO? Разделение API из базовой модели данных - это хорошо.

Тем не менее, я лично не люблю «таблицы» как элемент вашей иерархии. Если вы хотите, чтобы возглавить это направление, я предлагаю /dimensions - это написание вы могли бы использовать, если вы проектировали data warehouse

как часть тела в ответ на OPTIONS/автомобили? Это похоже на «RESTfullest» способ для меня, но некоторые из моих коллег не согласны, и ВАРИАНТЫ, похоже, редко используются для подобных вещей.

Yikes! RFC 7231 предполагает, что это очень запутанная идея.

Метод OPTIONS запрашивает информацию о связи опции, доступной для целевого ресурса, либо на сервере происхождения или промежуточный посредник.

(выделено мной).При написании API для Интернета вы всегда должны помнить, что клиентский запрос может проходить через посредников, которых вы не контролируете; ваша способность обеспечить хороший опыт в этих обстоятельствах зависит от того, чтобы не путать посредников, отклонившись от единого интерфейса.

Возможно, как часть ответа на GET/cars? & metadata = значения или что-то подобное?

По большей части машины довольно удобны с любым орфографическим. Руководства по дизайну URI обычно фокусируются на человеческой аудитории. Я думаю, что конкретное правописание будет путать ваших потребителей, особенно если /cars?... иначе идентифицирует ресурс, являющийся результатом поиска.

Что-нибудь еще? Я все еще чувствую, что то, что люди ожидают найти под машинами, - это ... куча автомобилей (их представления, я имею в виду), а не список ценностей среди них ...

Итак, давайте изменим ваш вопрос немного

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

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

Например, вы могли бы посмотреть на StackExchange API, где

https://api.stackexchange.com/docs/questions

говорит вам все, что нужно знать о семье ресурсов ресурсов на

https://api.stackexchange.com/2.2/questions

Типы, Unsurprisingly , задокументированы как:

https://api.stackexchange.com/docs/types/flag-option

Если вы хотите быть сексуальными, вы можете использовать Accept-Type для согласования переадресации на документацию, пригодную для чтения человеком или машиночитаемую документацию.

Answer 2

Я в аналогичной ситуации, но у меня есть большое количество полей, каждое из которых имеет большое количество возможных значений, а в некоторых случаях значения исходят из иерархии, поэтому мое поле представляет собой массив строк. (Заимствование из вашего примера: вы можете захотеть записать завод, который произвел автомобиль, а не 1-мерный список, который они организуют: континент, страна и государство).

Я думаю, что я буду использовать ресурс/таксономий, чтобы предоставить все данные пользователям. Я вижу, что WordPress использует аналогичную схему (http://v2.wp-api.org/reference/taxonomies/), хотя я еще не изучил ее.