Cos'è il ciclo di vita delle API?

Le API sono insiemi di regole o protocolli che consentono alle applicazioni software di comunicare tra loro per scambiare dati, caratteristiche e funzionalità. Esiste sia un ciclo di vita del produttore di API, incentrato sulla creazione e la distribuzione delle API, sia un ciclo di vita del consumatore delle API, incentrato sull'uso delle API dal punto di vista del consumatore. Questo articolo si concentra sul ciclo di vita del produttore di API.

Non esiste un ciclo di vita universale dei produttori di API. Potresti notare variazioni diverse da fonti diverse, ma il ciclo di vita generalmente include le seguenti fasi: pianificazione, progettazione, sviluppo, test, distribuzione, monitoraggio e ritiro.

Le Api management platform sono spesso utilizzate per aiutare a organizzare gli sforzi lungo tutto il ciclo di vita dell'API e per centralizzare la strategia, la governance, la documentazione e le directory API in un ambiente IT. Molte piattaforme includono funzionalità di analytics avanzate e strumenti per la scoperta e la monetizzazione delle API che aiutano le organizzazioni a ottenere il massimo dalle loro API.

Una considerazione e comprensione dell'intero ciclo di vita delle API aiuta i team di sviluppo a allocare le risorse in modo più efficiente, creare tempistiche realistiche per la consegna, tenere tutti gli stakeholder informati durante tutto il processo e garantire che le API soddisfino i requisiti aziendali. In sostanza, un ciclo di vita ben pensato ed eseguito aiuta a offrire API sicure e ad alte prestazioni e un'esperienza utente più forte.

La gestione end-to-end del ciclo di vita delle API comprende diverse fasi chiave, che iniziano con la pianificazione preliminare e terminano, spesso, ma non sempre, con il ritiro o la sostituzione. Ad esempio, consideriamo un'azienda di software che decide di costruire un'API per sincronizzare i dati dei clienti con strumenti aziendali come ticketing di supporto, sistemi contabili, piattaforme di gestione progetti e altro ancora.

La costruzione di un'API inizia con la risposta ad alcune domande fondamentali: perché questa API è necessaria, a chi è destinata, come verrà utilizzata e come verrà misurato il successo? 

La specificità sull'obiettivo del progetto API può aiutare a chiarire quali funzionalità e caratteristiche il design dell'API deve avere. Nell'esempio dello sviluppo software, l'obiettivo dell'API è quello di garantire che i dati dei clienti possano spostarsi senza problemi tra le applicazioni e le piattaforme che l'azienda utilizza o intende utilizzare. 

In questa fase di pianificazione, le organizzazioni:

• Esaminano i potenziali benefici aziendali dell'API
• Descrivono come questa API risponderà alle esigenze aziendali
• Si assicurano che non ci siano API esistenti o altri prodotti disponibili nei marketplace di integrazione nativi che potrebbero fare ciò che è richiesto (essenzialmente, confermando che la creazione di questa API è necessaria)
• Definiscono chiaramente quali applicazioni e piattaforme si affideranno all'API e come l'API si integrerà con i workflow esistenti.

Successivamente, il team dovrebbe discutere i potenziali utenti e i casi d'uso. È solo per uso interno? Quali team utilizzeranno questa API e per cosa? Ci sono preoccupazioni di sicurezza che dovrebbero essere affrontate nelle fasi di progettazione e sviluppo? E soprattutto, chi sarà responsabile di ogni fase della produzione dell'API?

Stabilire una tempistica per il completamento del progetto aiuta a garantire che il progetto rimanga entro il budget. È importante che le tempistiche siano realistiche e flessibili. 

I team risponderanno a domande come: ci sono date specifiche, come una data di lancio di una nuova caratteristiche, che devono essere rispettate? Esistono team di sicurezza, di conformità legale o altri stakeholder che devono dare il loro benestare prima che questa API possa essere distribuita? 

