Risposta a una richiesta POST HTTP idempotente

Question

Parte della nostra API RESTful consentirà agli utenti di registrare un articolo con un numero di serie. Poiché il numero di serie non è globalmente unico, non può essere utilizzato come identificativo della risorsa, quindi utilizzeremo un POST per la risorsa padre che genererà un identificatore, ad es.

POST /my/items 

<item serial-number="ABCDEF" /> 

Nel caso in cui l'elemento non sia già registrato, la semantica HTTP è ben definita. Restituiamo un'intestazione Location e l'elemento registrato come corpo dell'entità, ad es.

HTTP 201 Created 
Location: /my/items/1234  

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

Tuttavia, nel caso in cui l'articolo è già registrato, l'API deve essere idempotente e restituire l'articolo precedentemente registrata senza creare uno nuovo. La mia ipotesi migliore è che debba quindi restituire un codice di stato 200 OK e utilizzare l'intestazione Content-Location per indicare da dove proviene effettivamente l'elemento, ad es.

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

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

Questo sembra ragionevole? Non sono del tutto chiaro se la Location o Content-Location sia più adatta nel secondo caso.

Answer 1

Ho avuto un simile requisito di recente. Per le operazioni idempotenti PUT è il modo migliore. Hai ragione c'è una discrepanza tra l'id esterno e quello interno. Ho risolto con la creazione di una risorsa dedicata per il target ID esterno:

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

Internamente ho risolverlo come CREATE nel caso in cui non ho alcun elemento per 'username' e il numero di serie 'ABCDEF' o UPDATE nel caso in cui lo faccio .

Nel caso in cui fosse un CREATE, restituisco 201 per un UPDATE 200. Inoltre, il carico utile restituito contiene sia l'ID nazionale che il numero di serie esterno come suggerito nel payload.

Answer 2

Here è un'interessante discussione sugli usi delle due intestazioni. La posizione del contenuto non è definita per PUT o POST, quindi la posizione è probabilmente l'opzione migliore nel tuo caso. Non è certamente chiaro che è meglio però.

Nel complesso, penso che il tuo approccio abbia un senso.