Padroneggiare il design delle API: strategie essenziali per sviluppare API ad alte prestazioni

Questo articolo è un prezioso contributo della nostra community ed è stato revisionato da DataCamp per chiarezza e accuratezza.

Ti piacerebbe condividere la tua esperienza? Ci farebbe piacere sentirti! Invia i tuoi articoli o le tue idee tramite il nostro Modulo di Contribuzione della Community.

Le mappe che vedi nelle app di ride-hailing e consegna sono offerte dalle Google Maps API, che gli sviluppatori usano per abilitare questa funzionalità. Google Maps API è l’API predefinita che siti e app utilizzano per mostrare mappe in tempo reale. Se vuoi conoscere il numero preciso, ci sono attualmente 5.567.291 siti web attivi che utilizzano l’API.

Perché Google Maps API ha così tanto successo? Sì, in parte perché è di Google, ma anche grazie al design dell’API, che permette agli sviluppatori di integrarla facilmente nei propri prodotti.

Google Maps API è solo un esempio; ci sono innumerevoli API sul mercato, come PayPal, Stripe, ecc., molto popolari. Anzi, parte del successo di queste aziende può essere attribuito alle loro API.

Qualsiasi sito o applicazione può rendere accessibile la propria funzionalità principale tramite API. Tuttavia, alla fine l’adozione di un’API dipende da quanto è ben progettata. In questo blog esploreremo le basi del design delle API e le best practice da seguire per fare in modo che gli sviluppatori amino la tua API.

Che cos’è il design delle API?

Il design delle API è il processo di definizione dei metodi e dei formati dei dati che le applicazioni possono usare per richiedere e scambiare informazioni. Comporta la specifica degli endpoint o URL che gli sviluppatori possono utilizzare, dei formati dei dati da inviare e ricevere e del comportamento atteso dell’API.

Sebbene questi siano gli aspetti tecnici di un’API, il design è determinato dallo scopo dell’API: il perché alla base. Comprendere lo scopo di un’API elimina gli intoppi del processo di sviluppo perché offre informazioni sul comportamento atteso, sulle limitazioni e sui possibili sviluppi futuri. Oggi il design delle API rientra nel più ampio ombrello della gestione delle API per garantire coerenza tra il design pianificato e l’API implementata.

Se vuoi sviluppare le tue competenze nell’integrazione e gestione delle API, dai un’occhiata al corso di DataCamp Working with the OpenAI API, che ti aiuterà a sviluppare applicazioni basate sull’IA.

Come progettare un’API

Ogni API è diversa in base al suo scopo e alla funzionalità che offre. Tuttavia, esistono alcuni principi guida universali che ogni sviluppatore dovrebbe seguire per creare un’API solida e intuitiva per chi la utilizza. Ecco come procedere:

Passaggio 1: Comprendi lo scopo della tua API

Prima di delineare il progetto della tua API, assicurati che tutti gli stakeholder abbiano chiaro cosa farà l’API. Collabora strettamente con i responsabili di business per chiarire obiettivi e traguardi. Capisci come l’API si inserirà nel quadro generale. Se possibile, parla direttamente con gli utenti finali o con gli sviluppatori che interagiranno con l’API. Raccogli feedback su esigenze, difficoltà e aspettative per ottenere insight sui casi d’uso pratici dell’API.

Lo scopo dell’API determinerà funzionalità, caratteristiche, come verrà documentata, quali implementazioni di sicurezza saranno necessarie e quale specifica per API sceglierai.

Scegli la specifica API giusta

Esistono varie specifiche per API, ognuna adatta a un particolare caso d’uso. Ecco alcune tra le più diffuse:

OpenAPI (Swagger)

OpenAPI è uno standard ampiamente adottato per descrivere API RESTful. È noto per la sua semplicità, perché consente una facile generazione della documentazione e fornisce un modo standardizzato per permettere agli sviluppatori di comprendere e utilizzare l’API. OpenAPI usa un formato JSON o YAML per specificare gli endpoint dell’API, i formati delle richieste e risposte e i metodi di autenticazione. È adatto alla comunicazione stateless su HTTP ed è una buona scelta per API rivolte a un pubblico ampio.

Schema GraphQL

GraphQL è un’alternativa alle API RESTful e le sue specifiche sono spesso definite con un linguaggio di schema. Uno schema GraphQL definisce i tipi di dati specifici che si possono interrogare e la struttura di tali query. È adatto a scenari in cui i client hanno bisogno di un controllo preciso sui dati da recuperare.

Approfondisci la creazione di modelli di machine learning come API usando Flask. Esplora il tutorial completo di DataCamp su API per modelli di Machine Learning in Python.

RAML (RESTful API Modeling Language)

RAML è un linguaggio basato su YAML per descrivere API RESTful. Fornisce un modo leggibile per definire la struttura dell’API, gli endpoint e i tipi di dati. Usalo quando la tua priorità è la leggibilità e la semplicità.

SOAP (Simple Object Access Protocol)

