Должно ли тело ответа GET all родительского ресурса возвращать список дочерних ресурсов?

Question

Пожалуйста, потерпите меня, если название немного запутанное, я постараюсь объяснить мой вопрос ниже.

Скажем, у меня есть следующие две конечные точки

1. api/companies (возвращает список всех компаний, как показано ниже)

   [{name: "company1", id: 1}, {name: "company2", id: 2}]

2. api/companies/{companyeId}/employees (возвращает список всех сотрудников для конкретной компании, как показано ниже)

   [{name: "employee1", id: 1}, {name: "employee2", id: 2}]

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

[
  {
    name: "company1", 
    id: 1, 
    employees: [ {name: "employee1", id: 1}, {name: "employee2", id: 2} ]
  },
  {
    name: "company2", 
    id: 2, 
    employees: [ {name: "employee3", id: 3}, {name: "employee4", id: 4} ]
  },    
]

Есть два способа сделать это:

1. Сначала получите список компаний и просмотрите список компаний до сделать вызов API для каждой компании, чтобы получить свой список сотрудников. (Мне интересно, является ли это лучшим способом проектирования из-за принципа HATEOAS , если я правильно понимаю? Потому что наименьшая единица ресурса api/companies - это компания, а не сотрудники, поэтому ожидается, что клиент обнаружит компании в качестве доступного ресурса, но не сотрудников.)

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

2. Возвращать список сотрудников внутри каждого объекта компании, а затем возвращать список компаний через api/companies. Может быть, добавьте параметр запроса к этой конечной точке с именем responseHasEmployees, который по умолчанию имеет логическое значение false, поэтому, когда пользователь вводит значения от GET до api/companies?responseHasEmployees=true, тело ответа будет иметь список сотрудников внутри каждого объекта компании.

Итак, мой вопрос: какой путь является лучшим способом достижения цели на стороне клиента? (Не обязательно должно быть два вышеуказанных.)

Дополнительная информация, которая может оказаться полезной : компании и сотрудники хранятся в разных таблицах, а таблица сотрудников имеет столбец company_fk.

Answer 1

Я предполагаю, что у клиента, которого вы создаете, будет интерфейс для просмотра списка компаний, в котором будет возможность просматривать сотрудников компании. Поэтому лучше всего делать это по требованию, а не загружать все данные сразу.

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

Здесь, в вашем случае,

• Главный ресурс - Компании
• Подресурс - Сотрудники

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

Answer 2

Начните с того, чтобы задать себе пару вопросов:

Это распространенный сценарий?
Логично ли запрашивать данные таким образом?

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

Далее, у вас уже есть вызовы API, которые передают переменные? Основываясь на вашем принципе HATEOAS, вы, вероятно, не должны. Клиенты не должны знать или понимать значения переменных в вашем URL. Если нет, держись от этого подальше. Сделайте его максимально чистым для клиентской части. Вы можете создать третий отдельный API "api / companiesWithEmployees". Это соответствует вашему принципу HATEOAS, клиенту не нужно ничего знать о параметрах или других действиях API, только чтобы они получили "Компании с сотрудниками". Кроме того, стоимость минимальна; дополнительный метод в коде базы. Это проще для клиента с низкой стоимостью.

Затем подумайте о некоторых последствиях для развития: Вы открываете дверь для более конкретных запросов API?
Можете ли вы поддерживать жесткую линию данных, которые вы хотите получить доступ через API?
Можете ли вы поддерживать свой принцип HATEOAS в том, что клиенты знают все, что им нужно знать, основываясь на URL API?

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

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