Правильное использование дизайна REST — категории и подкатегории

У меня есть два вопроса об основных понятиях REST.

ВОПРОС 1. Категории

Итак, у меня есть список категорий, которые я хочу показать из базы данных.

SELECT * from categories

В настоящее время я использую этот дизайн REST: /api/v1/categories/

Это правильно?

Я также видел /api/v1/categories/list/ -- или это предпочтительнее? (Если да, то что тогда будет отображаться при простом вызове /categories? (Или правильным способом будет /api/v1/category/list, где category в единственном числе, а добавление list покажет вам все категории — таким образом, вызов /category позволит просмотреть информацию только по одному ?)

ВОПРОС 2: Подкатегории. (Думайте о «Сайнфелде» как о подкатегории «Телевидение».)

SELECT * FROM subcategories" WHERE category_id = {id}

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

Буду ли я делать /api/v1/categories/{id}/ для подкатегории с subcat_id? Должен ли я вместо этого использовать параметры, такие как /Categories?id={id}/

Как будут работать эти отношения?


mysql database rest restful-url
person TheLettuceMaster    schedule 12.05.2015    source источник
comment
Честно говоря, я не знаю, есть ли правильный ответ. Вы сами решаете, что лучше всего подходит для вас и вашего приложения. Теперь, сказав это, я думаю, что вы должны сделать так, чтобы ваши URL-адреса читались слева направо, и что, вероятно, в любом заданном слоте может быть только один тип элементов. Например, я, вероятно, не стал бы использовать /api/v1/categories/xyzzy (где xyzzy) — идентификатор категории, и /api/v1/categories/list. (Отдел маркетинга изобретает категорию под названием list, и теперь ваш код не работает...) И прежде всего: будьте последовательны. Придерживайтесь ОДНОГО пути.   -  person Mike Robinson    schedule 12.05.2015
comment
(В приведенном выше примере я мог бы вместо этого использовать, скажем, /api/v1/categories/item/xyzzy. Теперь строка URL-адреса четко читается слева направо, и два возможных значения для четвертого элемента (в данном случае), скажем: list или item , так что наличие любой другой строки в этой позиции указывает на неверный формат URL (ошибка клиента). И каждый другой URL следует тому же шаблону. Я также встречал RESTful API, которые тоже поддерживал JSON, и у них было четко определенное URL-имя, которое указывало, что данные JSON должны сопровождать его.) Тщательно думайте, планируйте будущее и будьте последовательны.   -  person Mike Robinson    schedule 12.05.2015
comment
@MikeRobinson Спасибо за отзыв. У меня есть три уровня в глубину (где каждый уровень может дать вам список). Категории-›Подкатегории-›Предметы. Например, Телевидение-›Сайнфелд-›Крамер. Если я могу спросить ваше мнение, какой URL-адрес будет подходящим в этом случае? Нужно ли показывать три уровня глубины?   -  person TheLettuceMaster    schedule 12.05.2015

Ответы (2)


arrow_upward
1
arrow_downward

Мои ответы основаны на «прагматическом REST».

ВОПРОС 1: Категории

Если вы выберете форму множественного или единственного числа, я бы посоветовал придерживаться ее и не прыгать между единственным и множественным числом ... это субъективно.

Если вы используете форму единственного числа, то действие пути list звучит применимо. Если вы выберете множественное число, то я думаю, что это более субъективно... ИМХО list устраняет двусмысленность, и я бы предпочел его.

ВОПРОС 2: Подкатегории. (Думайте о «Сайнфелде» как о подкатегории «Телевидение».)

ИМХО подкатегория звучит как отдельный ресурс. Я думаю, что у него должен быть свой собственный элемент пути.

Буду ли я делать /api/v1/categories/{id}/ для подкатегории с subcat_id? Должен ли я вместо этого использовать параметры, такие как /Categories?id={id}/

Я думаю, что /api/v1/subcategories/{id}/ более популярен. Но одна вещь, которая становится все более популярной, это критерии поиска. ID может быть просто одним из многих критериев поиска. Если вы видите, что добавляете критерии поиска, то /api/v1/subcategories/?id={id} или /api/v1/subcategories/?filter={some_search_string}, где вы решаете, как будет анализироваться эта строка поиска.

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

person Jose Martinez    schedule 12.05.2015
comment
Эй, спасибо за ответ. Похоже, он более гибкий, чем я предполагал. - person TheLettuceMaster; 12.05.2015
comment
Верный. REST — это не такой протокол, как TCP или HTTP. Это открывает его для интерпретации и субъективности. На самом деле ОТДЫХ, который был первоначально концептуализирован, не соблюдается точно. Вот почему появились такие термины, как прагматичный REST. Ознакомьтесь с этой классной электронной книгой от Apigee. Это может свидетельствовать о некотором разнообразии, которое вы видите в REST. pages.apigee.com/rs/apigee/ images/api-design-ebook-2012-03.pdf - person Jose Martinez; 13.05.2015

arrow_upward
0
arrow_downward

Структура URI — это деталь реализации, она не имеет значения для REST, пока ваша служба выполняет ограничение универсального интерфейса, которое касается применения соответствующих стандартов. В вашем случае структура URI должна соответствовать стандарту URI, и вы должны использовать формат гипермедиа, который содержит гиперссылки. Таким образом, в вашем случае /api/v1/sdfh34gsv/123regf3 будет совершенно нормально, если он находится в гиперссылке и имеется достаточно метаданных, чтобы понять, что делает эта гиперссылка. Например. с HAL+JSON:

{
    "_links": {
        "/api/v1/docs/rels/category": {
            "href": "/api/v1/sdfh34gsv/123regf3",
            "title": "Television"
        }
    }
}

Обрабатывая такой ответ, клиент распознает отношение ссылки «/api/v1/docs/rels/category», поэтому он будет знать, что это гиперссылка на категорию, название которой «Телевидение» и детали категории. можно получить по ссылке. Если клиент не знает отношение ссылки /api/v1/docs/rels/category, то он может разыменовать URI и, вероятно, получить некоторое описание в RDF, которое он может использовать для отображения гиперссылки в более простой форме. Конечно, если разработчики разыменовывают один и тот же URI, они могут получить HTML-описание отношения ссылки.

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

person inf3rno    schedule 12.05.2015