Например, у меня есть объекты: Клиент, Отчет. У клиента может быть много отчетов, и я думаю, что конечная точка для управления одним отчетом должна быть вложена следующим образом:
/clients/{client_id}/reports/{report_id}
Что касается всех отчетов одного клиента, ожидается, что enpoint:
/clients/{client_id}/reports
Но как должна выглядеть конечная точка для получения всех отчетов всех клиентов, чтобы API был согласованным и хорошо спроектированным.
Мои подходы:
- (Я видел это в некоторых API Google) используйте вместо него "-" и проанализируйте его как "все":
/clients/-/reports
Это сохраняет формат конечной точки таким же, но выглядит немного необычно, не может найти ни одного rfc, предлагающего этот способ.
- Создайте отдельную конечную точку только для всех отчетов:
/reports
Но чтобы получить Отчеты Клиента, это все равно:
/clients/{client_id}/reports
- Рефакторинг конечных точек, чтобы сделать «клиента» не родителем, а просто параметром фильтра:
/reports?client={client_id}
- отчеты одного клиента
/reports
- отчеты всего клиента
В случае добавления новой конечной точки для публикации отчета для конкретного клиента, это может выглядеть некрасиво, потому что это будет POST-запрос с параметром в URL.
Есть ли другие предложения идей?
источник
Ответы:
Прежде всего, помните, что нет золотых правил для моделирования API RESTful. Все, что у нас есть, это лучшие практики и соглашения. При этом вероятный ответ - как обычно - выберите тот, который лучше всего соответствует вашим требованиям, и в этом случае тот, который лучше всего отражает вашу модель.
Так что проверь три варианта из выразительности.
# 1 Запись "-"
Это блестящая идея. Это позволяет нам выразить состояние всего,
reports
что принадлежитclients
. Это сужает «запрос» к определенному набору отчетов (расположенных внутриclients
границы).Он постоянно поддерживает понятие иерархии (принадлежности), поэтому, если
reports
его можно найти в разных местах, эта запись имеет большое значение. Например:/clients/-/reports
/departments/-/reports
/employees/-/reports
Однако для получения всех доступных отчетов в системе сохранение иерархии не дает какого-либо ценного преимущества перед следующей опцией.
# 2 Различные URI
Если нам не нужно указывать границы / контексты / иерархию во время извлечения всех доступных отчетов , такой подход мне кажется более разумным.
Новый URI (
/reports
) также оставляет открытой возможность управления отчетами . Однако нам не нужно предоставлять полную поддержку RESTful, если мы не считаем это необходимым. Например, вы заявилиMake a separate endpoint just for all the reports
. Это нормально, вам нужно только внедритьGET
и, возможно, некоторые фильтры для запросов и все.Обратите внимание, что вы все еще можете сделать это
/reports?client={client_id}
. Хорошо иметь разные URI для одного и того же ресурса. Некоторые статьи, которые я прочитал, назвали бы эту надежность .# 3 Возвращение иерархии
У меня такое ощущение, что этот подход не соответствует вашим ожиданиям. Плюс, я думаю, это в конечном итоге приведет вас к начальной точке.
Выводы
Обратите внимание, что # 1 и # 2 не являются взаимоисключающими. Мы можем реализовать оба. Учитывая реальную ситуацию и в соответствии с условиями ОП, я бы реализовал только № 2.
1: это эквивалентно
/clients/-/reports
я думаюисточник
Шаблоны проектирования API Google предлагают использовать «-» в этом сценарии.
Источник:
https://cloud.google.com/apis/design/design_patterns#list_sub-collections
источник
/client/{client_id}/report/{report_id}
и/clients/report/{report_id}
/reports
?/clients...
и/reports
.