Che cos'è la progettazione API?

La progettazione API include decisioni sugli endpoint delle API, sui formati di richiesta e risposta, sui protocolli e sul modo in cui le API comunicano con altre applicazioni e consumatori. La progettazione delle API gioca un ruolo importante anche nella governance delle API.

Per governance delle API si intende l'insieme di criteri, politiche e pratiche che informano il modo in cui un'organizzazione sviluppa, distribuisce e utilizza le proprie API. Una progettazione efficace delle API produce API che aderiscono a queste politiche predeterminate, con una documentazione solida e aggiornata che spiega come funziona l'API. Il risultato sono API ben progettate che hanno una migliore riusabilità, scalabilità, compatibilità e offrono una migliore esperienza utente per gli utenti finali.

Esistono molti casi d'uso delle API e numerosi approcci alla progettazione delle API, con alcuni protocolli, stili di architettura e linguaggi più adatti per attività o casi d'uso specifici rispetto ad altri.

L'aumento dell'uso delle API web ha portato allo sviluppo e all'uso di determinati protocolli, stili, standard e linguaggi. Queste strutture forniscono agli utenti una serie di parametri, o specifiche API, che definiscono le tipologie accettate di dati, comandi, sintassi e altro. In effetti, questi protocolli API facilitano lo scambio standardizzato di informazioni.

I protocolli, gli stili architettonici e i linguaggi comuni includono:

• SOAP (simple object access protocol)
• Chiamata di procedura remota (RPC)
• WebSocket
• REST (representational state transfer)
• GraphQL

La scelta della struttura corretta per una nuova API è un aspetto importante del processo di progettazione. Questi protocolli, stili architettonici e linguaggi non sono necessariamente migliori o peggiori l'uno dell'altro. Sono strumenti diversi per compiti diversi.

SOAP è una specifica di protocollo di messaggistica leggera basata su XML che consente agli endpoint di inviare e ricevere dati attraverso una serie di protocolli di comunicazione tra cui SMTP (simple mail transfer protocol) e HTTP (hypertext transfer protocol). SOAP è indipendente, il che consente alle API SOAP di condividere informazioni tra app o componenti software eseguiti in ambienti diversi o scritti in linguaggi diversi.

Rispetto ad altri tipi di API, le API SOAP tendono a essere sviluppate in modo più formalizzato e strutturato. Le API SOAP sono in circolazione dagli anni '90; è un formato più vecchio e consolidato, ma anche più lento di architetture più moderne come REST. 

SOAP funziona codificando i dati in formato XML e non supporta il trasferimento di dati in altri formati. D'altra parte, le API SOAP non richiedono necessariamente HTTP per il trasporto dei messaggi, il che offre loro una maggiore flessibilità nello spostamento dei dati. SOAP è considerato più sicuro di altri protocolli, il che rende le API SOAP appropriate nei sistemi che gestiscono dati sensibili.

La chiamata di procedura remota (RPC) è un protocollo che fornisce il paradigma di comunicazioni di alto livello usato nel sistema operativo. RPC implementa un sistema logico di comunicazione client-to-server progettato appositamente per il supporto delle applicazioni di rete. Il protocollo RPC consente agli utenti di lavorare con procedure remote come se le procedure fossero locali. Questo lo rende adatto a situazioni che richiedono molte interazioni client/server e interazioni client/server.

Le API RPC possono essere ulteriormente suddivise in XML-RPC, JSON-RPC e gRPC. L'XML-RPC è una chiamata di procedura remota che utilizza un formato XML specifico per trasferire i dati. È più vecchia persino delle API SOAP, ma semplice e leggera. JSON-RPC è una chiamata di procedura remota che utilizza JSON (JavaScript Object Notation) per trasferire dati. Poiché JSON usa strutture di dati universali, può essere usato con qualsiasi linguaggio di programmazione. 

gRPC è un framework RPC open-source ad alte prestazioni, sviluppato inizialmente da Google. gRPC usa il protocollo di rete HTTP/2 e il formato dei dati Protocol Buffers ed è comunemente usato per collegare i servizi in un'architettura a microservizi.

Le API WebSocket consentono la comunicazione bidirezionale tra client e server. Questo tipo di API non richiede la creazione di un nuovo collegamento per ogni comunicazione: una volta stabilito il collegamento, consente uno scambio continuo. Ciò rende le API Web Socket ideali per la comunicazione in tempo reale. 

