Quelles sont les meilleures pratiques pour les ressources imbriquées REST?

Autant que je sache, chaque ressource individuelle ne devrait avoir qu'un seul chemin canonique . Dans l'exemple suivant, quels seraient les bons modèles d'URL?

Prenons par exemple une représentation représentative des entreprises. Dans cet exemple hypothétique, chaque entreprise possède 0 ou plusieurs départements et chaque département possède 0 ou plusieurs employés.

Un département ne peut exister sans une entreprise associée.

Un employé ne peut exister sans un service associé.

Maintenant, je trouverais la représentation naturelle des modèles de ressources.

• /companies Une collection d'entreprises - Accepte une nouvelle entreprise. Obtenez pour toute la collection.
• /companies/{companyId}Une entreprise individuelle. Accepte GET, PUT et DELETE
• /companies/{companyId}/departmentsAccepte le POST pour un nouvel élément. (Crée un département au sein de l'entreprise.)
• /companies/{companyId}/departments/{departmentId}/
• /companies/{companyId}/departments/{departmentId}/employees
• /companies/{companyId}/departments/{departmentId}/employees/{empId}

Compte tenu des contraintes, dans chacune des sections, je pense que cela a du sens s'il est un peu profondément imbriqué.

Cependant, ma difficulté vient si je veux lister ( GET) tous les employés dans toutes les entreprises.

Le modèle de ressources correspondant le plus étroitement à /employees(La collection de tous les employés)

Cela signifie-t-il que j'aurais dû /employees/{empId}aussi parce que si c'est le cas, il y a deux URI pour obtenir la même ressource?

Ou peut-être que le schéma entier devrait être aplati, mais cela signifierait que les employés sont un objet de niveau supérieur imbriqué.

Au niveau de base, /employees/?company={companyId}&department={deptId}la même vue des employés est exactement la même que le modèle le plus profondément imbriqué.

Quelle est la meilleure pratique pour les modèles d'URL dans lesquels les ressources appartiennent à d'autres ressources mais doivent être interrogeables séparément?

Ce que vous avez fait est correct. En général, il peut y avoir plusieurs URI vers la même ressource - il n'y a pas de règles qui disent que vous ne devriez pas faire ça.

Et généralement, vous devrez peut-être accéder aux éléments directement ou en tant que sous-ensemble de quelque chose d'autre - donc votre structure est logique pour moi.

Tout simplement parce que les employés sont accessibles par département:

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

Cela ne veut pas dire qu'ils ne peuvent pas non plus être accessibles sous l'entreprise:

company/{companyid}/employees

Ce qui rendrait des employés pour cette entreprise. Cela dépend de ce dont votre client consommateur a besoin - c'est pour cela que vous devriez concevoir.

Mais j'espère que tous les gestionnaires d'URL utilisent le même code de support pour satisfaire les demandes afin que vous ne dupliquiez pas le code.

J'ai essayé les deux stratégies de conception - points de terminaison imbriqués et non imbriqués. J'ai trouvé que:

1. si la ressource imbriquée a une clé primaire et que vous n'avez pas sa clé primaire parent, la structure imbriquée vous oblige à l'obtenir, même si le système n'en a pas réellement besoin.

2. les points de terminaison imbriqués nécessitent généralement des points de terminaison redondants. En d'autres termes, vous aurez le plus souvent besoin du point de terminaison supplémentaire / employés pour pouvoir obtenir une liste des employés dans les différents services. Si vous avez / employés, qu'est-ce que / entreprises / services / employés vous achètent exactement?

3. les points de terminaison d'imbrication n'évoluent pas aussi bien. Par exemple, vous n'aurez peut-être pas besoin de rechercher des employés maintenant, mais vous pourrez le faire plus tard et si vous avez une structure imbriquée, vous n'avez pas d'autre choix que d'ajouter un autre point de terminaison. Avec une conception non imbriquée, vous ajoutez simplement plus de paramètres, ce qui est plus simple.

4. Parfois, une ressource peut avoir plusieurs types de parents. Il en résulte plusieurs points de terminaison renvoyant tous la même ressource.

5. les points de terminaison redondants rendent les documents plus difficiles à écrire et rendent également l'API plus difficile à apprendre.

En bref, la conception non imbriquée semble permettre un schéma de point de terminaison plus flexible et plus simple.

J'ai déplacé ce que j'ai fait de la question à une réponse où plus de gens sont susceptibles de le voir.

Ce que j'ai fait, c'est d'avoir les points de terminaison de création sur le point de terminaison imbriqué. Le point de terminaison canonique pour modifier ou interroger un élément n'est pas sur la ressource imbriquée .

Donc, dans cet exemple (énumérant simplement les points de terminaison qui modifient une ressource)

• POST /companies/ crée une nouvelle société renvoie un lien vers la société créée.
• POST /companies/{companyId}/departments lorsqu'un département est créé crée le nouveau département renvoie un lien vers /departments/{departmentId}
• PUT /departments/{departmentId} modifie un département
• POST /departments/{deparmentId}/employees crée un nouvel employé renvoie un lien vers /employees/{employeeId}

Il existe donc des ressources de niveau racine pour chacune des collections. Cependant, la création se trouve dans l' objet propriétaire .

J'ai lu toutes les réponses ci-dessus, mais il semble qu'ils n'aient pas de stratégie commune. J'ai trouvé un bon article sur les meilleures pratiques de Design API de Microsoft Documents . Je pense que vous devriez vous référer.

Dans les systèmes plus complexes, il peut être tentant de fournir des URI qui permettent à un client de naviguer à travers plusieurs niveaux de relations, tels que /customers/1/orders/99/products.Cependant, ce niveau de complexité peut être difficile à maintenir et est inflexible si les relations entre les ressources changent à l'avenir. Essayez plutôt de garder les URI relativement simples . Une fois qu'une application a une référence à une ressource, il devrait être possible d'utiliser cette référence pour rechercher des éléments liés à cette ressource. La requête précédente peut être remplacée par l'URI /customers/1/orderspour rechercher toutes les commandes du client 1, puis /orders/99/productsrechercher les produits dans cette commande.

.

Pointe

Évitez d'exiger des URI de ressources plus complexes que collection/item/collection.

L'aspect de vos URL n'a rien à voir avec REST. Tout va. Il s'agit en fait d'un "détail d'implémentation". Donc, tout comme la façon dont vous nommez vos variables. Tout ce qu'ils doivent être est unique et durable.

Ne perdez pas trop de temps à ce sujet, faites simplement un choix et respectez-le / soyez cohérent. Par exemple, si vous optez pour des hiérarchies, vous le faites pour toutes vos ressources. Si vous allez avec des paramètres de requête ... etc, tout comme les conventions de dénomination dans votre code.

Pourquoi Pour autant que je sache, une API "RESTful" doit être consultable (vous savez ... "Hypermedia en tant que moteur de l'état de l'application"), donc un client API ne se soucie pas de ce que sont vos URL tant qu'elles sont valide (il n'y a pas de référencement, pas d'humain qui a besoin de lire ces "URL amicales", sauf peut-être pour le débogage ...)

Le caractère agréable / compréhensible d'une URL dans une API REST ne vous intéresse qu'en tant que développeur d'API, pas en tant que client d'API, comme le serait le nom d'une variable dans votre code.

La chose la plus importante est que votre client API sache comment interpréter votre type de média. Par exemple, il sait que:

• votre type de média a une propriété de liens qui répertorie les liens disponibles / liés.
• Chaque lien est identifié par une relation (tout comme les navigateurs savent que le lien [rel = "stylesheet"] signifie que c'est une feuille de style ou rel = favico est un lien vers un favicon ...)
• et il sait ce que ces relations signifient («sociétés» signifie une liste de sociétés, «recherche» signifie une URL basée sur un modèle pour effectuer une recherche sur une liste de ressources, «départements» signifie des départements de la ressource actuelle)

Voici un exemple d'échange HTTP (les corps sont en yaml car il est plus facile d'écrire):

Demande

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

Réponse: une liste de liens vers la ressource principale (entreprises, personnes, peu importe ...)

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

Demande: lien vers les entreprises (en utilisant la réponse précédente body.links.companies)

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

Réponse: une liste partielle des sociétés (sous les éléments), la ressource contient des liens connexes, comme un lien pour obtenir les deux sociétés suivantes (body.links.next), un autre lien (basé sur un modèle) pour rechercher (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

Donc, comme vous le voyez, si vous suivez les liens / relations, la façon dont vous structurez la partie chemin de vos URL n'a aucune valeur pour votre client API. Et si vous communiquez la structure de vos URL à votre client en tant que documentation, alors vous ne faites pas REST (ou du moins pas le niveau 3 selon le " modèle de maturité de Richardson ")

Je suis en désaccord avec ce genre de chemin

GET /companies/{companyId}/departments

Si vous voulez obtenir des départements, je pense qu'il vaut mieux utiliser une ressource / départements

GET /departments?companyId=123

Je suppose que vous avez une companiestable et une departmentstable puis des classes pour les mapper dans le langage de programmation que vous utilisez. Je suppose également que les départements peuvent être attachés à d'autres entités que les entreprises, donc une ressource / départements est simple, il est pratique d'avoir des ressources mappées sur des tables et vous n'avez pas besoin d'autant de points finaux car vous pouvez réutiliser

GET /departments?companyId=123

pour tout type de recherche, par exemple

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

Si vous souhaitez créer un service, le

POST /departments

la ressource doit être utilisée et le corps de la demande doit contenir l'ID de l'entreprise (si le service ne peut être lié qu'à une seule entreprise).

Rails apporte une solution à ce problème: l' emboîtement peu profond .

Je pense que c'est une bonne chose car lorsque vous traitez directement avec une ressource connue, il n'est pas nécessaire d'utiliser des routes imbriquées, comme cela a été discuté dans d'autres réponses ici.