Рекомендации по разработке REST API для ресурсов, которые также могут принадлежать другим ресурсам

Question

Ради простоты, скажем, у меня есть API для управления проектами, у каждого проекта могут быть вехи.Вехи относятся к проекту, но я также должен иметь возможность получить список всех вех (например, для отображения на приборной панели)

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

GET /api/project/{id}/milestones/

или

GET /api/milestones/?projectId=123

Или совершенно другой подход?

Answer 1

Чтобы ответить на вопрос, исходя из моего опыта, вы точно знаете, как

GET /api/projects/{id}/milestones/
GET /api/milestones/?projectId=123

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

Второй, который я лично использовал бы в качестве конечной точки поиска этапа, если бы я хотел искать этапы в разных проектах или в разных параметрах, например:

GET /api/milestones/?userId=bob
GET /api/milestones/?createdDate=20180101

Первый URL-адрес Iбыло бы просто вернуть основные этапы этого проекта, а затем, если необходимо, добавить оттуда фильтры.

Опять личный вкус / требования проекта

Answer 2

Правильное наименование, в соответствии со стандартами / лучшими практиками, таково:

GET /api/projects/{idProject}/milestones/

обратите внимание на множественное число projects.Это первый голос, который нужно упомянуть, и он используется для четкого определения темы, которую обрабатывает API.Затем вы указываете idProject, чтобы выбрать конкретный проект.И, наконец, вы переходите к sub-collection ресурсу проекта milestones.

Если вам нужна дополнительная ссылка, вы можете найти ее здесь .

PS: /api - довольно общий / общий префикс остальных ресурсов.В некоторых случаях его можно опустить, это вопрос выбора.Это действительно не имеет какого-то конкретного значения в контексте.