Nel design RESTful API, PUT e PATCH sono due metodi HTTP utilizzati per aggiornare risorse sul server, ma la differenza tra PUT e PATCH in REST API sta nel modo in cui eseguono gli aggiornamenti e negli scenari in cui ciascuno è più appropriato. Entrambi i metodi sono progettati per modificare dati esistenti, ma comprendere la differenza tra PUT e PATCH in REST API aiuta gli sviluppatori a scegliere l'opzione migliore in base alla natura dell'aggiornamento che devono eseguire. In questo post esploreremo la differenza tra PUT e PATCH in REST API, focalizzandoci sul dibattito PATCH vs aggiornamento REST, quando usare ciascuno e forniremo indicazioni per scegliere il metodo giusto per diversi use case.
Cos'è PUT in REST API?
Per capire la differenza tra PUT e PATCH in REST APIs, prima di tutto devi sapere cos'è PUT. Secondo Sezione 9.6 RFC 2616, il metodo PUT in REST API richiede che l'entità fornita sia memorizzata all'URI di richiesta specificato.
Se l'URI di richiesta si riferisce a una risorsa già esistente, l'entità fornita DOVREBBE essere considerata come una versione modificata di quella presente 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 completamente una risorsa sul server. Questo rende PUT un aggiornamento più "completo", spesso utilizzato quando è necessaria una sostituzione totale della risorsa.
PUT è quindi ideale 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.
Nel sistemi come Elasticsearch, le operazioni idempotenti sono necessarie per garantire la coerenza dei dati. Ad esempio, l'aggiornamento di un documento in Elasticsearch tramite PUT assicura che la stessa richiesta possa essere ripetuta senza effetti collaterali indesiderati.
Cos'è PATCH in REST API?
Ora che abbiamo coperto PUT in REST APIs, diamo un'occhiata a cos'è PATCH in REST APIs e come funziona prima di confrontare PUT vs PATCH in REST APIs. Come definito in RFC 5789, il metodo PATCH in REST API richiede che un insieme di modifiche descritte nell'entità della richiesta sia applicato alla risorsa identificata dall'URI di richiesta.
Questo si allinea con la distinzione PUT vs PATCH in REST API, dove invii solo i dati che devono essere modificati e il server applica quelle modifiche alla risorsa esistente senza alterare l'intera risorsa. Gli sviluppatori spesso creano patch per rappresentare questi cambiamenti incrementali, garantendo un trasferimento di dati minimo e aggiornamenti efficienti.
Ecco perché il metodo PATCH in REST API è 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 PATCH API potrebbe consistere nell'invio solo della nuova email, lasciando gli altri campi intatti.
- Miglioramento delle prestazioni riducendo il carico dei dati.
- Quando desideri aggiornare una risorsa in modo incrementale invece di sostituirla completamente.
- Crea patch per incapsulare modifiche a campi specifici, come la modifica dell'email di un utente, senza influire su dati non correlati.
Per piattaforme come CMS headless che spesso gestiscono strutture di contenuti complesse, utilizzare PATCH per aggiornamenti più piccoli, come la modifica di un singolo campo, può ridurre il carico del server e migliorare le prestazioni.
Ora che abbiamo coperto questi due metodi, dovresti avere un'idea abbastanza chiara di cosa siano PUT e PATCH in REST APIs. Tuttavia, prima di addentrarci nella differenza tra PUT e PATCH in REST APIs, dobbiamo parlare dell'idempotenza in questi due metodi.
Idempotenza in PUT vs PATCH in REST API
In REST API, l'idempotenza si riferisce alla proprietà di un'operazione che, ripetuta più volte con gli stessi input, produce sempre lo stesso risultato. Questo significa che effettuare la stessa richiesta più volte deve avere lo stesso effetto sul server, indipendentemente da quante volte viene eseguita. È importante per garantire stabilità e prevedibilità in un API. Ma come si collega alla differenza tra PUT e PATCH in REST API?
Metodo PUT e Idempotenza
Il metodo PUT in REST API è sempre idempotente perché è progettato per sostituire l'intera risorsa a un URI specificato con i dati forniti nella richiesta. In altre parole, se esegui una richiesta PUT più volte con gli stessi dati di risorsa, il risultato sarà sempre identico.
Perché PUT è idempotente? Quando effettui una richiesta PUT, stai essenzialmente dicendo al server: «Questo è lo stato completo e esatto che voglio per questa risorsa». Che tu invii la richiesta PUT una sola volta o molte volte, la risorsa risultante sarà sempre identica.
Ad esempio, considera uno scenario in cui aggiorni l'indirizzo email di un utente. Se effettui la stessa richiesta PUT più volte, il risultato non cambierà perché la risorsa viene sostituita con gli stessi dati ogni volta.
Esempio:
| PUT /users/1{"username": "john_doe","email": "[email protected]"} |
Se invii questa richiesta più volte, il risultato sarà sempre lo stesso:
| {"username": "john_doe","email": "[email protected]"} |
Anche se i dati dell'utente sono già così, inviare di nuovo la richiesta non cambia nulla. Sostituisce i dati con gli stessi dati, quindi l'effetto della richiesta rimane identico indipendentemente da quante volte viene ripetuta. Questo è ciò che rende PUT idempotente.
Metodo PATCH e Idempotenza
Il metodo PATCH in REST API, invece, è generalmente idempotente anch'esso, ma con più flessibilità. Quando crei patch, assicurati che le operazioni siano idempotenti (ad esempio, impostare un valore) per evitare effetti collaterali indesiderati da richieste ripetute. Se PATCH è idempotente dipende dall'operazione e dai dati in corso di modifica.
Perché PATCH è idempotente? Per le richieste PATCH, l'idempotenza significa che applicare la stessa patch più volte avrà lo stesso risultato. Questo è vero finché la patch stessa non causa effetti collaterali o cambiamenti aggiuntivi quando applicata più volte. Se continui ad applicare la stessa patch con gli stessi dati, il risultato non dovrebbe cambiare dopo la prima applicazione.
Ad esempio, se stai aggiornando solo l'email di un utente, inviare ripetutamente la stessa richiesta PATCH non cambierà il risultato dopo la prima volta, anche se la richiesta viene effettuata più volte. L'email dell'utente rimarrà la stessa e lo stato della risorsa non cambierà.
Esempio di PATCH API:
| PATCH /users/1{"email": "[email protected]"} |
Se l'email era già [email protected], applicare di nuovo questa PATCH non produrrà alcun cambiamento, rendendola idempotente.
Tuttavia, PATCH può essere non idempotente in alcuni casi. Ad esempio, se un'operazione PATCH modifica un contatore o aggiunge elementi a una lista (come incrementare un numero o aggiungere a un array), applicazioni ripetute della stessa PATCH potrebbero produrre risultati diversi. Questo violerebbe la proprietà di idempotenza.
Esempio PATCH non idempotente API REST:
| PATCH /counter/1{"increment": 1} |
Se applichi questa PATCH ripetutamente, il contatore continuerà ad aumentare, generando valori diversi ogni volta. Non è idempotente perché il risultato cambia ad ogni applicazione.
Ora che conosci i concetti fondamentali, possiamo esaminare alcuni scenari di esempio per capire meglio la differenza tra PUT e PATCH in REST API.
Scenari di esempio: PUT vs PATCH in REST APIs
Mettendo da parte la teoria, vediamo la differenza tra PUT e PATCH con esempi, includendo operazioni sia idempotenti che non idempotenti.
Scenario 1: Richiesta PUT - Sostituzione di un'intera risorsa
Immagina un endpoint API per gestire i prodotti in un sistema di e-commerce. Devi aggiornare tutti i dettagli di un prodotto, inclusi nome, prezzo e descrizione. Questo è un esempio tipico della differenza HTTP tra PUT e PATCH, dove PUT viene utilizzato per sostituire l'intera risorsa del prodotto.
Prodotto Iniziale
| GET /products/1001{"id": 1001,"name": "Laptop","price": 999.99,"description": "A powerful laptop."} |
Vuoi 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": "A discounted powerful laptop."} |
Se effettui questa richiesta PUT una o più volte, il risultato sarà sempre identico. I dettagli del prodotto verranno aggiornati per riflettere il nuovo prezzo e la nuova descrizione, e lo stesso risultato si ripeterà ogni volta. Questo garantisce la natura idempotente di PUT.
Risultato (dopo la richiesta PUT):
| {"id": 1001,"name": "Laptop","price": 899.99,"description": "A discounted powerful laptop."} |
Scenario 2: richiesta PATCH - Aggiornamento parziale di una risorsa
Consideriamo ora una richiesta PATCH per aggiornare solo parte dei dettagli del prodotto, come la descrizione. Esempio PATCH API: se vuoi modificare solo la descrizione del prodotto senza toccare il prezzo, PATCH è la scelta migliore. Per implementarlo, creeresti patch contenenti solo i campi da modificare, come la descrizione in questo esempio API REST PATCH.
Prodotto Iniziale
| GET /products/1001{"id": 1001,"name": "Laptop","price": 999.99,"description": "A powerful laptop."} |
Richiesta PATCH:
| PATCH /products/1001{"description": "A lightweight, powerful laptop."} |
Quando invii questa richiesta PATCH, verrà aggiornato solo il campo descrizione. Se invii la stessa richiesta PATCH più volte, la descrizione rimarrà invariata dopo il primo aggiornamento, rendendo la richiesta idempotente.
Risultato (dopo la richiesta PATCH):
| {"id": 1001,"name": "Laptop","price": 999.99,"description": "A lightweight, powerful laptop."} |
Se applichi di nuovo lo stesso PATCH, la descrizione del prodotto rimarrà uguale a come era dopo il primo PATCH. Il risultato è coerente, il che rende PATCH idempotente in questo scenario.
Scenario 3: richiesta PATCH - Operazione non idempotente
Osserviamo un'operazione PATCH non idempotente. Supponiamo che esista un endpoint per il saldo del portafoglio di un utente, e tu voglia incrementare il saldo. Una differenza di esempio tra PUT e PATCH può essere illustrata qui: PATCH aggiunge un valore al saldo ogni volta.
Portafoglio Iniziale:
| GET /users/1/wallet{"id": 1,"balance": 100.00} |
Richiesta PATCH:
| PATCH /users/1/wallet{"increment": 50.00} |
Questa richiesta PATCH aumenterà il saldo del portafoglio di 50 dollari. Se invii questa richiesta PATCH più volte, il saldo continuerà ad aumentare con ogni PATCH, producendo un risultato diverso ogni volta. Non è idempotente perché applicare lo stesso PATCH ripetutamente causerà risultati diversi.
Risultato (dopo la prima richiesta PATCH):
| {"id": 1,"balance": 150.00} |
Risultato (dopo la seconda richiesta PATCH):
| {"id": 1,"balance": 200.00} |
Qui, PATCH non è idempotente perché richieste ripetute con gli stessi dati producono risultati diversi.
Riepilogo: Differenze principali tra PUT e PATCH in REST APIs
La differenza chiave tra PUT e PATCH in REST API sta in come gestiscono gli aggiornamenti. PUT sostituisce l'intera risorsa, quindi i campi mancanti vengono cancellati, il che può causare perdita di dati. Ecco perché gli sviluppatori creano patch per gli aggiornamenti parziali: per evitare di sovrascrivere campi invariati e mantenere l'integrità dei dati.
Questo rende PATCH più efficiente per gli aggiornamenti parziali. Un esempio PATCH API è che se vuoi aggiornare solo l'email di un utente, creando patch invieresti solo il campo email, a differenza di una richiesta PUT che richiederebbe i dati completi dell'utente.
Con PUT, il payload completo è obbligatorio. Significa che ogni campo deve essere inviato, e qualsiasi campo mancante sarà cancellato. PATCH, invece, invia solo i campi che devono essere aggiornati, rendendolo più efficiente, soprattutto per risorse grandi con modifiche minime. Il metodo PATCH in REST API consente richieste più mirate e ridotte, riducendo il trasferimento dati.
Sia PUT che PATCH sono idempotenti. Significa che ripetere la stessa richiesta produrrà lo stesso risultato. Tuttavia, PUT è più prevedibile poiché sostituisce l'intera risorsa. PATCH, quando usato per modificare solo campi specifici, potrebbe produrre risultati diversi a seconda di come il server gestisce gli aggiornamenti.
Per esempio, se un PATCH incrementa un contatore, richieste ripetute potrebbero portare a risultati diversi. Tuttavia, le operazioni PATCH API possono essere progettate per essere idempotenti.
In conclusione, la differenza tra PUT e PATCH in REST API si riduce alla natura degli aggiornamenti: PATCH è per modifiche parziali, mentre PUT è per la sostituzione completa della risorsa. Entrambi sono idempotenti, ma PATCH può essere più complesso.
Considerazioni Finali
Sia PUT che PATCH sono metodi fondamentali HTTP nella progettazione REST API, ma servono scopi diversi, che è l'essenza della differenza tra PUT e PATCH in REST API. Puoi migliorare significativamente l'efficienza, la chiarezza e la funzionalità del tuo API comprendendo la differenza tra PUT e PATCH con gli esempi che abbiamo trattato in precedenza in questo articolo. Scegliendo il metodo corretto (PATCH vs aggiornamento REST) in base al tuo caso d'uso, puoi rendere il tuo API più efficiente, manutenibile e user-friendly. Considera sempre la natura dell'aggiornamento, se completo o parziale, insieme all'impatto su prestazioni e integrità dei dati, e seleziona il metodo più allineato alle tue esigenze.
