Comprendere le operazioni Swagger: una guida alle interazioni API RESTful
Man mano che N-able aggiunge più operazioni alla sua API, Paul Kelly esamina come Swagger può aiutarti.
In questo articolo spiega i sette diversi tipi di Swagger, cosa fanno e come potresti usarli.
Fornendo una documentazione API chiara e interattiva, Swagger migliora il processo di sviluppo complessivo, aumenta la collaborazione e riduce la complessità per gli sviluppatori che lavorano con le API.
È così ampiamente adottato che ogni API che ho esaminato di recente lo sta utilizzando, da N-central a FortiGate a DNS Filter.
Ciò che ho notato in particolare in N-central è che man mano che aggiungiamo sempre più operazioni alla nostra API, vediamo sempre più tipi di operazioni Swagger utilizzate.
L’operazione in particolare che ha innescato l’idea per questo blog è stata l’aggiunta di un’operazione Patch per Lifecycle-info.
Stavo pensando tra me e me, cosa c’entra Patch con le informazioni sulla garanzia? Poi ho capito che era un termine utilizzato da Swagger.
In questo blog spiegherò i sette diversi tipi di operazioni che vedrai in Swagger, a cosa servono e come potresti usarli.
Innanzitutto, un po’ di contesto: Swagger organizza le operazioni API tramite metodi HTTP: GET, POST, PUT, DELETE, PATCH, OPTIONS e HEAD.
Ognuna di queste operazioni ha uno scopo specifico quando si interagisce con le risorse in un servizio Web. Diamo un’occhiata più da vicino a cosa fanno questi metodi e quando usarli.
1. GET: Recupero dati
Il metodo GET è l’operazione più comune in qualsiasi API. Viene utilizzato per recuperare dati da un server senza alterare nulla sul lato server.
- A cosa serve: l’operazione GET recupera informazioni, ad esempio recuperando un elenco di dispositivi o i dettagli di una risorsa specifica.
- Esempio di utilizzo: Immagina di sfogliare un catalogo di prodotti. Stai visualizzando le informazioni ma non stai ancora modificando o acquistando nulla.
2. POST: Creazione di nuove risorse
Il metodo POST viene utilizzato quando è necessario inviare dati al server per creare una nuova risorsa .
- A cosa serve: con una richiesta POST aggiungi qualcosa di nuovo al sistema, che si tratti di un nuovo utente, un nuovo cliente o una nuova finestra di manutenzione.
- Esempio di utilizzo: è come compilare e inviare un modulo per creare un account su un sito web.
3. PUT: Aggiornamento di un'intera risorsa
Quando è necessario aggiornare completamente una risorsa esistente , entra in gioco il metodo PUT.
- Cosa fa: PUT sostituisce l’intera risorsa con i nuovi dati forniti nel corpo della richiesta.
- Esempio di utilizzo: immagina di modificare una proprietà personalizzata del dispositivo: questa operazione sovrascriverebbe tutte le informazioni correnti con i nuovi dettagli forniti.
4. PATCH: aggiornamento parziale di una risorsa
A differenza del metodo PUT, che aggiorna l’intera risorsa, il metodo PATCH viene utilizzato per aggiornare solo una parte di una risorsa .
- A cosa serve: PATCH consente di modificare campi specifici senza modificare l’intera risorsa.
- Esempio di utilizzo: supponiamo che tu voglia solo aggiornare la data di scadenza della garanzia di un dispositivo ma lasciare tutto il resto invariato: è qui che entra in gioco PATCH.
5. DELETE: Rimozione di una risorsa
Il metodo DELETE viene utilizzato per rimuovere una risorsa dal server.
- A cosa serve: come suggerisce il nome, DELETE elimina una risorsa specifica.
- Esempio di utilizzo: eliminazione definitiva di un utente dal sistema.
6. OPTIONS: scoperta dei metodi supportati
A volte, prima di interagire con un’API, è necessario sapere quali metodi sono disponibili per un dato endpoint. Ecco dove il metodo OPTIONS torna utile.
- Cosa fa: OPTIONS restituisce i metodi HTTP (come GET, POST, PUT, ecc.) consentiti per una particolare risorsa.
- Esempio di utilizzo: prima di effettuare una richiesta, puoi utilizzare OPTIONS per scoprire quali azioni sono supportate dall’API per un determinato endpoint.
7. HEAD: controllo dei metadati senza il corpo
Il metodo HEAD funziona come GET, ma recupera solo le intestazioni della risposta, senza il contenuto effettivo del corpo.
- A cosa serve: HEAD è utile per verificare se una risorsa esiste o per ottenere metadati come la lunghezza del contenuto, senza dover scaricare i dati completi.
- Esempio di utilizzo: è come controllare se un file è disponibile per il download senza effettivamente scaricarlo.
COMPILA IL FORM PER RICEVE INFORMAZIONI SU N-SIGHT RMM
Articolo:
Understanding Swagger Operations: A Guide to RESTful API Interactions
Autore: Paul Kelly, Head Nerd N-able