Nella progettazione dell'API RESTful, PUT e PATCH sono due metodi HTTP utilizzati per aggiornare le risorse sul server, ma la differenza tra PUT e PATCH nelle API REST sta nel modo in cui eseguono gli aggiornamenti e negli scenari in cui ciascuno è più appropriato. Entrambi i metodi sono progettati per modificare i dati esistenti, ma comprendere la differenza PUT e PATCH nell'API REST può aiutare gli sviluppatori a fare la scelta migliore in base alla natura dell'aggiornamento che devono eseguire. In questo post del blog, esploreremo la differenza PUT e PATCH nell'API REST, concentrandoci sul dibattito PATCH e aggiornamento REST, su quando utilizzarli ciascuno e forniremo indicazioni sulla scelta del metodo giusto per diversi casi d'uso.
Cos'è il PUT nelle API REST?
Per comprendere la differenza tra PUT e PATCH nelle API REST, dobbiamo innanzitutto sapere cos'è PUT. Basato su Sezione 9.6 RFC 2616, il metodo PUT nell'API REST richiede che l'entità racchiusa venga archiviata nell'URI di richiesta fornito.
Se l'URI della richiesta fa riferimento a una risorsa già esistente, l'entità racchiusa DOVREBBE essere considerata come una versione modificata di quella residente sul server di origine. Se l'URI di richiesta non punta a una risorsa esistente e quell'URI può essere definito come una nuova risorsa dall'agente utente richiedente, il server di origine può creare la risorsa con quell'URI.
In altre parole, il metodo PUT viene utilizzato per aggiornare un'intera risorsa sul server. Ciò rende PUT un aggiornamento più “completo”, spesso utilizzato quando è necessaria una sostituzione completa della risorsa.
Quindi, PUT è la soluzione migliore per i seguenti casi d'uso:
- Aggiornamento di una risorsa completa (ad esempio, aggiornamento di un profilo utente con tutte le nuove informazioni).
- Sostituzione di un intero elemento o record.
- Quando l'identità della risorsa è chiara e i suoi dati devono essere completamente aggiornati.
In sistemi come Ricerca elastica, le operazioni idempotenti sono necessarie per garantire la coerenza dei dati. Ad esempio, l'aggiornamento di un documento in Elasticsearch utilizzando PUT garantisce che la stessa richiesta possa essere ripetuta senza effetti collaterali indesiderati.
Cos'è PATCH nelle API REST?
Ora che abbiamo trattato PUT nelle API REST, diamo un'occhiata a cos'è PATCH nelle API REST e come funziona prima di confrontare PUT e PATCH nelle API REST. Come definito in RFC5789, il metodo PATCH nell'API REST richiede che una serie di modifiche descritte nell'entità della richiesta venga applicata alla risorsa identificata dall'URI della richiesta.
Ciò è in linea con la distinzione API PUT e PATCH REST, in cui si inviano solo i dati che devono essere modificati e il server applica tali modifiche alla risorsa esistente senza alterare l'intera risorsa. Gli sviluppatori spesso creano patch per rappresentare queste modifiche incrementali, garantendo un trasferimento minimo di dati e aggiornamenti efficienti.
Ecco perché il metodo PATCH nell'API REST è più adatto ai seguenti casi d'uso:
- Aggiornamento solo di un sottoinsieme di campi in una risorsa (ad esempio, modifica dell'indirizzo email o del numero di telefono di un utente). Un esempio di API PATCH potrebbe comportare l'invio solo della nuova email, lasciando intatti gli altri campi.
- Migliorare le prestazioni riducendo al minimo il carico utile dei dati.
- Quando desideri aggiornare una risorsa in modo incrementale anziché sostituirla completamente.
- Crea patch per incapsulare modifiche di campi specifici, come la modifica dell'e-mail di un utente, senza influire sui dati non correlati.
Per piattaforme come CMS senza testa che spesso gestiscono strutture di contenuto complesse, l'utilizzo di PATCH per aggiornamenti più piccoli, come la modifica di un singolo campo, può ridurre il carico del server e migliorare le prestazioni.
Con questi due metodi trattati, dovresti avere una buona idea di cosa sono PUT e PATCH nelle API REST. Tuttavia, prima di approfondire la differenza tra PUT e PATCH nelle API REST, dobbiamo parlare dell'idempotenza in questi due metodi.
Idempotenza in PUT Vs Patch nelle API REST
Nelle API REST, l'idempotenza si riferisce alla proprietà di un'operazione che, se ripetuta più volte con gli stessi input, produce lo stesso risultato. Ciò significa che effettuare più volte la stessa richiesta dovrebbe avere lo stesso effetto sul server, indipendentemente da quante volte viene eseguita. Questo è importante per garantire stabilità e prevedibilità in un'API. Ma in che modo è rilevante per la differenza PUT e PATCH nell'API REST?
Metodo PUT e Idempotenza
Il metodo PUT nell'API REST è sempre idempotente perché è progettato per sostituire l'intera risorsa in un URI specificato con i dati forniti nella richiesta. In altre parole, se esegui più volte una richiesta PUT con gli stessi dati di risorsa, il risultato sarà sempre lo stesso.
Perché PUT è idempotente? Quando effettui una richiesta PUT, stai essenzialmente dicendo al server: "Questo è lo stato completo ed esatto che desidero per questa risorsa". Sia che si emetta la richiesta PUT una o più volte, la risorsa risultante sarà sempre identica.
Ad esempio, considera lo scenario in cui aggiorni l'indirizzo email di un utente. Se si effettua più volte la stessa richiesta PUT, il risultato non verrà alterato perché la risorsa viene sostituita ogni volta dagli stessi dati.
Esempio:
| PUT /users/1{"nomeutente": "john_doe","email": "[email protected]"} |
Se invii questa richiesta più volte, il risultato sarà sempre lo stesso:
| {"nome utente": "john_doe","e-mail": "[email protected]"} |
Anche se i dati dell’utente sono già questi, inviare nuovamente la richiesta non cambia nulla. Sostituisce i dati con gli stessi dati, quindi l'effetto della richiesta rimane lo stesso indipendentemente da quante volte viene ripetuta. Questo è ciò che rende PUT idempotente.
Metodo PATCH e Idempotenza
D'altra parte, anche il metodo PATCH nell'API REST è generalmente idempotente, ma con maggiore flessibilità. Quando crei le patch, assicurati che le operazioni siano idempotenti (ad esempio, l'impostazione di un valore) per evitare effetti collaterali indesiderati derivanti da richieste ripetute. Il fatto che PATCH sia idempotente dipende dall'operazione e dai dati modificati.
Perché PATCH è idempotente? Per le richieste PATCH, l'idempotenza significa che applicare la stessa patch più volte avrà lo stesso risultato. Ciò è vero purché il cerotto stesso non causi ulteriori effetti collaterali o modifiche se applicato ripetutamente. Se continui ad applicare la stessa patch con gli stessi dati, il risultato dovrebbe rimanere invariato dopo la prima applicazione.
Ad esempio, se stai aggiornando solo l'e-mail di un utente, inviare ripetutamente la stessa richiesta PATCH non modificherà il risultato dopo la prima volta, anche se la richiesta viene effettuata più volte. L'e-mail dell'utente rimarrà la stessa e lo stato della risorsa non cambierà.
Esempio API PATCH:
| PATCH /users/1{“email”: “[email protected]”} |
Se l'e-mail era già [email protected], applicare nuovamente questa PATCH non comporterà alcuna modifica, rendendola idempotente.
Tuttavia, in alcuni casi, PATCH può anche essere non idempotente. Ad esempio, se un'operazione PATCH modifica un contatore o aggiunge elementi a un elenco (come l'incremento di un numero o l'aggiunta a un array), applicazioni ripetute dello stesso PATCH potrebbero portare a risultati diversi. Ciò violerebbe la proprietà di idempotenza.
Esempio di PATCH REST API non idempotente:
| PATCH /contatore/1{"incremento": 1} |
Se applichi ripetutamente questa PATCH, il contatore continuerà ad aumentare, producendo ogni volta valori diversi. Questo non è idempotente perché il risultato cambia con ogni applicazione.
Ora che conosci gli elementi essenziali, possiamo esaminare alcuni scenari di esempio per comprendere meglio la differenza tra PUT e PATCH nelle API REST.
Scenari di esempio: PUT e PATCH nelle API REST
Teoria a parte, diamo un'occhiata alla differenza tra PUT e PATCH con esempi, incluse operazioni idempotenti e non idempotenti.
Scenario 1: richiesta PUT: sostituzione di un'intera risorsa
Immagina un endpoint API per la gestione dei prodotti in un sistema di e-commerce. È necessario aggiornare tutti i dettagli di un prodotto, inclusi nome, prezzo e descrizione. Questo è un tipico esempio del metodo HTTP PUT vs PATCH, dove PUT viene utilizzato per sostituire l'intera risorsa del prodotto.
Prodotto iniziale:
| OTTIENI /products/1001{“id”: 1001,”name”: “Laptop”,”price”: 999,99,”description”: “Un potente laptop.”} |
Desideri aggiornare il prezzo e la descrizione del prodotto. Invii una richiesta PUT con l'intera risorsa:
Richiesta PUT:
| PUT /products/1001{“id”: 1001,”name”: “Laptop”,”price”: 899,99,”description”: “Un potente laptop scontato.”} |
Se effettui questa richiesta PUT una o più volte, il risultato sarà sempre lo stesso. I dettagli del prodotto verranno aggiornati per riflettere il nuovo prezzo e la nuova descrizione e ogni volta si verificherà lo stesso risultato. Ciò garantisce la natura idempotente di PUT.
Risultato (dopo la richiesta PUT):
| {"id": 1001,"nome": "Laptop","prezzo": 899,99,"descrizione": "Un potente laptop scontato."} |
Scenario 2: Richiesta PATCH – Aggiornamento di parte di una risorsa
Consideriamo ora una richiesta PATCH per aggiornare solo una parte dei dettagli del prodotto, come ad esempio la descrizione. Esempio API PATCH: se desideri modificare la descrizione del prodotto ma non il suo prezzo, PATCH è la scelta migliore. Per implementare ciò, creerai patch contenenti solo i campi che richiedono modifiche, come la descrizione in questo esempio API REST PATCH.
Prodotto iniziale:
| OTTIENI /products/1001{“id”: 1001,”name”: “Laptop”,”price”: 999,99,”description”: “Un potente laptop.”} |
Richiesta PATCH:
| PATCH /products/1001{“descrizione”: "Un laptop leggero e potente."} |
Quando invii questa richiesta PATCH, verrà aggiornato solo il campo della descrizione. Se invii più volte la stessa richiesta PATCH, la descrizione rimarrà invariata dopo il primo aggiornamento, rendendo la richiesta idempotente.
Risultato (dopo la richiesta PATCH):
| {"id": 1001,"nome": "Laptop","prezzo": 999,99,"descrizione": "Un laptop leggero e potente."} |
Se applichi nuovamente la stessa PATCH, la descrizione del prodotto sarà sempre la stessa che era dopo la prima PATCH. Il risultato è coerente, il che rende PATCH idempotente in questo scenario.
Scenario 3: richiesta PATCH: operazione non idempotente
Diamo un'occhiata a un'operazione PATCH non idempotente. Supponiamo che esista un endpoint per il saldo del portafoglio di un utente e che desideri incrementare il saldo. Un esempio di differenza tra PUT e PATCH può essere illustrato qui: PATCH aggiungerà ogni volta un valore al saldo
Portafoglio iniziale:
| GET /users/1/wallet{“id”: 1,”saldo”: 100,00} |
Richiesta PATCH:
| PATCH /utenti/1/portafoglio{“incremento”: 50.00} |
Questa richiesta PATCH aumenterà il saldo del portafoglio di $ 50. Se invii questa richiesta PATCH più volte, il saldo continuerà ad aumentare con ogni PATCH, portando ogni volta a un risultato diverso. Questo non è idempotente perché applicare ripetutamente la stessa PATCH causerà un risultato diverso.
Risultato (dopo la prima richiesta PATCH):
| {"id": 1, "saldo": 150,00} |
Risultato (dopo la seconda richiesta PATCH):
| {"id": 1, "saldo": 200,00} |
In questo caso PATCH non è idempotente perché richieste ripetute con gli stessi dati producono risultati diversi.
Riepilogo: differenze chiave tra PUT e PATCH nelle API REST
La differenza fondamentale tra PUT e PATCH nell'API REST è il modo in cui gestiscono gli aggiornamenti. PUT sostituisce l'intera risorsa, quindi tutti i campi mancanti vengono cancellati, il che può portare alla perdita di dati. Questo è il motivo per cui gli sviluppatori creano patch per aggiornamenti parziali, per evitare di sovrascrivere i campi non modificati e mantenere l'integrità dei dati.
Ciò rende PATCH più efficiente per gli aggiornamenti parziali. Un esempio di API PATCH è che se desideri aggiornare solo l'e-mail di un utente, la creazione di patch invierebbe solo il campo e-mail, a differenza di una richiesta PUT che richiederebbe tutti i dati dell'utente.
Con PUT è richiesto l'intero payload dei dati. Ciò significa che ogni campo deve essere inviato e tutti i campi mancanti verranno cancellati. PATCH, tuttavia, invia solo i campi che devono essere aggiornati, rendendolo più efficiente, soprattutto per risorse di grandi dimensioni con modifiche minime. Il metodo PATCH nell'API REST consente richieste più mirate e più piccole, riducendo il trasferimento dei dati.
Sia PUT che PATCH sono idempotenti. Ciò significa che ripetere la stessa richiesta porterà allo stesso risultato. Tuttavia, PUT è più prevedibile poiché sostituisce l'intera risorsa. PATCH, se utilizzato per modificare solo i campi specificati, potrebbe portare a risultati diversi a seconda di come gli aggiornamenti vengono gestiti dal server.
Ad esempio, se una PATCH incrementa un contatore, richieste ripetute potrebbero portare a risultati diversi. Tuttavia, anche le operazioni API PATCH possono essere progettate per essere idempotenti.
In conclusione, la differenza PUT e PATCH nell'API REST si riduce alla natura degli aggiornamenti: PATCH è per modifiche parziali, mentre PUT è per la sostituzione completa delle risorse. Entrambi sono idempotenti, ma PATCH può essere più complesso.
Considerazioni finali
Sia PUT che PATCH sono metodi HTTP fondamentali nella progettazione dell'API REST, ma hanno scopi diversi, che è l'essenza della differenza PUT e PATCH nell'API REST. Puoi migliorare in modo significativo l'efficienza, la chiarezza e la funzionalità della tua API comprendendo la differenza tra PUT e PATCH con gli esempi trattati in precedenza in questo articolo. Scegliendo il metodo corretto (PATCH o aggiornamento REST) in base al tuo caso d'uso, puoi rendere la tua API più efficiente, gestibile e facile da usare. Considera sempre la natura dell'aggiornamento, totale o parziale, insieme all'impatto sulle prestazioni e sull'integrità dei dati, e seleziona il metodo che meglio si adatta alle tue esigenze.
