En réponse à une requête HTTP POST idempotent

Question

Une partie de notre API RESTful permettra aux utilisateurs d'enregistrer un élément avec un numéro de série. Comme le numéro de série est pas globalement unique, il ne peut pas être utilisé comme identifiant de la ressource, donc nous allons utiliser un POST à ​​la ressource mère qui va générer un identifiant, par exemple

POST /my/items 

<item serial-number="ABCDEF" /> 

Dans le cas où l'élément n'est pas déjà enregistré, la sémantique HTTP est bien définie. Nous retournons un en-tête Location et l'élément enregistré en tant que corps d'entité, par ex.

HTTP 201 Created 
Location: /my/items/1234  

<item id="1234" serial-number="ABCDEF" /> 

Cependant, dans le cas où l'élément est déjà enregistré, l'API devrait être idempotent et retourner l'élément précédemment enregistré sans créer un nouveau. Ma meilleure estimation est qu'il devrait alors retourner un code d'état 200 OK, et utiliser l'en-tête Content-Location pour indiquer d'où vient réellement l'élément, par ex.

HTTP 200 OK 
Content-Location: /my/items/1234  

<item id="1234" serial-number="ABCDEF" /> 

Cela vous semble-t-il raisonnable? Je ne suis pas tout à fait clair si l'emplacement ou le contenu-emplacement est plus approprié dans le second cas.

Answer 1

j'avais besoin similaire récemment. Pour les opérations idempotentes PUT est le meilleur moyen. Vous avez raison, il existe une discordance entre l'identifiant externe et l'identifiant interne. Je l'ai résolu en créant une ressource dédiée à la cible id externe:

PUT /api-user/{username}/items/{serialNumber} 

interne je le résoudre comme CREER au cas où j'ai aucun élément pour le numéro de série « nom d'utilisateur » et « ABCDEF » ou UPDATE dans le cas où je .

Dans le cas où il s'agissait d'un CREATE, je renvoie 201 pour une UPDATE 200. En outre, la charge utile retournée contient à la fois l'ID maison et le numéro de série externe comme vous l'avez suggéré dans votre charge utile.

Answer 2

Here est une discussion intéressante sur les usages des deux têtes. Il prétend Content-Location n'est pas défini pour PUT ou POST donc Location est probablement la meilleure option dans votre cas. Ce n'est certainement pas clair, mais c'est mieux.

Je pense que l'ensemble de votre approche est logique cependant.