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

Question

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

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

1. пользователи
2. отчеты
3. фотографии

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

Я разработал следующие 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}

Вопросы

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

Answer 1

В этом дизайне нет ничего плохого. Но это создает длинные 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}

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

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

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

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

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

Answer 2

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

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

Я хожу по параметрам запроса для фильтрации и тому подобного.

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

Answer 3

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

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

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