RESTful API Именование ресурсов и дизайн контроллера

Question

Просто прочитайте некоторые рекомендации по дизайну API RESTful. Я исхожу из фона ASP.Net Web Forms, в котором я вызывал код WebMethods, чтобы возвращать данные на javascript моей клиентской стороны. Для меня логично перевести эти WebMethods в API, чтобы мы могли начать централизовать и стандартизировать то, как мы вызываем конечные системы.

Я понимаю, что целью REST является категоризация операции на ресурсе для получения, POST, PUT и DELETE. Так же, чтобы использовать Существительные вместо глаголов для этих ресурсов.

1) У меня есть два метода, которые возвращают данные для создания отчетов. Я создал свои собственные классы BreakdownIncidents и BreakdownMinutes из-за привязки к стороне клиента и других конкретных свойств для каждого отчета.

[WebMethod] Top10MinutesBreakdowns

|Machine|Department|Total Minutes|etc.| 

[WebMethod] Top10IncidentsBreakdowns

|Machine|Department|Total Incidents|etc.| 

Должны быть организованы эти методы:

GET /Breakdowns?report=minutes&type=top10 
GET /Breakdowns?report=incidents&type=top10 

Тогда в моем контроллере Breakdowns проверьте параметры и вызовите соответствующую существующую функцию бизнес-уровня, чтобы вернуть данные?

2) Отчеты возвращают два разных свойства (простота: количество минут и количество инцидентов). Должен ли я действительно группировать эти два метода в один и тот же контроллер?

Здесь я смущен, потому что в отчете используются разные свойства, но основной объект - это разбивка. Возможно, этот вопрос больше подходит для перепроектирования самого моего бизнес-объекта. Я нахожу, что наш существующий бизнес-уровень имеет много классов, которые были созданы для привязки просмотров клиентской стороны. Я уверен, что с этим сценарием я столкнулся, когда попытаюсь построить этот API.

Answer 1

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

Вы также можете указать параметр fieldset, что делает возвращаемые свойства более явными, например: /api/breakdown?fieldset=machine,department,minutes.

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

Answer 2

Я понимаю, что цель REST состоит в том, чтобы классифицировать операцию на ресурсе с помощью GET, POST, PUT и DELETE. Так же, чтобы использовать Существительные вместо глаголов для этих ресурсов.

Не совсем - цель REST - сформулировать ограничения, необходимые для поддержки приложений веб-масштаба.См. Fielding, 2000

Это то место, где я запутался, потому что в отчете используются разные свойства, но базовый объект - это разбивка.

Не путайте API с базовыми реализациями/представлениями. Тот факт, что Top10MinutesBreakdowns и Top10IncidentsBreakdowns информационных ресурсов, случается, использовать ссылки на один и тот же базовый объект - это случайность вашей текущей реализации.

Другими словами, ваш контроллер (ы) - это адаптеры, поддерживающие иллюзию - это просто хранилище документов, которое понимает сообщения HTTP-запроса.

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

Любое правописание URI, которое вы можете правильно направить, хорошо, но я лично был бы склонен давать эти собственные идентификаторы отчетов.

GET /Top10MinutesBreakdowns 
GET /Top10IncidentsBreakdowns 

А затем настройте свою маршрутизацию для доставки этих запросов соответствующему контроллеру.