Free Press

Le API REST permettono di sviluppare qualsiasi tipo di applicazione web con tutte le possibili operazioni CRUD (creare, recuperare, aggiornare, cancellare). Le linee guida REST suggeriscono di usare uno specifico metodo HTTP per un particolare tipo di chiamata fatta al server (anche se tecnicamente è possibile violare questa linea guida, ma è altamente sconsigliato).

Utilizzare le informazioni fornite di seguito per trovare un metodo HTTP adatto all’azione eseguita dall’API.

Table of ContentsHTTP GETHTTP POSTHTTP PUTHTTP DELETEHTTP PATCHSummaryGlossary

HTTP GET

Utilizzare le richieste GET per recuperare solo la rappresentazione/informazione della risorsa – e non per modificarla in alcun modo. Poiché le richieste GET non cambiano lo stato della risorsa, questi sono detti metodi sicuri. Inoltre, le API GET dovrebbero essere idempotenti, il che significa che fare più richieste identiche deve produrre lo stesso risultato ogni volta finché un’altra API (POST o PUT) non abbia cambiato lo stato della risorsa sul server.

Se l’URI della richiesta si riferisce a un processo che produce dati, sono i dati prodotti che devono essere restituiti come entità nella risposta e non il testo sorgente del processo, a meno che quel testo sia l’output del processo.

Per qualsiasi API HTTP GET, se la risorsa viene trovata sul server, allora deve restituire il codice di risposta HTTP 200 (OK) – insieme al corpo della risposta, che di solito è un contenuto XML o JSON (a causa della loro natura indipendente dalla piattaforma). Allo stesso modo, se si determina che la richiesta GET stessa non è formata correttamente allora il server restituirà il codice di risposta HTTP 400 (BAD REQUEST).

Esempio di URI di richiesta

• HTTP GET http://www.appdomain.com/users
• HTTP GET http://www.appdomain.com/users?size=20&page=5
• HTTP GET http://www.appdomain.com/users/123
• HTTP GET http://www.appdomain.com/users/123/address

HTTP POST

Utilizza le API POST per creare nuove risorse subordinate, per es, un file è subordinato a una directory che lo contiene o una riga è subordinata a una tabella di database. Quando si parla strettamente in termini di REST, i metodi POST sono usati per creare una nuova risorsa nella collezione di risorse.

In definitiva, se una risorsa è stata creata sul server di origine, la risposta DOVREBBE essere HTTP response code 201 (Created) e contenere un’entità che descrive lo stato della richiesta e si riferisce alla nuova risorsa, e un header Location.

Molte volte, l’azione eseguita dal metodo POST potrebbe non risultare in una risorsa che può essere identificata da un URI. In questo caso, il codice di risposta HTTP 200 (OK) o 204 (No Content) è lo stato di risposta appropriato.

Le risposte a questo metodo non sono memorizzabili nella cache, a meno che la risposta includa i campi di intestazione Cache-Control o Expires appropriati.

Si noti che POST non è né sicuro né idempotente, e invocando due richieste POST identiche si otterranno due risorse diverse contenenti le stesse informazioni (tranne gli id delle risorse).

Esempio di URI di richiesta

• HTTP POST http://www.appdomain.com/users
• HTTP POST http://www.appdomain.com/users/123/accounts

HTTP PUT

Utilizza le API PUT principalmente per aggiornare la risorsa esistente (se la risorsa non esiste, allora le API possono decidere di creare o meno una nuova risorsa). Se una nuova risorsa è stata creata dall’API PUT, il server di origine DEVE informare l’interprete tramite il codice di risposta HTTP 201 (Created) e se una risorsa esistente viene modificata, i codici di risposta 200 (OK) o 204 (No Content) DOVREBBERO essere inviati per indicare il completamento con successo della richiesta.

Se la richiesta passa attraverso una cache e il Request-URI identifica una o più entità attualmente in cache, quelle voci DOVREBBERO essere trattate come stantie. Le risposte a questo metodo non sono memorizzabili nella cache.

Esempio di URI di richiesta

• HTTP PUT http://www.appdomain.com/users/123
• HTTP PUT http://www.appdomain.com/users/123/accounts/456

HTTP DELETE

