Каковы лучшие практики для вложенных ресурсов REST?

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

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

Отдел не может существовать без ассоциированной компании.

Сотрудник не может существовать без ассоциированного отдела.

Теперь я нашел бы естественное представление шаблонов ресурсов.

• /companies Коллекция компаний - Принимает положил для новой компании. Получи за всю коллекцию.
• /companies/{companyId}Индивидуальная компания. Принимает GET, PUT и DELETE
• /companies/{companyId}/departmentsПринимает POST для нового элемента. (Создает отдел внутри компании.)
• /companies/{companyId}/departments/{departmentId}/
• /companies/{companyId}/departments/{departmentId}/employees
• /companies/{companyId}/departments/{departmentId}/employees/{empId}

Учитывая ограничения, в каждом из разделов я чувствую, что это имеет смысл, если немного глубоко вложен.

Однако моя проблема возникает, если я хочу перечислить ( GET) всех сотрудников во всех компаниях.

Шаблон ресурсов для этого наиболее точно соответствует /employees(Коллекция всех сотрудников)

Означает ли это, что я должен иметь /employees/{empId}также потому, что если так, то есть два URI, чтобы получить тот же ресурс?

Или, может быть, вся схема должна быть сведена, но это будет означать, что сотрудники являются вложенным объектом верхнего уровня.

На базовом уровне /employees/?company={companyId}&department={deptId}возвращается точно такое же представление о сотрудниках, как и наиболее глубоко вложенный шаблон.

Какова оптимальная практика для шаблонов URL, когда ресурсы принадлежат другим ресурсам, но должны обрабатываться отдельно?

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

И вообще, вам может понадобиться получить доступ к элементам напрямую или как к подмножеству чего-то еще - так что ваша структура имеет смысл для меня.

Только потому, что сотрудники доступны в отделе:

company/{companyid}/department/{departmentid}/employees

Это не значит, что они не могут быть доступны и в компании:

company/{companyid}/employees

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

Но я надеюсь, что все обработчики URL-адресов используют один и тот же код поддержки для удовлетворения запросов, чтобы вы не дублировали код.

Я испробовал обе стратегии проектирования - вложенные и не вложенные конечные точки. Я нашел это:

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

2. вложенные конечные точки обычно требуют избыточных конечных точек. Другими словами, вам чаще всего понадобится дополнительная конечная точка / employee, чтобы вы могли получить список сотрудников по отделам. Если у вас есть / сотрудники, что именно / компании / отделы / сотрудники покупают вам?

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

4. иногда ресурс может иметь несколько типов родителей. В результате все конечные точки возвращают один и тот же ресурс.

5. избыточные конечные точки затрудняют написание документов, а также затрудняют изучение API.

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

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

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

Так что в этом примере (просто перечисление конечных точек, которые изменяют ресурс)

• POST /companies/ создает новую компанию, возвращает ссылку на созданную компанию.
• POST /companies/{companyId}/departments когда отдел помещен, создается новый отдел возвращает ссылку на /departments/{departmentId}
• PUT /departments/{departmentId} изменяет отдел
• POST /departments/{deparmentId}/employees создает нового сотрудника возвращает ссылку на /employees/{employeeId}

Таким образом, есть ресурсы корневого уровня для каждой из коллекций. Однако создание находится в владеющем объекте.

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

В более сложных системах может возникнуть соблазн предоставить URI, которые позволяют клиенту перемещаться по нескольким уровням отношений, например, /customers/1/orders/99/products.однако, этот уровень сложности может быть сложно поддерживать и он негибкий, если отношения между ресурсами изменятся в будущем. Вместо этого постарайтесь сделать URI относительно простыми . Как только у приложения есть ссылка на ресурс, должна быть возможность использовать эту ссылку для поиска элементов, связанных с этим ресурсом. Предыдущий запрос можно заменить на URI, /customers/1/ordersчтобы найти все заказы для клиента 1, а затем /orders/99/productsнайти продукты в этом заказе.

,

Наконечник

Избегайте использования URI ресурса более сложным, чем collection/item/collection.

То, как выглядят ваши URL, не имеет ничего общего с REST. Все идет. На самом деле это «деталь реализации». Так же, как вы называете свои переменные. Все они должны быть уникальными и долговечными.

Не тратьте слишком много времени на это, просто сделайте выбор и придерживайтесь его / будьте последовательны. Например, если вы используете иерархию, вы делаете это для всех своих ресурсов. Если вы идете с параметрами запроса ... и т. Д., Так же, как соглашения о присвоении имен в вашем коде.