Dove saranno archiviate e rese disponibili sia a sviluppatori che a utenti documentazione e altre informazioni sull'API? Dove verranno tracciate e memorizzate le modifiche al codice?

Rispondere a queste domande fin dall'inizio aiuta a stabilire un piano chiaro per il resto del ciclo di vita.

Mentre la fase di pianificazione descrive il risultato desiderato, la fase di progettazione definisce come il team intende raggiungerlo. Durante tutto il processo di progettazione, il team di progettazione dell'API decide come l'API deve essere costruita per soddisfare i requisiti dettagliati nella fase di pianificazione. 

Il team deve prendere decisioni progettuali riguardanti il protocollo e lo stile architettonico che l'API utilizzerà. Questa decisione potrebbe basarsi sull'architettura API esistente dell'organizzazione o sui casi d'uso previsti per questa nuova API.

Ad esempio, i framework e le architetture API più comuni includono REST, GraphQL e gRPC; ognuno ha i propri punti di forza e debolezze. 

• REST: semplice, intuitivo e onnipresente, ma non ideale per query complesse e non offre una tipizzazione forte.
  
  
• GraphQL: efficiente, con una tipizzazione efficace e documentazione integrata. Ma GraphQL può anche essere complesso e richiedere più configurazione e competenze specifiche rispetto a REST.
  
  
• gRPC: veloce, con digitazione forte, generazione automatica di codice e streaming bidirezionale. gRPC è spesso utilizzato per la comunicazione con microservizi. Ma essendo un framework più recente, può esserci una curva di apprendimento, e il suo formato di documentazione è binario piuttosto che leggibile dall'uomo. 

Nel progettare l'API, il team deciderà anche quale tipo di autenticazione sia appropriata (come OAuth 2.0) e se l'API debba essere posizionata dietro un API gateway.

Un documento di specifica descrive la struttura, il comportamento e la funzionalità di un'API in modo standardizzato. Fornisce una singola fonte affidabile con informazioni su come è costruita l'API, cosa può fare e come interagire con essa. 

La specifica standardizzata più diffusa è la specifica OpenAPI, che consente agli sviluppatori di definire percorsi, metodi, parametri, metodi di autenticazione e altro ancora. OpenAPI è utilizzato specificamente per le API REST e supporta un set di strumenti open-source chiamato Swagger, che offre la generazione di codice, la modifica e la creazione automatica di documentazione.

Per GraphQL, la specifica equivalente è lo schema GraphQL, un contratto fortemente tipizzato scritto in linguaggio di definizione di schema, o SDL, un formato leggibile dall'uomo. L'ecosistema GraphQL offre alcuni strumenti diversi che sfruttano questo schema in modi simili a quelli di OpenAPI; ad esempio, GraphiQL è un ecosistema di sviluppo integrato (IDE) interno al browser per gli sviluppatori da utilizzare come sandbox. 

Per gRPC, Protocol Buffers, o protobuf, è un formato di serializzazione e un linguaggio di definizione dell'interfaccia (IDL) che funge da formato di file più comunemente usato per le specifiche. Protobuf non offre test interattivi, anche se esistono interfacce web che lo permettono. 

In questa fase, gli sviluppatori iniziano la codifica, seguendo il piano di progettazione delle API delineato nel passaggio precedente. Un sistema di controllo delle versioni viene utilizzato per tenere traccia delle versioni e delle modifiche al codice durante tutto il processo di sviluppo.

Lo standard di settore per i sistemi di controllo delle versioni è Git, un software open source che tiene traccia delle modifiche al codice memorizzate localmente sul dispositivo di uno sviluppatore. Gli sviluppatori usano Git per creare, gestire e tenere traccia delle modifiche al loro codice, ma poi hanno bisogno di un posto dove questo codice sia accessibile a loro stessi e agli altri. 

GitHub è il servizio di hosting Git più popolare, che offre piani sia gratuiti che a pagamento, consentendo lo storage, il recupero e la collaborazione su repository di codice Git. Esistono alternative per ospitare repository Git, tra cui GitLab, AWS CodeCommit e Microsoft Azure Repos.