SOAP è un protocollo per lo scambio di informazioni strutturate nei servizi web. È comunemente usato in applicazioni di livello enterprise con necessità di comunicazione standardizzata. È la scelta migliore quando lavori in ambienti legacy.

WSDL (Web Services Description Language)

WSDL è comunemente usato per descrivere i servizi web SOAP (Simple Object Access Protocol). Definisce operazioni, messaggi e tipi di dati per i servizi web, consentendo una comunicazione standardizzata tra sistemi diversi. È ideale per applicazioni enterprise con necessità di contratti rigorosi e comunicazione standardizzata.

AsyncAPI

Simile a OpenAPI ma progettato specificamente per API asincrone, AsyncAPI si focalizza su architetture guidate dai messaggi e descrive come i messaggi vengono scambiati tra i diversi componenti. Si usa quando non è necessaria una risposta in tempo reale da parte di un’API.

Approfondisci lo sviluppo di API con il tutorial di DataCamp su Introduzione a FastAPI. Impara a creare API robuste usando framework moderni.

Passaggio 2: Definisci endpoint e risorse

Il passo successivo è definire endpoint e risorse. Gli endpoint definiscono gli URL (Uniform Resource Locator) o URI (Uniform Resource Identifier) specifici che gli sviluppatori possono usare per interagire con l’API. Ogni endpoint di solito corrisponde a un’operazione o azione specifica. Metodi HTTP comuni come GET, POST, PUT e DELETE vengono utilizzati per eseguire operazioni su questi endpoint. Ecco un esempio:

• GET /users: recupera un elenco di utenti.
• GET /users/{id}: recupera i dettagli di un utente specifico utilizzando l’id utente.
• POST /users: crea un nuovo utente.
• PUT /users/{id}: aggiorna i dettagli di un utente specifico.
• DELETE /users/{id}: elimina un utente specifico.

Le risorse rappresentano le entità o gli oggetti che la tua API gestisce. Possono essere qualsiasi cosa: utenti, prodotti, commenti o qualsiasi altra entità rilevante nel tuo sistema. Ogni risorsa ha in genere un identificatore univoco ed è associata a uno o più endpoint. Ad esempio:

Risorsa: users

Attributi: ID, username, email, ecc.

Endpoint:

/users (GET - elenca tutti gli utenti, POST - crea un nuovo utente),

/users/{id} (GET - recupera i dettagli utente, PUT - aggiorna i dettagli utente, DELETE - elimina un utente)

Risorsa: products

Attributi: ID, name, description, price, ecc.

Endpoint:

/products (GET - elenca tutti i prodotti, POST - crea un nuovo prodotto),

/products/{id} (GET - recupera i dettagli del prodotto, PUT - aggiorna i dettagli del prodotto, DELETE - elimina un prodotto)

Passaggio 3: Definisci le convenzioni di denominazione

Se vuoi che gli sviluppatori amino la tua API, usa convenzioni di denominazione chiare e coerenti. Non essere creativo nella scelta dei nomi per endpoint, risorse e parametri: dai priorità a chiarezza e semplicità. Ecco alcune linee guida utili:

1. Usa sostantivi per le risorse:
• Scegli sostantivi chiari e descrittivi per le risorse. Ad esempio, /users, /products, /orders.
• Evita termini ambigui o generici. Sii specifico per comunicare lo scopo della risorsa.
2. Usa verbi per le azioni:
• Usa i metodi HTTP (GET, POST, PUT, DELETE) per rappresentare le azioni sulle risorse.
• Mantieni coerenti i verbi tra gli endpoint. Ad esempio, usa GET per recuperare utenti e POST per crearne uno nuovo.
3. Sii coerente con il plurale:
• Decidi se i nomi delle risorse devono essere singolari o plurali e sii coerente in tutta l’API. Ad esempio, usa sempre /user oppure /users.

Passaggio 3: Ottimizza i payload di richiesta e risposta

Un altro aspetto cruciale nella progettazione del contratto di un’API è specificare i payload di richiesta e risposta, ovvero i dati inviati nella richiesta e quelli attesi nella risposta. Per prima cosa scegli un formato dati standard per la tua API, come JSON o XML. È preferibile optare per JSON perché è ampiamente usato grazie alla sua semplicità e leggibilità. Puoi imparare a usare JSON nel corso di DataCamp Streamlined Data Ingestion with pandas.

Ricorda di mantenere leggeri i payload, perché influenzano direttamente l’efficienza della tua API. Ecco cosa puoi fare:

1. Cerca di implementare la compressione dei payload (ad es., gzip) per ridurre la dimensione delle richieste durante la trasmissione.

2. Se applicabile, supporta richieste batch in cui più operazioni possono essere raggruppate in un’unica richiesta.

3. Usa parametri di query o di header per progettare endpoint che restituiscano solo i dati richiesti dai client.

Passaggio 4: Implementa autenticazione e autorizzazione

Assicurati di considerare la sicurezza nel design della tua API. Ci sono due aspetti da coprire: autenticazione e autorizzazione.

