I software applicativi hanno reso le nostre vite più semplici e migliori in molti modi. Ne abbiamo bisogno quasi ogni giorno, e alcune persone si trovano a utilizzare applicazioni più frequentemente di quanto interagiscono con le altre persone.

Ma come interagiscono le applicazioni le une con le altre? Beh, lo fanno tramite API – Application Programming Interfaces. In questo articolo, imparerete cosa sono le API. Concentreremo specificamente sull’interfaccia web e sulla sua progettazione e sviluppo.

Cos’è un’API web?

Le API web sono un tipo di API progettato per essere utilizzato sul web. In altre parole, le applicazioni software basate su web, i sistemi e i servizi utilizzano le API web per scambiare informazione attraverso internet. Inviano richieste e ricevono risposte, di solito in formati come JSON o XML.

Le API web rivestono un ruolo fondamentale nel moderno sviluppo software per i seguenti motivi:

  1. Interoperabilità: Le API sono tecnologia-indipendenti, cioè consentono a sistemi software differenti di comunicare tra loro indipendentemente dalla pila tecnologica. Questo consente ai developers di integrare varie applicazioni in maniera seamless.

  2. Scalabilità: Le API web supportano lo sviluppo modulare, consentendo ai diversi componenti di un’applicazione di essere costruiti, debugati e scalati indipendentemente. Ciò migliora grandemente la scalabilità del sistema.

  3. Flessibilità e Estensibilità: Seguendo pratiche standard e regole ben definite, le Web APIs aiutano le applicazioni nell’estensione della loro funzionalità. Permettono anche di essere abbastanza flessibili da consentire ai sviluppatori la creazione di applicazioni dinamiche.

Approcci alla Developmennto di Web APIs

Le Web APIs possono essere sviluppate utilizzando diversi metodi in base alle necessità. Ecco alcuni approcci comuni seguiti:

  • REST – Representational State Transfer (REST) APIs usano il protocollo HTTP per eseguire operazioni. Operano in maniera stateless, ovvero ogni richiesta deve includere tutte le informazioni necessarie per il ricevente per processare e rispondere.

  • SOAP – Simple Object Access Protocol usa XML per scambiare informazioni in modo strutturato.

  • GraphQL – utilizzato per l’interrogazione e la manipolazione di API.

  • gRPC – un framework per le chiamate di procedura remota che utilizza HTTP/2 per il trasporto delle informazioni.

Nelle prossime sezioni esploreremo la progettazione e lo sviluppo di API, concentrandoci sulle API REST come protocollo centrale della nostra discussione.

Comprendere i requisiti e gli obiettivi

In qualsiasi processo di sviluppo del software, è fondamentale comprendere i requisiti e il caso d’uso previsto prima di iniziare. Questo aiuta a pianificare e stimare i costi, il tempo e le altre risorse necessarie per il progetto.

Lo stesso vale per la creazione di API RESTful. È necessario determinare se le applicazioni scambieranno informazioni in modo stateless, se le entità coinvolte possono essere rappresentate come risorse e se i servizi sono sufficientemente flessibili per lavorare con diversi formati di dati.

Definire le risorse e gli endpoint

Le API REST ruotano attorno alle risorse, che sono entità che rappresentano i dati o gli oggetti del sistema. Ogni risorsa è identificata da un URI unico chiamato identificatore di risorsa. Queste risorse possono essere accedute e manipolate tramite endpoint, che sono URL specifici che ricevono ed elaborano le richieste del client.

Le migliori pratiche suggeriscono di usare nomi per le risorse negli endpoint invece di verbi che potrebbero indicare un’operazione sulla risorsa.

Pensate al seguente esempio: https://api.example.com/products

L’endpoint segue le migliori pratiche dell’uso di un nome di sostantivo per il risorsa (in questo caso, products). Notate come ho usato la forma plurale – products? Ѐ anche consigliabile usare i pluriali se state lavorando con una raccolta di oggetti.

Tuttavia, l’endpoint seguente https://api.example.com/add-product non è raccomandato perché utilizza un verbo e cerca di descrivere un’azione sulla risorsa. Questo approcio può diventare complicato per operazioni più complesse.

Un’altro aspetto importante della convenzione di nomeamento degli endpoint standard è l’uso di una struttura gerarchica. Questo aiuta a rappresentare chiaramente le relazioni tra le risorse.

Per esempio: https://api.example.com/categories/{categoryId}/products/{productId}.
Qui, definiamo un endpoint che mantiene una chiara gerarchia tra le risorse category e product.

Uso dei Metodi HTTP e dei Codici di Stato

Nelle API REST, HTTP viene usato per la comunicazione tra client e server. HTTP ha metodi standard che sono principalmente utilizzati per eseguire operazioni sulle risorse. Ecco di seguito una lista di questi metodi insieme ai loro scopi:

  • GET – Recupera i dettagli della risorsa. Questi dettagli vengono restituiti dal server nel corpo del messaggio di risposta.

  • POST – Crea una nuova risorsa. I dettagli della risorsa da creare vengono inviati nel corpo del messaggio di richiesta.

  • PUT – Crea o aggiorna una risorsa in base alla sua disponibilità. I dettagli della risorsa da creare o aggiornare vengono inviati nel corpo del messaggio di richiesta.

  • DELETE – Rimuove una risorsa.

  • PATCH – Aggiorna parzialmente una risorsa. Le modifiche da apportare alla risorsa vengono inviate nel corpo del messaggio di richiesta.

La procedura raccomandata per lo sviluppo di un API REST ben definito è l’utilizzo corretto di questi metodi HTTP per eseguire le operazioni corrispondenti CRUD (Create, Read, Update, Delete) sulla risorsa. Inoltre, dovresti assicurarti che l’API risponda al client con un codice di stato HTTP appropriato nel corpo del messaggio di risposta.