La chat dal vivo, il tracciamento della posizione in tempo reale e la trasmissione dei dati sono tutti casi d'uso eccellenti per le API WebSocket. Le API WebSocket sono utili anche per la sincronizzazione dei dati, ovvero la pratica di mantenere i dati coerenti e aggiornati su più dispositivi o sistemi, perché possono essere aggiornate in tempo reale, senza la necessità di creare una nuova connessione ogni volta che viene apportata una modifica.

REST è un insieme di principi dell'architettura API web. Le API REST., note anche come API RESTful, sono API che rispettano determinati vincoli architettonici REST. Le API REST usano richieste HTTP come GET, PUT, HEAD e DELETE per interagire con le risorse. REST rende i dati disponibili come risorse, con ciascuna risorsa rappresentata da un URI univoco. I client richiedono una risorsa fornendo il relativo URI. Le API REST sono stateless: non salvano i dati dei client tra una richiesta e l'altra.

Le API RESTful sono popolari perché sono leggere, flessibili e facili da usare. Supportano completamente il trasporto dei messaggi in diversi formati, ad esempio testo normale, HTML, YAML, XML e JSON, e supportano anche la memorizzazione nella cache. Sebbene ciò le renda utili in una grande varietà di contesti, alcune stazioni richiedono un linguaggio o un protocollo più specifico per completare in modo efficiente un'attività.

GraphQL è un linguaggio di query e un runtime API che Meta ha sviluppato internamente nel 2012 prima di diventare open source nel 2015. GraphQL consente agli utenti di effettuare richieste API con poche righe, anziché dover accedere a endpoint complessi con molti parametri. Questa funzionalità può semplificare la generazione e la risposta alle query API, in particolare alle richieste più complesse o specifiche destinate a più risorse.

Dato che Meta ha sviluppato questo linguaggio di query per rendere più efficienti le proprie applicazioni mobili, è logico che le API GraphQL siano utili per le applicazioni mobili. Offrendo un unico punto di ingresso, le API GraphQL possono ridurre i tempi di caricamento eseguendo query sui dati senza dover effettuare più richieste al server. 

Ci sono quattro fasi chiave del processo di progettazione di un'API:

• Pianifica
• Sviluppo
• Prova
• Implementa

Tutti questi passaggi richiedono la collaborazione tra il principali stakeholder delle API. Sebbene alcuni passaggi siano più adatti ad alcuni stakeholder rispetto ad altri, la progettazione delle API dovrebbe comunque essere collaborativa durante tutto il processo. Questo aiuta gli sviluppatori a non aggiungere funzioni extra di cui il programma non ha bisogno, accelerando il processo di sviluppo nel suo complesso.

Il primo passo di ogni progetto è coinvolgere tutti sul tipo di nuova API che si sta creando. Un'API rivolta al pubblico pensata per permettere ai clienti di interfacciarsi in un contesto di e-commerce ha esigenze di design e funzionalità diverse rispetto a una destinata all'uso interno per un workflow di autenticazione; è importante che tutti gli stakeholder comprendano il caso d'uso di una potenziale API prima dell'inizio dello sviluppo.

Capire cosa sta costruendo un'azienda (e perché) può dare agli sviluppatori un'idea migliore di come costruirlo, compresi i protocolli da utilizzare. Se, ad esempio, questa potenziale API richiede la comunicazione in tempo reale, gli sviluppatori sanno che potrebbero utilizzare WebSocket durante la creazione perché quel protocollo è adatto a tale scopo. 

Una volta che gli stakeholder hanno una visione chiara di cosa sarà l'API e di come funzionerà, è il momento di iniziare a costruirla. Durante il processo di sviluppo dell'API, gli sviluppatori definiscono gli endpoint; progettano il modello di dati per l'API; si assicurano che l'API aderisca alle politiche di sicurezza API e restituisca codici di stato standard per gli errori; se necessario, implementano meccanismi di autenticazione come intestazioni HTTP, chiavi API, OAuth o token; definiscono i codici di errore, i messaggi e le risposte.

Un'altra parte del processo di sviluppo è la documentazione. Durante la creazione dell'API, tutte le scelte effettuate devono essere riportate in un documento leggibile dall'uomo e dalle macchine. Un documento leggibile dall'uomo è scritto in un linguaggio naturale e facile da capire. Un documento leggibile dalle macchine dovrebbe aderire a una specifica API, come la specifica OpenAPI, che standardizza il formato in modo che sia coerente e in grado di essere integrato nei sistemi futuri.