I test API vengono condotti sia durante che dopo la fase di sviluppo API; i test continui aiutano lo sviluppo rivelando vulnerabilità e bisogni, e abilitando aggiornamenti regolari. 

Il test unitario consiste nell'isolare piccole parti del codice e testarle singolarmente. Nell'esempio dell'API della nostra società di software, supponiamo che il team debba testare la risposta a una richiesta di recupero delle informazioni di un utente. Il comando GET è destinato a recuperare il nome e l'indirizzo e-mail di un utente dal suo numero ID in un database clienti. Il test unitario prevede di assicurarsi che questa richiesta GET recuperi le informazioni previste e che una richiesta per un ID utente inesistente restituisca un messaggio di errore appropriato.

I test di integrazione vengono generalmente eseguiti dopo i test unitari e vengono utilizzati per rilevare problemi che i test unitari non rilevano. Il test di integrazione aiuta a garantire che più componenti o servizi possano comunicare come previsto attraverso l'API. 

Tornando al nostro esempio, supponiamo che una caratteristica dell'API sia che un webhook, o notifica, viene inviato da un sistema all'altro in caso di un certo evento, come l'aggiunta di un nuovo cliente. Per garantire che questo funzioni, viene configurato un test di integrazione con un server falso che riceve una notifica e compie l'azione prevista quando le informazioni di un nuovo cliente vengono aggiunte al CRM. Questo processo si ripete per tutte le integrazioni.

Il test tramite contratto API garantisce che un'API faccia ciò che gli utenti si aspettano. Il contratto è in genere costruito come un file di specifica OpenAPI, che è un documento standard, leggibile dalla macchina, che definisce gli elementi della funzionalità e delle capacità di un'API. Un file di specifica API è tipicamente scritto in JSON o YAML e include elementi come endpoint API, metodi di autenticazione, i formati specifici di richieste e risposte accettabili, metadati e parametri di input.

La valutazione delle prestazioni dell'API spesso comporta la valutazione della sua velocità ed efficienza. In questa fase, i tester cercano di misurare il tempo di risposta delle query, i tassi di errore, l'uso delle risorse (come CPU e memoria), la latenza e la capacità di throughput. Comprendere le prestazioni di un'API in questa fase può aiutare a rivelare i colli di bottiglia o le ridondanze che possono rallentare l'esperienza dell'utente.

Le API sono spesso utilizzate per trasmettere dati sensibili, rendendo i test di sicurezza una componente vitale. I test di API security cercano essenzialmente di rompere l'API in vari modi per garantire sicurezza e stabilità. Questi tentativi potrebbero includere test di convalida degli input per assicurarsi che i dati vengano accettati solo quando inseriti in formati pre-approvati. 

I test di convalida degli input cercano vari tipi di attacchi. I tipi comuni di attacchi includono l'SQL injection, in cui attori malintenzionati inseriscono codice malevolo in un'applicazione. SQL è un linguaggio utilizzato per comunicare con i database e alcuni comandi SQL universali possono attivare risposte non autorizzate, come un elenco di tutti gli utenti. 

Altri metodi di test di sicurezza includono il test di autenticazione, che garantisce che le misure di identificazione come la biometria funzionino correttamente, e il test di autorizzazione, che garantisce che gli utenti possano accedere solo alle caratteristiche a cui sono autorizzati. 

I test di sicurezza vengono condotti sia durante che dopo la fase di sviluppo e le nuove caratteristiche dell'intelligenza artificiale (AI) e l'automazione stanno migliorando la forza e l'accuratezza di questi test. Gli strumenti di test di sicurezza AI possono generare automaticamente test, scansionare codice per bug, analizzare dati di prestazioni per aiutare a prevedere problemi e segnalare comportamenti anomali, e molto altro.