I codici di stato riflettono il risultato finale di una richiesta. Ecco alcuni degli standard HTTP status code più comuni che puoi utilizzare:

  • 200 OK

  • 201 Created

  • 204 No Content

  • 400 Bad Request

  • Non autorizzato (401 Unauthorized)

  • Proibito (403 Forbidden)

  • Non trovato (404 Not Found)

  • Errore interno del server (500 Internal Server Error)

  • Servizio non disponibile (503 Service Unavailable)

  • Timeout del gateway (504 Gateway Timeout)

Utilizzare un codice di stato HTTP appropriato che rappresenti correttamente il risultato della richiesta che il tuo endpoint API sta processando. Puoi anche implementare codici di stato HTTP personalizzati per descrivere il comportamento specifico dell’applicazione.

Strategie di versionamento

Con il tempo, l’API che hai creato evolve e subirà modifiche. È qui che diventa importante utilizzare strategie di versionamento. Devi assicurarti che i clienti che utilizzano già le tue API non siano influenzati dalle modifiche che intraprendo.

Mantenere differenti versioni renderà le tue API retrocompatibili e permetterà ai clienti di utilizzare la versione preferita dell’API in base alle loro necessità. Un estratto da questo blog informativo sulla pagina web di Postman spiega quando è ideale versionare le tue API:

“Dovreste versionare la vostra API ogni volta che fai un cambiamento che richiederà agli utenti di modificare il loro codice per poter continuare ad usare l’API. Questo tipo di cambiamento è conosciuto come “breaking change” e può essere apportato alle strutture di input e output dell’API, ai feedback di successo e errore e ai meccanismi di sicurezza.“

La versioning dell’API può essere fatto in modi differenti. Ecco alcune metodologie:

  • URI Versioning: Incluse il numero della versione nel percorso dell’URL. Per esempio, https://api.example.com/v1/products.

  • Versioning Parametro di richiesta: Specificare il numero della versione come parametro di richiesta nell’URL. Per esempio, https://api.example.com/products?version=1.

  • Header Versioning: Incluse il numero della versione negli header HTTP della richiesta. Per esempio, usando un header personalizzato come X-API-Version: 1.

  • Negoziazione del contenuto: Specificare la versione negli header Accept della richiesta, spesso utilizzando tipi di media. Ad esempio, Accept: application/vnd.example.v1+json.

  • Versione incorporata: Incorpore il numero di versione all’interno del tipo di media della risposta. Ad esempio, application/vnd.example.product-v1+json.

Considerazioni sulla sicurezza

Un altro aspetto importante da considerare nella creazione di un API è la sicurezza. Ecco alcuni punti chiave da ricordare:

  1. Implementare HTTPS per cifrare le informazioni scambiate tra il client e il server.

  2. Implementare l’autenticazione e l’autorizzazione per assicurarsi che solo gli utenti con i privilegi corretti possano eseguire operazioni sulle risorse. Metodi comuni includono l’autenticazione Basic, l’autenticazione tramite Bearer o Token, JWT e OAuth 2.0. Inoltre, implementare il controllo dell’accesso basato su ruoli per gestire l’accesso alle risorse.

  3. Implementare la validazione e la sanificazione dell’input per prevenire gli attacchi di vulnerabilità come l’iniezione SQL e l’XSS (Cross-Site Scripting).

  4. Implementare il limitazione e la rappresentazione delle richieste per controllare il numero di richieste che un client può fare al server in un determinato intervallo di tempo. Questo aiuta a prevenire un carico eccessivo sul server.

Documentazione

Un aspetto chiave ma spesso trascurato dell’ Sviluppo API è la documentazione. È fondamentale documentare la tua API in modo da permettere agli utenti di comprendere le sue funzionalità e le sue caratteristiche.

La documentazione deve essere completa, facile da capire e seguire le pratiche standard. Includere esempi di corpo della richiesta e della risposta, codici di stato HTTP utilizzati e altro. Puoi seguire la specifica Open API per descrivere le tue API RESTful.

Strategie di ordinamento, filtraggio e paginazione.

L’API che sviluppi potrebbe causare problemi di prestazioni se restituisce troppe righe. E’ inefficiente recuperare grandi quantità di dati e poi ordinare o filtrare.

Per risolvere questo, dovresti abilitare l’ordinamento e la filtratura delle righe. Inoltre, dovresti implementare la paginazione per scomporre il numero di righe da recuperare e impostare un limite per una navigazione e un processamento più semplici.

Monitoraggio dell’Uso, Logging e Verifiche di Stato

E’ una buona idea loggare le richieste e le risposte dell’API per aiutare nell’debug. Il monitoraggio dell’uso dell’API ti aiuterà a capire il comportamento e le prestazioni generali dell’applicazione. Eseguire verifiche di stato regolari può aiutarti a prendere le dovute azioni in caso di problemi. Tutti questi passaggi renderanno l’API più robusta e affidabile.

Conclusione

Le API, in particolare le Web API, sono essenziali per le applicazioni software che comunicano via internet.

In questo articolo è stato spiegato cosa sono le Web API, perché sono importanti, e differenti approcchi per lo sviluppo di esse, focalizzandosi sulle REST API. Hai anche imparato argomenti chiave come la definizione delle risorse e degli endpoint, l’uso di metodi HTTP standard e di codici di stato, strategie di versionamento, considerazioni di sicurezza, documentazione e altro.

Se hai trovato questo articolo interessante, non ti preoccupare di controllare i miei altri articoli su freeCodeCamp e contattarmi su LinkedIn.