La progettazione delle API può essere un processo altamente iterativo; soprattutto se le API espongono dati sensibili, è importante testarle rigorosamente per individuare bug e difetti. Dopo aver costruito qualcosa, è importante vedere se funziona come previsto. Una parte importante del test delle API è il mocking, che è il processo di creazione di server fittizi con dati di esempio per verificare se l'API comunica correttamente con i suoi endpoint e restituisce i risultati previsti. 

Il mocking può essere condotto insieme ai test delle API. I test delle API includono i test dei contratti, che stabiliscono l'aspetto di una richiesta e una risposta; i test unitari, che confermano che un singolo endpoint fornisce la risposta prevista; il test di carico, che verifica se l'API è in grado di funzionare in condizioni di picco di traffico e i test end-to-end, che convalidano i percorsi degli utenti che implicano la comunicazione con più di un'API. I test possono essere eseguiti manualmente o implementando framework di test automatizzati.

Se tutto funziona come previsto, l'API è pronta per essere rilasciata e implementata. A questo punto, è importante che la documentazione dell'API sia finalizzata in modo che altri utenti e le loro macchine possano integrare correttamente questa API nel loro ambiente di rete di computer. È possibile che, una volta rilasciata l'API, gli utenti trovino problemi che gli stakeholder non avevano previsto. È utile disporre di una strategia di controllo delle versioni prima del rilascio dell'API in modo che, se gli sviluppatori devono aggiornare l'applicazione, lo facciano in modo chiaro e coerente.

Un approccio allo sviluppo applicativo dà priorità alla progettazione delle API all'inizio del processo di sviluppo software e costruisce applicazioni con servizi che saranno forniti tramite API. L'idea è che, dando priorità alla progettazione delle API nelle prime fasi dello sviluppo del software, le API risultanti siano più riutilizzabili, sicure, efficienti, più facili da usare e meglio allineate agli obiettivi dell'organizzazione. Questo approccio è contrario a un approccio basato sul codice, che mette al primo posto la logica del codice, con gli sviluppatori che creano API da adattare al software in un secondo momento. 

La progettazione delle API è fondamentale in un approccio con priorità API. In questo approccio, le API sono fondamentali per lo sviluppo di applicazioni e un design ben ponderato promuove lo sviluppo di applicazioni più performanti e di maggior valore. 

Solide pratiche di progettazione delle API possono anche aiutare a migliorare sia l'esperienza degli sviluppatori che l'esperienza dell'utente finale scoprendo e risolvendo gli ostacoli nello sviluppo e nelle prestazioni prima che si trasformino in problemi più grandi.

Gli stakeholder possono stabilire fin dall'inizio del processo di sviluppo che tutte le app dell'azienda si integrino e funzionino bene tra loro. Se implementato con successo, un approccio con priorità API con documentazione completa consente agli sviluppatori di riutilizzare le API esistenti anziché ricreare funzioni già esistenti.

Le API REST (o RESTful) hanno una struttura libera. L'unico requisito è che si allineino ai seguenti sei principi di progettazione REST, noti anche come vincoli architettonici: interfaccia uniforme, disaccoppiamento client/server, statelessness, cacheability, architettura di sistema a più livelli e, opzionalmente, codice su richiesta. 

Questi vincoli architetturali rendono le API RESTful adatte a un approccio API-first: il disaccoppiamento client/server e l'assenza di stato sono particolarmente utili. 

In un'API RESTful, le applicazioni client e server devono essere indipendenti l'una dall'altra. L'unica informazione che l'applicazione del client deve conoscere è l'Uniform Resource Identifier (URI) della risorsa richiesta; non può interagire con l'applicazione in nessun altro modo. 

Le API REST sono stateless, il che significa che ogni richiesta deve includere tutte le informazioni necessarie per l'elaborazione. In altre parole, le API REST non richiedono sessioni lato server. Questi vincoli rendono queste API indipendenti dai server aziendali, rendendole flessibili: le applicazioni lato client e server possono essere scritte con linguaggi e protocolli diversi senza influire sulla progettazione delle API.

Le API RESTful sono adatte anche per un ambiente API-first perché sono scalabili e leggere. La separazione tra client e server migliora la scalabilità perché le API RESTful non devono conservare le informazioni passate sulle richieste dei client, riducendo i colli di bottiglia nelle comunicazioni. Un caching efficace può anche ridurre le interazioni client/server, un altro vantaggio in termini di scalabilità. Poiché le API RESTful utilizzano il formato HTTP per il trasporto dei messaggi, possono accettare il trasferimento dei dati in più formati. Ciò può semplificare l'integrazione in nuovi ambienti.