In settori come la sanità e i servizi finanziari, esistono regolamenti, leggi e linee guida per proteggere la sicurezza, la protezione e la privacy degli utenti. Esempi includono HIPAA (stato di salute americano), GDPR (informazioni personali dell'UE) e CCPA (informazioni personali della California). 

Il test di conformità è un test che garantisce che l'API rispetti qualsiasi leggi e linea guida applicabile. Ad esempio, il GDPR garantisce il "diritto all'oblio", il che significa che gli utenti possono richiedere la cancellazione completa dei propri dati senza indebito ritardo. I test di conformità per un'API conforme al GDPR richiederebbero la garanzia del rispetto di questa regola.

La fase di distribuzione è il lancio dell'API. È stato testato per funzionalità, sicurezza e conformità ed è pronto per essere utilizzato. Nella fase di distribuzione, l'API si sposta dall'ambiente di test all'ambiente di produzione live. La distribuzione delle API prevede diverse fasi.

Prima della distribuzione, il team dovrebbe effettuare ulteriori recensioni per assicurarsi che l'infrastruttura di supporto, la documentazione, il supporto agli utenti, le strategie di distribuzione e comunicazione e i protocolli di monitoraggio siano tutti completati e pronti all'uso. Questa checklist può includere la scalabilità dei server, la configurazione di avvisi e notifiche, la creazione di una pagina FAQ, l'invio di un annuncio ai clienti (o un annuncio pubblico) e altro ancora.

CI/CD, acronimo di integrazione continua/distribuzione continua, è un insieme di pratiche che automatizzano e semplificano i cicli di sviluppo, test e distribuzione del software. È una pratica fondamentale all'interno della metodologia DevOps. Come le applicazioni software, anche le API sono comunemente incorporate nelle pipeline CI/CD per semplificare e automatizzare la distribuzione, il testing e l'aggiornamento delle API. 

Un API gateway è un livello software che fornisce un unico punto di ingresso per consentire ai clienti di accedere a una varietà di servizi di backend o a più istanze di un servizio di backend. Gli API gateway possono offrire diversi vantaggi:

• Semplicità: i clienti devono tenere traccia solo di un singolo URL di servizio, anziché di molti altri
  
  
• Bilanciamento del carico: un'organizzazione può distribuire il traffico di un singolo servizio su più istanze per distribuire il carico ed evitare i colli di bottiglia delle prestazioni
  
  
• Sicurezza e governance: un gateway può essere utilizzato per applicare protocolli di sicurezza e governance standardizzati a numerose API. 
  
  
• Caching: un gateway può aiutare con la cache memorizzando i dati frequentemente accessibili su più servizi. Ciò contribuisce ad accelerare i tempi di risposta e a migliorare le prestazioni.

Le organizzazioni spesso rilasciano versioni beta per utenti selezionati al fine di testare un'API prima di rilasciarla completamente al pubblico. Questo permette all'organizzazione di individuare e correggere bug, raccogliere feedback, misurare le prestazioni e promuovere l'API in un ambiente più sicuro e controllato.

Una volta completati la lista di controllo e gli eventuali lanci beta, è il momento di "cambiare" e implementare completamente l'API. Questo processo potrebbe includere l'avvio di strategie di distribuzione per informare ulteriormente i clienti interni o esterni sull'API e incoraggiarne l'uso. Il processo di distribuzione può includere anche la pubblicazione di guide utente e altre attività di divulgazione pubblica, l'aggiornamento di un sito web o di una directory API e la modifica delle impostazioni per consentire l'accesso istantaneo invece di richiedere l'autenticazione privata.

Uno dei vantaggi fondamentali della comprensione e pianificazione di un ciclo di vita completo dell'API è garantire che monitoraggio, observability e manutenzione siano al centro dell'attenzione fin dall'inizio. Il lavoro non è completo al momento del lancio; c'è ancora del lavoro da fare. Il monitoraggio delle API è un processo continuo, progettato per vedere come un'API si comporta nel mondo reale, in tempo reale. 

Le metriche chiave per il monitoraggio includono i tempi di risposta, ovvero quanto tempo impiega l'API a rispondere alle richieste; tasso di errore, ovvero la percentuale di richieste fallite; throughput e traffico, ovvero il numero di richieste che l'API può gestire; e l'analisi dell'infrastruttura, che misura lo sforzo e lo stato di salute dei server.

L'elemento di manutenzione deriva dalla risposta ai dati raccolti dagli strumenti di monitoraggio. La manutenzione può consistere nella correzione di bug, nell'ottimizzazione delle prestazioni o addirittura nell'aggiunta di nuove caratteristiche o funzionalità.

Nel nostro esempio di CRM, gli strumenti di monitoraggio potrebbero rilevare che la latenza è elevata quando i dati dei clienti vengono inviati da una piattaforma all'altra; la fase di manutenzione intervenire riducendo le ridondanze del codice, perfezionando le impostazioni di memorizzazione nella cache o riposizionando i server per essere più vicini ai clienti che servono.

La fine del ciclo di vita di un'API è altrettanto importante, dinamica e informativa quanto qualsiasi altra fase.

Il versioning è il processo esteso di mantenimento dell'efficacia di un'API attraverso aggiornamenti durante la sua vita attiva. La chiave del versioning è offrire modifiche e miglioramenti senza interrompere le funzionalità esistenti per gli utenti consolidati. 

Per le semplici correzioni di bug e simili, gli aggiornamenti vengono in genere rilasciati senza applicare una nuova versione dell'API, in quanto queste piccole modifiche sono considerate "non-breaking". Ma per le modifiche "breaking", in cui una nuova versione non è retrocompatibile con la versione che intende sostituire, è buona norma introdurre la modifica come una nuova versione.

La comunicazione, sia precoce che frequente, è fondamentale per il controllo delle versioni. Una pratica comune è quella di supportare le versioni parallele: la versione precedente rimane attiva e funzionale insieme alla nuova versione e gli sviluppatori comunicano le modifiche per esortare gli utenti a migrare alla nuova versione. Una volta eseguita la migrazione di tutti o di un numero sufficiente di utenti, la versione precedente può essere disattivata.

Il ritiro è la rimozione e la disabilitazione permanenti di un'API. Non tutte le API vengono ritirate, ma è comune che prima o poi vengano sostituite. Ci sono diverse ragioni per cui un'API potrebbe essere ritirata:

• Una nuova versione offre prestazioni superiori
• Le esigenze di conformità o sicurezza non sono più adeguatamente affrontate 
• Cambiamenti aziendali o finanziari all'interno dell'organizzazione
• Incompatibilità con software più recenti

Dopo il ritiro, un'API non sarà più funzionante. Esistono però alcune fasi che possono contribuire a facilitare questa transizione.

Il ritiro di un'API richiede discussione. È necessario ritirare l'API e perché? Qual è l'alternativa, se ce ne sarà una? Chi dovrà essere informato dell'imminente ritiro?

In genere, l'organizzazione annuncia che un'API deve essere ritirata. Questo annuncio include tutte le informazioni necessarie per gli utenti dell'API, come il motivo per cui questo cambiamento sta avvenendo, quando avverrà e quali azioni l'utente deve intraprendere, se ce ne sono. 

Poi l'API viene ufficialmente deprecata. L'API al momento rimane operativa ma non riceverà nuovi aggiornamenti o funzionalità. Il periodo di deprecazione è progettato per dare all'utente tempo e consapevolezza per apportare eventuali modifiche necessarie.

Il "sunset day" è quando l'API pubblica è completamente disattivata, a quel punto le richieste non riceveranno più risposta e i clienti che tentano di raggiungere l'API riceveranno un messaggio di errore. È buona norma aggiornare la documentazione per riflettere questa modifica e liberare spazio sul server o altra infrastruttura utilizzata dall'API. 

Un post-mortem su un'API ritirata può essere un esercizio utile. I team possono discutere le lezioni apprese durante l'intero ciclo di vita dell'API e come applicarle ai progetti futuri.