Come dice il nome, le API DELETE sono usate per cancellare risorse (identificate dal Request-URI).

Una risposta di successo delle richieste DELETE DOVREBBE essere la risposta HTTP code 200 (OK) se la risposta include un’entità che descrive lo stato, 202 (Accepted) se l’azione è stata accodata, o 204 (No Content) se l’azione è stata eseguita ma la risposta non include un’entità.

Le operazioni DELETE sono idempotenti. Se si elimina una risorsa, questa viene rimossa dalla collezione di risorse. Chiamare ripetutamente l’API DELETE su quella risorsa non cambierà il risultato – tuttavia, chiamare DELETE su una risorsa una seconda volta restituirà un 404 (NOT FOUND) poiché è già stata rimossa. Alcuni potrebbero sostenere che questo rende il metodo DELETE non idempotente. È una questione di discussione e di opinione personale.

Se la richiesta passa attraverso una cache e il Request-URI identifica una o più entità attualmente in cache, quelle voci DOVREBBERO essere trattate come stantie. Le risposte a questo metodo non sono memorizzabili nella cache.

Esempio di URI di richiesta

• HTTP DELETE http://www.appdomain.com/users/123
• HTTP DELETE http://www.appdomain.com/users/123/accounts/456

HTTP PATCH

Le richiesteHTTP PATCH sono per fare un aggiornamento parziale su una risorsa. Se vedi che le richieste PUT modificano anche un’entità della risorsa, quindi per rendere più chiaro – il metodo PATCH è la scelta corretta per aggiornare parzialmente una risorsa esistente, e PUT dovrebbe essere usato solo se stai sostituendo una risorsa nella sua interezza.

Si prega di notare che ci sono alcune sfide se si decide di utilizzare PATCH API nella tua applicazione:

• Il supporto per PATCH in browser, server e framework di applicazioni web non è universale. IE8, PHP, Tomcat, Django, e molti altri software hanno un supporto mancante o rotto per esso.
• Il payload di una richiesta PATCH non è semplice come lo è per la richiesta PUT.

  HTTP GET /users/1

  produce la seguente risposta:

  {id: 1, username: 'admin', email: ''}

  Un esempio di richiesta di patch per aggiornare l’email sarà come questo:

  HTTP PATCH /users/1

  ” }
  ]

Ci possono essere le seguenti operazioni possibili secondo la specifica HTTP.

},
{ "op": "replace", "path": "/a/b/c", "value": 42 },
{ "op": "move", "from": "/a/b/c", "path": "/a/b/d" },
{ "op": "copy","from": "/a/b/d", "path": "/a/b/e" }
]

Il metodo PATCH non sostituisce i metodi POST o PUT. Applica un delta (diff) piuttosto che sostituire l’intera risorsa.

Sommario dei metodi HTTP per le API RESTful

La seguente tabella riassume l’uso dei metodi HTTP discussi sopra.

Glossario

Metodi sicuri

Come da specifica HTTP, i metodi GET e HEAD dovrebbero essere usati solo per recuperare rappresentazioni di risorse – e non aggiornano/cancellano la risorsa sul server. Entrambi i metodi sono considerati “sicuri”.

Questo permette agli interpreti di rappresentare altri metodi, come POST, PUT e DELETE, in un modo unico in modo che l’utente sia consapevole del fatto che viene richiesta un’azione possibilmente non sicura – e possono aggiornare/cancellare la risorsa sul server e quindi dovrebbero essere usati con attenzione.

Metodi Idempotenti

Il termine idempotente è usato in modo più completo per descrivere un’operazione che produrrà gli stessi risultati se eseguita una o più volte. L’idempotenza è una proprietà utile in molte situazioni, in quanto significa che un’operazione può essere ripetuta o riprovata tutte le volte che è necessario senza causare effetti indesiderati. Con operazioni non idempotenti, l’algoritmo potrebbe dover tenere traccia del fatto che l’operazione sia già stata eseguita o meno.

Nelle specifiche HTTP, i metodi GET, HEAD, PUT e DELETE sono dichiarati metodi idempotenti. Gli altri metodi OPTIONS e TRACE NON DEVONO avere effetti collaterali, quindi entrambi sono anche intrinsecamente idempotenti.

.