REST API PATCH ou PUT

Je souhaite concevoir mon sharepoint terminaison 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 sharepoint fin 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} 

La méthode PATCH est le bon choix ici car 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 méthode PUT est décrite comme suit:

Plusieurs applications développant le protocole HTTP (Hypertext Transfer Protocol) nécessitent une fonctionnalité pour effectuer une modification partielle des ressources. La méthode HTTP PUT existante permet uniquement le remplacement complet d’un document. Cette proposition ajoute une nouvelle méthode HTTP, PATCH, pour modifier une ressource HTTP existante.

Le R dans REST est synonyme de ressource

(Ce qui n’est pas vrai, car cela signifie Représentationnel, mais c’est une bonne astuce pour rappeler l’importance de Ressources dans REST).

A propos de PUT /groups/api/v1/groups/{group id}/status/activate : vous ne mettez pas à jour un “activate”. Un “activer” n’est pas une chose, c’est un verbe. Les verbes ne sont jamais de bonnes ressources. Une règle de base: si l’action, un verbe, est dans l’URL, ce n’est probablement pas RESTful .

Que faites-vous à la place? Soit vous “ajoutez”, “supprimez” ou “mettez à jour” une activation sur un groupe, soit vous préférez: manipuler une ressource “statut” sur un groupe. Personnellement, j’utiliserais des “activations” car elles sont moins ambiguës que le concept “statut”: créer un statut est ambigu, créer 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. Comme un groupe n’a qu’une seule activation, nous soaps à quelle ressource d’activation nous faisons référence.
  • PUT /groups/{group id}/activation Insère ou remplace l’ancienne activation. Comme un groupe n’a qu’une seule activation, nous soaps à quelle ressource d’activation nous faisons référence.
  • DELETE /groups/{group id}/activation Annule ou supprime l’activation.

Ce modèle est utile lorsque “l’activation” d’un groupe a des effets secondaires, tels que les paiements, les courriers envoyés, etc. Seuls les tests POST et PATCH peuvent avoir de tels effets secondaires. Lorsque, par exemple, une suppression d’une activation doit, par exemple, avertir les utilisateurs par courrier, DELETE n’est pas le bon choix. Dans ce cas, vous souhaiterez probablement créer une ressource de désactivation : POST /groups/{group_id}/deactivation .

Il est conseillé de suivre ces instructions, car ce contrat standard le rend très clair pour vos clients, ainsi que tous les proxy et couches entre le client et vous, lorsque vous pouvez réessayer en toute sécurité et quand vous ne le faites pas. Disons que le client est quelque part avec le wifi flaky, et que son utilisateur clique sur “deactive”, 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 ce qu’il peut gérer. Mais s’il déclenche un POST to deactivation il sait qu’il ne doit pas réessayer: le POST implique cela.
Tout client a maintenant un contrat qui, une fois suivi, protégera contre l’envoi de 42 emails “votre groupe a été désactivé”, simplement parce que sa bibliothèque HTTP réessayait l’appel au backend.

Mettre à jour un seul atsortingbut: utilisez PATCH

PATCH /groups/{group id}

Si vous souhaitez mettre à jour un atsortingbut. Par exemple, le “statut” peut être un atsortingbut sur les groupes pouvant être définis. Un atsortingbut tel que “status” est souvent un bon candidat à limiter à une liste blanche de valeurs. Les exemples utilisent un schéma JSON non défini:

 PATCH /groups/{group id} { "atsortingbutes": { "status": "active" } } response: 200 OK PATCH /groups/{group id} { "atsortingbutes": { "status": "deleted" } } response: 406 Not Acceptable 

