Как мне структурировать реальный API в соответствии с принципами REST? - PullRequest
Новая
       11

Как мне структурировать реальный API в соответствии с принципами REST?

4 голосов
/ 23 декабря 2009

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

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

Ответы [ 3 ]

3 голосов
/ 23 декабря 2009

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

Я также думаю, что вы немного усложняете вещи. Вот более точный ответ на два ваших конкретных вопроса:

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

Даже если что-то концептуально подчинено чему-то другому, это не обязательно имеет значение для целей описания этого. Например, давайте использовать ваш блог пример. A Blog может иметь множество Articles, каждый из которых может иметь один или несколько Pictures. При первом взломе вы можете ожидать, что сможете ссылаться на Pictures примерно так: 

http://api.example.com/articles/123/pictures/456

Но обратите внимание, что, поскольку Pictures сами являются ресурсами, нет ничего плохого в том, чтобы просто делать: 

http://api.example.com/pictures/456

(списки ресурсов с параметрами, которые влияют на то, что выбрано и т. Д.)

Совершенно нормально и приемлемо иметь параметры в запросе RESTful. Например, скажем, вы хотите получить первые 500 фотографий по дате, начиная с двадцать пятой такой фотографии. Ваш API может поддерживать что-то вроде этого: 

http://api.example.com/pictures?limit=500&offset=25&order=desc&by=date
1 голос
/ 23 декабря 2009

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

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

REST Обсудить список рассылки

Rest Wiki

REST Cookbook

Лучший совет, который я могу вам дать, - перестать думать о том, как структурировать URL-адреса, и сосредоточиться на том, какие ссылки вы собираетесь использовать в своих представлениях. Как структурировать ваши URL-адреса будет легко, как только вы определились со своими типами медиа.

0 голосов
/ 23 декабря 2009

Я пойду дальше и предположу, что мы говорим о RESTful HTTP:)

Вот как вы можете представить «список ресурсов с параметрами, которые влияют на то, что выбрано»:

/ list? {Search part}

Где поисковая часть - это произвольная строка, которую вы используете для нацеливания на «раздел» ресурса списка.

Обычный способ сделать это (способ, которым работают браузеры + HTML-формы) - это иметь пары ключ / значение для каждого параметра, т. Е.

/ список? Name1 = Фред & name2 = Дэйв & name3 = матовый

Это соглашение об организации поисковой части не является обязательным, но вы обнаружите, что следование этому шаблону облегчает написание HTML для вашего приложения. Не менее допустимо с точки зрения HTTP и URI использовать следующее:

/ список? Фред, Дэйв, матовый

как эффективно структурировать URL для ресурсы, на которые могут ссылаться сами по себе, но концептуально подчиненный какой-то другой сущности

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

/ Foo

/ Foo / бар

.. если только вы не создадите связь с гиперссылкой от одного к другому. Это правило обычно называют «гипертекстовым ограничением» или «HATEOAS».

Сказав это - нет ничего плохого в том, чтобы "раскладывать" ваши URI. Просто знайте, что (если вы хотите «сделать REST»), вы должны связать все вместе. Большинство API предоставляют «вложенные ресурсы» следующим образом:

/ страны / Англия / город / лондон

Надеюсь, это полезно: -)

...