Un'architettura di microservizi è uno stile architetturale cloud-native in cui una singola applicazione è composta da molti componenti più piccoli, liberamente accoppiati e implementabili indipendentemente. Le API REST vengono spesso utilizzate per abilitare la comunicazione tra questi servizi più piccoli.

Un approccio con priorità API si integra bene con lo schema dell'architettura dei microservizi perché le API vengono usate per connettere i servizi tra loro. Se la progettazione delle API è una priorità all'interno di un'organizzazione e le API sono progettate per comunicare senza problemi tra loro, gli sviluppatori risparmiano tempo raggruppando questi servizi in applicazioni più grandi. 

Per ottenere il massimo valore dalle API aziendali, le organizzazioni spesso sottolineano:

• Governance e documentazione delle API
• Raccolta del feedback degli stakeholder
• Autenticazione corretta
• Controllo delle versioni
• Standardizzazione dei messaggi di errore
• Scala e contesto
• Consistenza

Questi principi aiutano a tenere informate tutti gli stakeholder durante tutto il processo di progettazione delle API e ad assicurare che le API siano in linea con gli obiettivi e la strategia dell'organizzazione.  

Governance e documentazione delle API: stabilire precocemente una strategia di governance e documentazione delle API a livello di organizzazione aiuta a promuovere la coerenza e a rendere il portfolio di API più facile da navigare. Ad esempio, un'organizzazione potrebbe scegliere di adottare una specifica come OpenAPI in modo che tutte le API aziendali aderiscano a uno standard di settore. In ogni caso, mantenere una governance e una documentazione adeguate e coerenti consente ai nuovi utenti dell'API di acquisire una rapida comprensione dell'API e delle sue funzioni. 

Raccolta del feedback degli stakeholder: l'input precoce dei principali stakeholder e dei consumatori di API aiuta a mantenere gli sviluppatori sulla strada giusta durante tutto il processo di sviluppo. Una comunicazione scadente può comportare ritardi nello sviluppo e conseguire API di minor valore.

Autenticazione e sicurezza API adeguate: per proteggere le API e i dati sensibili, le organizzazioni implementano tecniche di autenticazione che forniscono la convalida delle richieste API. Meccanismi di autenticazione come chiavi API, OAuth e token Web JSON (JWT) forniscono diversi metodi per proteggere i dati e il traffico API. La crittografia API, il processo di codifica dei dati per gli spostamenti tra client e server, viene utilizzata anche per proteggere dati e API.

Test e versioning: il test delle API include la copertura di vari scenari, positivi e negativi, per identificare i problemi prima che un'API venga distribuita. Le API si evolvono nel corso di questi test e gli sviluppatori creano nuove versioni che migliorano le prestazioni. Le nuove versioni dell'API vengono rilasciate anche per altri motivi, ad esempio quando gli sviluppatori aggiungono nuove caratteristiche a un'API. Il controllo delle versioni è il modo in cui gli sviluppatori gestiscono le modifiche a un'API, rendono trasparenti le modifiche e si assicurano che gli aggiornamenti non disturbino gli utenti attuali.

È utile disporre di meccanismi di versioning, come il versioning basato sugli URL o il versioning basato sulle intestazioni, definiti prima che lo sviluppo inizi seriamente.

Standardizzazione dei messaggi di errore: una corretta gestione degli errori migliora l'esperienza di un utente di API perché aiuta a risolvere i problemi quando le cose vanno male. I codici di errore, i messaggi e le risposte devono descrivere accuratamente la natura dell'errore e rimanere chiari e coerenti.

Contesto e vincoli: ogni API esiste in un contesto specifico che determina come verrà creata e quali sono le sue funzioni. Le scadenze dei progetti concorrenti, i volumi di traffico previsti e il fatto che l'azienda dia priorità alle API o al codice possono modellare l'API risultante. È importante che tutti gli stakeholder siano a conoscenza di queste informazioni in modo da poter prendere decisioni informate durante il processo di sviluppo.

Coerenza: soprattutto, mantenere una certa coerenza porta in genere a un migliore design dell'API. La coerenza nel design delle API va oltre il semplice versioning e i codici di errore. Quando si definiscono gli endpoint, mantenere coerenti le convenzioni di denominazione può facilitarne l'identificazione. Quando si effettua una richiesta specifica a un'API, questa deve essere risolta ogni volta allo stesso modo. Quando tutto è coerente in un landscape di API, è anche più facile documentare le API in modo che siano comprensibili per gli utenti futuri.