Как исправить модель "аннотации" в REST?

Question

Микросервис предоставляет канонический REST API для работы с двумя ресурсами: teams и matches, где в матче играют две команды и набирают очки.

1. post /team добавит новую команду
2. get /teams получат все команды
3. get /team/{id} вернет определенную команду

Та же каноническая реализация предусмотрена для ресурса match. Сейчас есть два клиентских приложения этого микросервиса:

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

Давайте добавим следующие ограничения:

1. Мы не хотим возвращать эту сводную информацию в ресурсе team, поскольку она может быть вычислительно дорогой
2. Эти две сводки имеют разные разрешения: в соответствии с заголовком HTTP-запроса мы можем принять / отклонить запрос

Каким будет подходящий способ разработки API для этого варианта использования?

• Одна конечная точка с параметром запроса, которая не приводит к увеличению количества конечных точек, но возвращает ответы, которые сильно отличаются друг от друга

• Несколько конечных точек (внутренняя сводка, внешняя сводка, сводка результатов, сводка неисправностей)

Answer 1

Как вы, возможно, знаете, в каноническом отдыхе параметры пути проектирования REST API и параметры запроса используются для различных целей:

путь: определить конкретный ресурс / ресурсы,
запрос: сортировка / фильтр ресурсы.

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

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