web-dev-qa-db-fra.com

REST API DESIGN - Obtention d'une ressource via REST avec des paramètres différents mais le même modèle d'URL

J'ai une question liée à REST url. J'ai trouvé quelques messages pertinents ici: Représentations RESTful différentes de la même ressource et ici: RL RESTful to GET ressource par différents champs mais les réponses ne sont pas très claires sur ce que sont les meilleures pratiques et pourquoi. Voici un exemple.

J'ai des URL REST pour représenter la ressource "utilisateurs". Je peux obtenir un utilisateur avec un identifiant ou une adresse électronique, mais la représentation de l'URL reste la même pour les deux. Parcourir beaucoup de blogs et livres, je vois que les gens le font de différentes façons, par exemple

lisez cette pratique dans un livre et quelque part sur stackoverflow (je n'arrive pas à retrouver le lien)

GET /users/id={id}
GET /users/email={email}

lire cette pratique sur beaucoup de blogs

GET /users/{id}
GET /users/email/{email}

Les paramètres de requête sont normalement utilisés pour filtrer les résultats des ressources représentées par l'URL, mais j'ai déjà vu cette pratique être utilisée

GET /users?id={id}
GET /users?email={email}

Ma question est, parmi toutes ces pratiques, laquelle serait la plus sensée pour les développeurs qui consomment les API et pourquoi? Je crois qu'il n'y a pas de règles immuables en matière de conceptions d'URL et de conventions de nommage REST url, mais je voulais simplement savoir quelle route je devrais prendre pour aider les développeurs à mieux comprendre les API.

Toute aide appréciée!

resturljax-rsurl-schemeurl-pattern
64
shahshi15

Dans mon expérience, GET /users/{id} GET /users/email/{email} est l’approche la plus courante. Je m'attendrais également à ce que les méthodes renvoient un 404 non trouvé si un utilisateur n'existe pas avec le id ou le email fourni. Je ne serais pas surpris de voir GET /users/id/{id}, non plus (bien qu'à mon avis, il soit redondant).

Commentaires sur les autres approches

  1. GET /users/id={id} GET /users/email={email}
    • Je ne pense pas avoir vu cela, et si je le voyais, ce serait très déroutant. C'est presque comme si on essayait d'imiter les paramètres de requête avec les paramètres de chemin.
  2. GET /users?id={id} GET /users?email={email}
    • Je pense que vous avez frappé le clou lorsque vous avez mentionné l'utilisation de paramètres de requête pour le filtrage.
    • Est-il logique d’appeler cette ressource avec à la fois un id et un email (par exemple, GET /users?id={id}&email={email})? Sinon, je n'utiliserais pas une méthode de ressource unique comme celle-ci.
    • Je m'attendrais à ce que cette méthode récupère une liste d'utilisateurs avec des paramètres de requête facultatifs pour le filtrage, mais je ne m'attendrais pas à id, email ou tout identifiant unique faisant partie des paramètres. Par exemple: GET /users?status=BANNED pourrait renvoyer une liste d'utilisateurs bannis.

Départ cette réponse d'une question connexe.

81
DannyMo

En regardant cela de manière pragmatique, vous avez une collection d'utilisateurs:

/users   # this returns many

Chaque utilisateur a un emplacement de ressource dédié:

/users/{id}    # this returns one

Vous avez également plusieurs façons de rechercher des utilisateurs:

/users?email={email}
/users?name=*bob*

Comme ce sont tous des paramètres de requête à/utilisateurs, ils devraient tous renvoyer des listes .. même s'il s'agit d'une liste de 1.

J'ai écrit ici un article sur la conception pragmatique des API RESTful qui en parle, entre autres, ici: http://www.vinaysahni.com/best-practices-for-a-pragmatic-restful-api

32
Vinay Sahni

A propos des ressources utilisateur

sur le chemin /users vous obtiendrez toujours une ressource de collection retournée.

sur le chemin /users/[user_id] vous obtiendrez une ressource singleton représentant l’utilisateur avec son identifiant [id_utilisateur] ou une réponse 404 s’il n’existe aucun utilisateur avec le [id_utilisateur] demandé (ou interdit (401) si vous n’êtes pas autorisé à accéder à la ressource utilisateur demandée, etc). Chaque chemin de ressources n'a qu'un seul identifiant et vous l'utilisez pour rechercher/identifier les ressources. Il n'est pas possible d'utiliser plusieurs identificateurs pour la même ressource sur le même chemin de ressource. Si vous obtenez une ressource renvoyée dans une réponse, cet identifiant est inclus dans la réponse en tant que fichier HREF autonome pour localiser/identifier la ressource.

Vous pouvez interroger le chemin /users avec GET/paramètres de requête. Cela renverra une collection avec les utilisateurs qui répondent aux critères demandés. La collection renvoyée contient les ressources utilisateur, le tout avec leur propre identifiant HREF.

À propos des ressources de messagerie

Si je regarde ce que vous avez suggéré pour le courrier électronique, je préférerais penser à ce qui suit:

Les e-mails des utilisateurs sont également des ressources. Donc, je penserais que /users/[user_id]/emails renvoie un ensemble d’adresses électroniques pour les utilisateurs portant l’identifiant user_id. /users/[user_id]/emails/[email_id] renvoie l'e-mail de l'utilisateur avec user_id et ['email_id']. Ce que vous utilisez comme identifiant dépend de vous, mais je m'en tiens à un entier. Vous pouvez supprimer un courrier électronique de l'utilisateur en envoyant une demande DELETE au chemin qui identifie le courrier électronique que vous souhaitez supprimer. Ainsi, par exemple, DELETE sur /users/[user_id]/emails/[email_id] supprime l’email avec email_id qui appartient à l’utilisateur avec user_id. Très probablement, seul cet utilisateur est autorisé à effectuer cette opération de suppression. Les autres utilisateurs recevront une réponse 401.

Si un utilisateur ne peut avoir qu'une seule adresse électronique, vous pouvez vous en tenir à /users/[user_id]/email Ceci retourne une ressource singleton. L'utilisateur peut mettre à jour son adresse email en PUTting ou POSTing avec une nouvelle adresse email à cette adresse. Si, dans votre application, vous n'autorisez pas les utilisateurs sans courrier électronique, vous devez répondre par un 401 s'il envoie une demande DELETE à cette URL.

2
Wilt