Почему так ? Насколько я знаю, API "RESTful" должен быть доступен для просмотра (вы знаете ... "Гипермедиа как движок состояния приложения"), поэтому клиент API не заботится о том, на что похожи ваши URL, пока они действительный (нет SEO, нет человека, который должен читать эти "дружеские ссылки", кроме как для отладки ...)

То, насколько приятный / понятный URL-адрес в REST API, интересует вас, как разработчика API, а не клиента API, как было бы имя переменной в вашем коде.

Самое главное, чтобы ваш клиент API знал, как интерпретировать ваш тип мультимедиа. Например, он знает, что:

• Ваш тип мультимедиа имеет свойство links, в котором перечислены доступные / связанные ссылки.
• Каждая ссылка идентифицируется отношением (точно так же, как браузеры знают, что ссылка [rel = "stylesheet"] означает, что это таблица стилей, или rel = favico - это ссылка на favicon ...)
• и он знает, что означают эти отношения («компании» означают список компаний, «поиск» означает шаблонный URL для поиска по списку ресурса, «отделы» означают отделы текущего ресурса)

Ниже приведен пример обмена HTTP (тела в yaml, так как их легче написать):

Запрос

GET / HTTP/1.1
Host: api.acme.io
Accept: text/yaml, text/acme-mediatype+yaml

Ответ: список ссылок на основной ресурс (компании, люди, что угодно ...)

HTTP/1.1 200 OK
Date: Tue, 05 Apr 2016 15:04:00 GMT
Last-Modified: Tue, 05 Apr 2016 00:00:00 GMT
Content-Type: text/acme-mediatype+yaml

# body: this is your API's entrypoint (like a homepage)  
links:
  # could be some random path https://api.acme.local/modskmklmkdsml
  # the only thing the API client cares about is the key (or rel) "companies"
  companies: https://api.acme.local/companies
  people: https://api.acme.local/people

Запрос: ссылка на компании (используя body.links.companies предыдущего ответа)

GET /companies HTTP/1.1
Host: api.acme.local
Accept: text/yaml, text/acme-mediatype+yaml

Ответ: неполный список компаний (по пунктам), ресурс содержит связанные ссылки, например ссылку, чтобы получить следующую пару компаний (body.links.next), другую (шаблонную) ссылку для поиска (body.links.search)

HTTP/1.1 200 OK
Date: Tue, 05 Apr 2016 15:06:00 GMT
Last-Modified: Tue, 05 Apr 2016 00:00:00 GMT
Content-Type: text/acme-mediatype+yaml

# body: representation of a list of companies
links:
  # link to the next page
  next: https://api.acme.local/companies?page=2
  # templated link for search
  search: https://api.acme.local/companies?query={query} 
# you could provide available actions related to this resource
actions:
  add:
    href: https://api.acme.local/companies
    method: POST
items:
  - name: company1
    links:
      self: https://api.acme.local/companies/8er13eo
      # and here is the link to departments
      # again the client only cares about the key department
      department: https://api.acme.local/companies/8er13eo/departments
  - name: company2
    links:
      self: https://api.acme.local/companies/9r13d4l
      # or could be in some other location ! 
      department: https://api2.acme.local/departments?company=8er13eo

Таким образом, как вы видите, если вы идете по пути ссылок / отношений, то, как вы структурируете часть пути ваших URL, не имеет никакого значения для вашего клиента API. И если вы сообщаете клиенту структуру ваших URL-адресов в качестве документации, то вы не выполняете REST (или, по крайней мере, не уровень 3 в соответствии с « моделью зрелости Ричардсона »)

Я не согласен с таким путем

GET /companies/{companyId}/departments

Если вы хотите получить отделы, я думаю, что лучше использовать ресурс / отделы

GET /departments?companyId=123

Я предполагаю, что у вас есть companiesтаблица и таблица, а departmentsзатем классы для отображения их на языке программирования, который вы используете. Я также предполагаю, что отделы могут быть присоединены к другим объектам, а не к компаниям, поэтому ресурс / отделы прост, удобно сопоставлять ресурсы с таблицами, а также вам не нужно столько конечных точек, так как вы можете повторно использовать

GET /departments?companyId=123

для любого вида поиска, например

GET /departments?name=xxx
GET /departments?companyId=123&name=xxx
etc.

Если вы хотите создать отдел,

POST /departments

должен использоваться ресурс, а тело запроса должно содержать идентификатор компании (если отдел может быть связан только с одной компанией).

Rails предоставляет решение этой проблемы: мелкое вложение .

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