Je souhaite concevoir mon point de terminaison de repos avec la méthode appropriée pour le scénario suivant.
Il y a un groupe. Chaque groupe a un statut. Le groupe peut être activé ou désactivé par l'administrateur.
Dois-je concevoir mon point final comme
PUT /groups/api/v1/groups/{group id}/status/activate
OU
PATCH /groups/api/v1/groups/{group id}
with request body like
{action:activate|deactivate}
http
rest
http-put
http-method
http-patch
java_geek
la source
la source
activate
" n'est pas une construction RESTful adéquate. Vous essayez probablement de mettre à jour lestatus
"actif" ou le "désactivé". auquel cas vous pouvez PATCHER.../status
avec la chaîne "active" ou "désactivante" dans le corps. Ou si vous essayez de mettre à jour un booléen àstatus.active
, vous pouvez CORRIGER.../status/active
avec le booléen dans le corpsRéponses:
La
PATCH
méthode est le bon choix ici lorsque vous mettez à jour une ressource existante - l'ID de groupe.PUT
ne doit être utilisé que si vous remplacez une ressource dans son intégralité.De plus amples informations sur la modification partielle des ressources sont disponibles dans la RFC 5789 . Plus précisément, la
PUT
méthode est décrite comme suit:la source
Le R dans REST est synonyme de ressource
(Ce qui n'est pas vrai, car il signifie représentationnel, mais c'est une bonne astuce pour se souvenir de l'importance des ressources dans REST).
À propos
PUT /groups/api/v1/groups/{group id}/status/activate
: vous ne mettez pas à jour un "activer". Un "activer" n'est pas une chose, c'est un verbe. Les verbes ne sont jamais de bonnes ressources. Une règle d'or: si l'action, un verbe, est dans l'URL, elle n'est probablement pas RESTful .Que fais-tu à la place? Soit vous "ajoutez", "supprimez" ou "mettez à jour" une activation sur un groupe, soit si vous préférez: manipuler une ressource "état" sur un groupe. Personnellement, j'utiliserais des «activations» car elles sont moins ambiguës que le concept de «statut»: la création d'un statut est ambiguë, la création d'une activation ne l'est pas.
POST /groups/{group id}/activation
Crée (ou demande la création de) une activation.PATCH /groups/{group id}/activation
Met à jour certains détails d'une activation existante. Puisqu'un groupe n'a qu'une seule activation, nous savons à quelle ressource d'activation nous faisons référence.PUT /groups/{group id}/activation
Insère ou remplace l'ancienne activation. Puisqu'un groupe n'a qu'une seule activation, nous savons à quelle ressource d'activation nous faisons référence.DELETE /groups/{group id}/activation
Annulera ou supprimera l'activation.Ce modèle est utile lorsque «l'activation» d'un groupe a des effets secondaires, tels que des paiements en cours, des courriers envoyés, etc. Seuls POST et PATCH peuvent avoir de tels effets secondaires. Lorsque, par exemple, la suppression d'une activation doit, par exemple, avertir les utilisateurs par courrier électronique, SUPPRIMER n'est pas le bon choix; dans ce cas , vous voulez probablement créer une ressource de désactivation :
POST /groups/{group_id}/deactivation
.C'est une bonne idée de suivre ces directives, car ce contrat standard indique très clairement pour vos clients, et toutes les procurations et couches entre le client et vous, sachez quand il est sûr de réessayer et quand ce n'est pas le cas. Disons que le client est quelque part avec un wifi floconneux, et son utilisateur clique sur "désactiver", ce qui déclenche un
DELETE
: Si cela échoue, le client peut simplement réessayer, jusqu'à ce qu'il obtienne un 404, 200 ou tout autre chose qu'il peut gérer. Mais s'il déclenche unPOST to deactivation
il sait ne pas réessayer: le POST l'implique.Tout client a maintenant un contrat qui, une fois suivi, protégera contre l'envoi de 42 e-mails "votre groupe a été désactivé", tout simplement parce que sa bibliothèque HTTP a continué de relancer l'appel vers le backend.
Mise à jour d'un seul attribut: utilisez PATCH
PATCH /groups/{group id}
Si vous souhaitez mettre à jour un attribut. Par exemple, le "statut" pourrait être un attribut sur les groupes qui peut être défini. Un attribut tel que "status" est souvent un bon candidat pour se limiter à une liste blanche de valeurs. Les exemples utilisent un schéma JSON non défini:
Remplacer la ressource, sans effets secondaires, utilisez PUT.
PUT /groups/{group id}
Si vous souhaitez remplacer un groupe entier. Cela ne signifie pas nécessairement que le serveur crée réellement un nouveau groupe et rejette l'ancien, par exemple les identifiants peuvent rester les mêmes. Mais pour les clients, c'est ce que PUT peut signifier: le client doit supposer qu'il obtient un élément entièrement nouveau, basé sur la réponse du serveur.
En cas de
PUT
demande, le client doit toujours envoyer l'intégralité de la ressource, avec toutes les données nécessaires à la création d'un nouvel élément: généralement les mêmes données que celles nécessaires à une création POST.Une exigence très importante
PUT
est idempotente: si vous avez besoin d'effets secondaires lors de la mise à jour d'un groupe (ou de la modification d'une activation), vous devez l'utiliserPATCH
. Donc, lorsque la mise à jour se traduit par exemple par l'envoi d'un mail, ne l'utilisez pasPUT
.la source
Je recommanderais d'utiliser PATCH, car votre «groupe» de ressources a de nombreuses propriétés mais dans ce cas, vous ne mettez à jour que le champ d'activation (modification partielle)
selon la RFC5789 ( https://tools.ietf.org/html/rfc5789 )
De plus, plus en détail,
Le code de réponse pour PATCH est
référez-vous également à http://restcookbook.com/HTTP%20Methods/patch/
la source
Puisque vous souhaitez concevoir une API en utilisant le style architectural REST, vous devez penser à vos cas d'utilisation pour décider quels concepts sont suffisamment importants pour être exposés en tant que ressources. Si vous décidez d'exposer le statut d'un groupe en tant que sous-ressource, vous pouvez lui donner l'URI suivant et implémenter la prise en charge des méthodes GET et PUT:
L'inconvénient de cette approche sur PATCH pour la modification est que vous ne pourrez pas modifier plus d'une propriété d'un groupe de manière atomique et transactionnelle. Si les modifications transactionnelles sont importantes, utilisez PATCH.
Si vous décidez d'exposer le statut en tant que sous-ressource d'un groupe, il doit s'agir d'un lien dans la représentation du groupe. Par exemple, si l'agent obtient le groupe 123 et accepte XML, le corps de la réponse peut contenir:
Un lien hypertexte est nécessaire pour remplir l' hypermédia en tant que moteur de la condition d'état d' application du style architectural REST.
la source
Je préfère généralement quelque chose d'un peu plus simple, comme
activate
/deactivate
sub-resource (lié par un en-Link
tête avecrel=service
).ou
Pour le consommateur, cette interface est extrêmement simple, et elle suit les principes REST sans vous enliser dans la conceptualisation des "activations" en tant que ressources individuelles.
la source
Une option possible pour implémenter un tel comportement est
Et évidemment, si quelqu'un a besoin de le désactiver,
PUT
aura leDeactivated
statut JSON.En cas de nécessité d'activation / désactivation de masse,
PATCH
peut entrer dans le jeu (pas pour le groupe exact, mais pour lagroups
ressource:En général, c'est l'idée comme @Andrew Dobrowolski le suggère, mais avec de légers changements dans la réalisation exacte.
la source