Come progettare una semplice API CRUD REST

Question

Sto progettando una semplice API CRUD REST. Questa è la mia prima volta, quindi volevo avere un riscontro sul fatto che il mio progetto avesse un senso.

Sto utilizzando i metodi HTTP: GET, POST, DELETE e UPDATE. L'API consumerà e recupererà i dati in formato JSON. L'URL campione sarà come questo:

GET (list): curl http://<domain>/myapp/rest/v1/colors 
POST: curl -XPOST http://<domain>/myapp/rest/v1/colors -d '{ 
     "name": "red", 
     "shade": "light" 
     }' 
GET (single item): curl http://<domain>/myapp/rest/v1/colors/2 
DELETE: curl -XDELETE http://<domain>/myapp/rest/v1/colors/2 
etc... 

Domanda

Dopo la richiesta POST un record verrà creato nel database. Quindi, la richiesta POST dovrebbe restituire l'ID del record appena creato? In modo che l'ID può essere utilizzato in UPDATE, DELETE and GET (single item)?

Answer 1

Il HTTP specification definisce quanto segue POST:

Se una risorsa è stata creata sul server di origine, la risposta dovrebbe essere 201 (Opera) e contengono un'entità che descrive lo stato della richiesta e si riferisce alla nuova risorsa e un'intestazione di posizione (vedere la sezione 14.30).

Quindi questo significa essenzialmente:

• Si dovrebbe tornare 201 Created come codice di stato
• Si dovrebbe restituire un colpo di testa Location, indicando l'URI della risorsa appena creata
• Si può opzionalmente includere una rappresentazione della risorsa nell'entità di risposta POST per liberare il client dall'emissione di un'altra richiesta GET rispetto al valore ottenuto dall'intestazione Location.

Answer 2

Il POST deve restituire un nuovo reindirizzamento al nuovo URL per il singolo elemento.

Probabilmente si desidera perdere l'identificatore di versione degli URL.

Invece progettare le rappresentazioni e i client in un modo che gestisce con garbo varie versioni. Ad esempio, un client non dovrebbe dipendere da un formato specifico, ma solo dagli attributi di cui ha effettivamente bisogno.

Ciò che manca nella descrizione è il principio HATEOAS, ovvero il client non deve codificare gli URL, ma trovare gli URL per ulteriori azioni all'interno della rappresentazione di altre entità. Dato che non mostri un documento di esempio per i risultati restituiti dagli URL, non possiamo dire se lo hai fatto in un modo carino.

Partenza this presentation, spiega l'argomento e anche cita alcuni Primavera Biblioteca utile per la sua attuazione.