Иерархический дизайн URL-адреса RESTful

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

У меня есть приложение и вы хотите создать RESTful API для отображения подмножества информации. У меня есть три ресурса:

  • пользователей
  • Отчеты
  • фото

У пользователей есть отчеты и отчеты с фотографиями. Фотографии не могут существовать вне отчетов, и отчеты не могут существовать вне пользователей.

Я разработал следующие URL-адреса для своих требований

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

GET example.com/api/

Получить информацию о пользователе

GET example.com/api/users/{username}

Получить все отчеты пользователей

GET example.com/api/users/{username}/reports

Получить все фотографии отчета

GET example.com/api/users/{username}/reports/{report_id}/photos

Добавить фото

POST example.com/api/users/{username}/reports/{report_id}/photos

Удалить фотографию

DELETE example.com/api/users/{username}/reports/{report_id}/photos/{photo_id}

Изменить описание фотографии

PUT example.com/api/users/{username}/reports/{report_id}/photos/{photo_id}

Вопросы

  • Можно ли добавить идентификатор ресурса в URL-адрес, т.е. ресурс /id, или добавить его как параметр запроса?
  • Является ли этот метод цепочки ресурсов, то есть ресурсом /id/sub -resource/id/etc., приемлемым и хорошим, или я должен разместить все мои ресурсы на верхнем уровне и указать его позицию с параметрами запроса?

Ответы

Ответ 1

ИМХО, вы хорошо его моделируете.

Что касается 1, я предпочитаю использовать resource/id, а не параметр запроса. Но одно дело, которое вы должны иметь в виду, когда моделирование - механизм кэширования по прокси и т.д. Поэтому не забывайте заголовки.

Я использую параметры запроса для фильтрации и тех видов.

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

Ответ 2

В этом дизайне нет ничего плохого. Но это создает длинный URL-адрес, который когда-то трудно понять, и пользователь API должен знать иерархию. Более того, потребителю API нужно писать больше кода немного нестандартным способом (Хотя это можно сделать, но будет немного беспорядочно). Подумайте об этом с другой точки зрения У вас есть три ресурса, каждый из которых имеет свою собственную идентификацию. Поэтому, если мы реорганизуем указанный выше URI, он будет выглядеть ниже (я демонстрирую только GET)

Ресурс пользователя:

Получить список пользователей

  GET example.com/api/users

Получить конкретный пользователь

  GET example.com/api/users/{username}

Ресурс отчета:

Получить все отчеты

 GET example.com/api/reports

Получить конкретный отчет

 GET example.com/api/reports/{report_id}

Ресурсы для фотографий

Все фотографии

GET example.com/api/photos

Конкретная фотография

GET example.com/api/photos/{photo_id}

Все отчеты пользователя

GET example.com/api/reports?username={userName}

Конкретный отчет пользователя

GET example.com/api/report?username={userName}&report_id={reportId}

Все фотографии пользователя

GET example.com/api/photos?username={userName}

Пользовательские фотографии для идентификатора отчета (вам может не понадобиться имя пользователя, если report_id уникально независимо от пользователя, что упростит URI)

GET example.com/api/photos?username={userName}&report_id={reportId}

Все фотографии отчета

GET example.com/api/photos?report_id={reportId}

Это упрощает понимание, и более стандартный код может быть написан на стороне потребителя, используя этот подход.

Ответ 3

Я не вижу ничего плохого в вашей схеме.

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

По моему мнению, это делает URL более читаемым и немного приятнее для пользователя.