Per quanto riguarda l’autenticazione, puoi implementare OAuth e API key. La API key è un metodo semplice e comune, in cui una chiave univoca è inclusa nell’header della richiesta. Tuttavia, questo tipo di autenticazione non è sufficientemente sicuro.

OAuth, invece, è un framework più robusto e flessibile, adatto a scenari in cui sono necessarie autorizzazioni per applicazioni di terze parti. Per l’autorizzazione, definisci chiaramente i livelli di accesso e gli scope che utenti o applicazioni possono avere.

Passaggio 5: Adotta il versioning delle API

Le esigenze degli utenti e la tecnologia cambiano spesso nel tempo, per cui anche un’API deve evolvere. Il versioning delle API ti consente di apportare modifiche senza interrompere i sistemi esistenti. Puoi implementare vari tipi di versioning, come versioning nell’URL, nei parametri di query, negli header, ecc.

Ad esempio,

Versioning nell’URL: https://example-api.com/v1/resource

Versioning con parametro di query: https://example-api.com/resource?version=v1.

Passaggio 6: Definisci messaggi di errore appropriati

Gli errori sono inevitabili durante la vita della tua API. Ciò che conta è come gestirli. Includi messaggi di errore chiari e concisi nel body della risposta per aiutare gli sviluppatori a capire cosa è andato storto.

Includi informazioni come codici di errore, descrizioni e suggerimenti per la risoluzione. Usa gli standard degli status code HTTP per indicare il successo o il fallimento di una richiesta (ad es., 200 OK per il successo, 404 Not Found per risorsa non trovata, 500 Internal Server Error per problemi del server).

Passaggio 7: Considera i comportamenti imprevisti

Assicurati anche che la tua API possa gestire comportamenti e richieste impreviste da parte degli utenti finali. Ad esempio, gli utenti possono inviare più richieste alla stessa risorsa, causando problemi di concorrenza.

Dall’altro lato, potrebbero verificarsi problemi anche dalla tua parte, come timeout e risposte lente, oppure il server potrebbe restituire una risposta in un formato non richiesto dal client. La tua API dovrebbe gestire azioni impreviste in modo elegante, con messaggi di errore appropriati.

Passaggio 8: Documentazione

Ora che hai fatto tutto, l’ultima parte è la documentazione. La documentazione è come un manuale che spiega ad altri sviluppatori come funziona la tua API. È uno dei fattori chiave che influiscono sull’adozione e sull’utilizzo della tua API. Assicurati quindi che la documentazione sia chiara, concisa e semplice da capire. Ecco alcune best practice da seguire:

• Evita gergo tecnico superfluo che potrebbe confondere gli sviluppatori.
• Organizza la documentazione in una struttura logica e gerarchica. Usa sezioni, sottosezioni e titoli per aiutare gli utenti a trovare rapidamente le informazioni di cui hanno bisogno.
• Includi esempi interattivi o una sandbox dell’API per consentire agli sviluppatori di sperimentare l’API direttamente dalla documentazione.
• Valuta l’uso di strumenti come Swagger o OpenAPI per generare documentazione interattiva dell’API.

API Design First vs Code First

Quando si tratta di costruire un’API, ci sono due approcci possibili: prima il design dell’API oppure prima il codice.

La strategia che abbiamo appena discusso è l’approccio design first, che prevede la definizione delle specifiche dell’API, inclusi endpoint, formati dei dati, meccanismi di autenticazione e architettura complessiva, prima di scrivere il codice che implementa tali specifiche. L’obiettivo è stabilire un design chiaro e ben ponderato che soddisfi i requisiti del sistema e sia facile da comprendere e usare per gli sviluppatori.

L’approccio code first, invece, si concentra sullo scrivere prima il codice senza definire a priori specifiche o documentazione. Gli sviluppatori adattano quindi l’API in base all’esperienza di implementazione e ai feedback dei test, e il design evolve man mano che si scrive il codice.

Uno dei due approcci è migliore?

Si può dire che l’approccio code first offra flessibilità e velocità di sviluppo, perché consente il rapid prototyping. Tuttavia, comporta anche diverse sfide. Senza una specifica ben definita in anticipo, c’è il rischio di incomprensioni o incoerenze nel modo in cui vengono implementate le varie parti di un’API. In definitiva, dipende dai requisiti del progetto e dalle preferenze del team di sviluppo.

Esplora le possibilità creative delle API con la guida di DataCamp alla DALL-E 3 API per capire come sfruttare l’IA per soluzioni innovative.

Parole finali

Nel design di un’API entrano in gioco vari aspetti tecnici. Tuttavia, dovresti considerare la tua API come un prodotto creato per risolvere i pain point dei tuoi utenti finali. Quando il design dell’API è guidato da quei pain point, è più probabile che venga adottata rapidamente.

Migliora le tue tecniche di ingestion dei dati tramite API con il corso di DataCamp, Streamlined Data Ingestion with pandas. Fai pratica concreta nella gestione efficiente dei dati.