Remplacement de 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 jette l’ancien, par exemple les identifiants peuvent restr 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 demande PUT , le client doit toujours envoyer la ressource entière, avec toutes les données nécessaires pour créer un nouvel élément: en général, les mêmes données que celles requirejses pour une création POST.

 PUT /groups/{group id} { "atsortingbutes": { "status": "active" } } response: 406 Not Acceptable PUT /groups/{group id} { "atsortingbutes": { "name": .... etc. "status": "active" } } response: 201 Created or 200 OK, depending on whether we made a new one. 

Une exigence très importante est que PUT soit idempotent: si vous avez besoin d’effets secondaires lors de la mise à jour d’un groupe (ou de la modification d’une activation), vous devez utiliser PATCH . Ainsi, lorsque la mise à jour se traduit par exemple par l’envoi d’un courrier, n’utilisez pas PUT .

Je recommande d’utiliser PATCH, car votre groupe de ressources possède 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 )

La méthode HTTP PUT existante permet uniquement le remplacement complet d’un document. Cette proposition ajoute une nouvelle méthode HTTP, PATCH, pour modifier une ressource HTTP existante.

Aussi, en plus de détails,

La différence entre les requêtes PUT et PATCH se reflète dans la façon dont le serveur traite l’entité incluse pour modifier la ressource.
identifié par l’URI de demande. Dans une requête PUT, l’entité incluse est considérée comme une version modifiée de la ressource stockée sur le
serveur d’origine, et le client demande que la version stockée
Est remis, remplacé. Avec PATCH, cependant, l’entité incluse contient un ensemble d’instructions décrivant comment une ressource résidant sur le
le serveur d’origine doit être modifié pour produire une nouvelle version. La méthode PATCH affecte la ressource identifiée par l’URI de demande, et
PEUT aussi avoir des effets secondaires sur d’autres ressources; ie, nouvelles ressources
peuvent être créés, ou existants, modifiés par l’application d’un
PIÈCE.

PATCH n’est ni sûr ni idempotent comme défini dans la [RFC2616], section 9.1.

Les clients doivent choisir quand utiliser PATCH plutôt que PUT. Pour
Par exemple, si la taille du document de patch est supérieure à la taille du
de nouvelles données de ressources qui seraient utilisées dans un PUT, alors cela pourrait faire
sens d’utiliser PUT au lieu de PATCH. Une comparaison avec le test POST est encore plus difficile, car le test POST est utilisé de diverses manières et peut
englober les opérations de type PUT et PATCH si le serveur le souhaite. Si
l’opération ne modifie pas la ressource identifiée par l’URI de demande de manière prévisible, POST doit être considéré à la place de PATCH
ou PUT.

Le code de réponse pour PATCH est

Le code de réponse 204 est utilisé car la réponse ne transporte pas un corps de message (ce qui aurait une réponse avec le code 200). Notez que d’autres codes de réussite peuvent également être utilisés.

référez-vous également à http://restcookbook.com/HTTP%20Methods/patch/

Avertissement: Une API implémentant PATCH doit patcher de manière atomique. Il ne doit pas être possible que les ressources soient à moitié corrigées à la demande d’un GET.

Puisque vous souhaitez concevoir une API en utilisant le style architectural REST, vous devez réfléchir à 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 atsortingbuer l’URI suivant et implémenter le support des méthodes GET et PUT:

 /groups/api/groups/{group id}/status 

L’inconvénient de cette approche par rapport à PATCH pour la modification est que vous ne serez pas en mesure d’apporter des modifications à 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, cela devrait être 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:

  Active  ...  

Un lien hypertexte est nécessaire pour remplir l’ hypermédia en tant que moteur de l’état de l’application du style architectural REST.

Je préfère généralement quelque chose de plus simple, comme activate / deactivate sous-ressource (lié par un en-tête Link avec rel=service ).

 POST /groups/api/v1/groups/{group id}/activate 

ou

 POST /groups/api/v1/groups/{group id}/deactivate 

Pour le consommateur, cette interface est extrêmement simple, et elle suit les principes REST sans vous embourber dans la conceptualisation des «activations» en tant que ressources individuelles.