Cos'è il modello di maturità delle API?

Alcuni framework di maturità delle API enfatizzano dimensioni specifiche come sicurezza, reperibilità , manutenibilità o ingegneria della piattaforma. I fornitori di API management, tra cui Kong, Tyk e Curity, offrono modelli di maturità delle API allineati alle proprie soluzioni, aiutando i clienti a valutare i loro progressi nell'adozione di tali piattaforme. Altri modelli hanno una portata più ampia e possono essere applicati a qualsiasi protocollo o architettura.

Le application programming interface (API), che facilitano le connessioni tra servizi e applicazioni separati, sono un pilastro fondamentale di Internet, poiché aiutano gli sviluppatori a utilizzare tecnologie e fonti di dati di terze parti, anziché crearle da zero. Consentono inoltre l'integrazione di risorse, dati, sicurezza dei dati e governance all'interno delle organizzazioni, semplificando le distribuzioni interne e le comunicazioni tra team. Più API possono essere confezionate insieme a librerie, strumenti di interfaccia utente e altri componenti per formare un kit di sviluppo software (SDK), un insieme di strumenti che aiuta gli sviluppatori a costruire applicazioni standardizzate in modo rapido e affidabile.

I modelli di maturità delle API identificano e descrivono specifiche innovazioni strutturali e tecnologiche, nonché best practice strategiche che possono aiutare le organizzazioni a sviluppare sistemi API più sofisticati e robusti, migliorando efficienza, sicurezza e interoperabilità. Servono come una roadmap che aiuta le organizzazioni a decidere a quali innovazioni dare priorità, accelerando lo sviluppo delle API.

Il modello di maturità di Richardson, uno dei framework più citati, valuta l'aderenza di un'API ai principi RESTful su quattro livelli di maturità, con il livello più alto che rappresenta un sistema completamente RESTful.

Nel 2000, lo scienziato informatico Roy Fielding introdusse REST, uno stile architettonico che promuove funzionalità come un'interfaccia uniforme, disaccoppiamento client-server, statelessness, memorizzazione nella cache e sistemi stratificati. Insieme, queste funzionalità possono migliorare la scalabilità, l'efficienza e la flessibilità all'interno delle organizzazioni e possono contribuire a un internet più aperto, resiliente e sicuro se implementate su scala più ampia. Le iterazioni moderne utilizzano spesso HTTP per trasportare informazioni e il formato JSON leggibile dall'uomo per organizzare questi dati, sebbene possano essere utilizzati anche altri protocolli e formati.

Nel 2008, l'ingegnere software Leonard Richardson ha sviluppato questo framework con un modello che identifica cambiamenti tecnici specifici che le organizzazioni possono implementare per migliorare l'adattabilità e la resilienza del design delle loro API REST. Il modello di maturità di Richardson (RMM) "incoraggia a considerare le tre tecnologie web – URI, HTTP e ipermedia (noto anche come HTML) – come tre tecnologie individuali piuttosto che come un pacchetto unico", ha dichiarato Richardson a IBM Think. Il framework mostra i benefici pratici dell'implementazione progressiva di ciascuna di esse, "dato che disponiamo di queste tecnologie, sono molto diffuse e ampiamente supportate da ogni linguaggio di programmazione".

Il modello di maturità di Richardson dà priorità all'implementazione delle risorse, dove a ciascuna risorsa viene assegnata un'URI distinta, in conformità con i principi generali di REST, che raccomandano di assegnare a ciascuna risorsa un'identificazione unica. L'RMM incoraggia inoltre l'uso di documenti di risposta, che catturano lo stato attuale di un'API, piuttosto che documenti di descrizione, che presentano una descrizione statica e predefinita di un'API in un singolo momento. Il modello si applica generalmente alle applicazioni web basate su http, anche se come framework può essere utilizzato anche in altri contesti, come IoT e pipeline dati.

Il modello di maturità di Richardson utilizza quattro livelli per distinguere tra diversi gradi di maturità, da un'architettura non RESTful a una completamente RESTful.

Il livello zero rappresenta una progettazione non RESTful, con un singolo endpoint (come "/api") e un singolo comando (di solito POST). Sebbene il livello zero sia semplice da implementare, non utilizza le funzionalità più potenti di HTTP, inclusi verbi, URI e codici di stato. Invece, HTTP viene utilizzato semplicemente come meccanismo di trasporto, con tutti i dettagli operativi aggiunti al corpo del messaggio stesso.

Poiché i modelli di chiamata di procedura remota (RPC) basati su XML hanno storicamente utilizzato questo metodo, i critici lo hanno soprannominato "swamp of POX" (plain old XML). L'idea è che, con una mancanza di struttura e di delimitazioni chiare tra i servizi, le funzioni e i dati possono facilmente diventare disordinati e strettamente accoppiati. Al livello zero, l'API non ha la capacità di identificare o esporre risorse scoperte, costringendo i consumatori API a sapere in anticipo cosa è disponibile. Gli sviluppatori potrebbero avere difficoltà con scaling, versioning e risoluzione dei problemi perché il singolo endpoint non può condividere informazioni su se stesso.

Il primo livello introduce URI multipli, ognuno dei quali è in grado di rappresentare una risorsa diversa. Ma continua a usare un solo verbo HTTP, tipicamente POST. Invece di interagire con un endpoint generico "/api", i clienti possono ora chiamare endpoint che corrispondono a risorse specifiche, ad esempio "/products", "/carts" o "/invoices" in un ambiente di e-commerce. Tuttavia, i client tipicamente devono comunque trasmettere l'intento operativo o le azioni attraverso il corpo stesso della richiesta, invece di utilizzare un insieme predefinito di verbi HTTP.

Questo approccio stabilisce linee più pulite tra le risorse e riduce le ambiguità sulle risorse disponibili per i clienti. Ma gli sviluppatori possono facilmente confondere quali azioni possano essere eseguite perché non esiste un formato standardizzato per chiamare gli URI. Il primo livello può anche diventare complicato nel tempo perché, in pratica, gli sviluppatori potrebbero creare nuovi endpoint per singole azioni, come "/productsUpdate" o "/productsDelete". Questo approccio può far sì che gli URI si accumulino gradualmente, rendendo più difficili i rollout e il versioning.

Infine, il modello rende gli sviluppatori più dipendenti dalla documentazione esterna delle API perché, sebbene alle risorse vengano assegnati URI distinti, non possono esporre quali azioni possano essere interpretate o eseguite.

Il livello due aggiunge i metodi HTTP, un insieme standardizzato di verbi che gli sviluppatori possono utilizzare per interagire con dati e servizi. In molte configurazioni, i client possono utilizzare quattro comandi di base – creare, leggere, aggiornare o eliminare – per eseguire azioni diverse in ciascun endpoint. Le intestazioni possono essere utilizzate per trasmettere informazioni aggiuntive, come il tipo di contenuto, i requisiti condizionali o le credenziali di autorizzazione, durante la chiamata API.

Questo approccio è più efficiente e organizzato rispetto al livello uno e zero perché gli utenti hanno un'idea di cosa sia capace l'API e di come i client possano interagire con essa. Ma le API non sono in grado di trasmettere queste informazioni in tempo reale: gli utenti possono conoscere ogni API solo attraverso un portale dello sviluppatore esterno, riducendo la rilevabilità. Questo approccio statico può anche portare a disallineamenti se la documentazione API non corrisponde alle funzionalità attuali.

Oggi, la maggior parte degli ecosistemi API delle organizzazioni opera al livello due, poiché questo livello offre un buon equilibrio tra prevedibilità, efficienza e accessibilità. Consente inoltre alle organizzazioni di utilizzare al meglio le funzionalità infrastrutturali specifiche di HTTP, come la cache (memorizzazione localmente delle risorse frequentemente utilizzate, così da poterle recuperare rapidamente), portando a significativi miglioramenti di prestazioni.

Il terzo livello introduce HATEOAS, ovvero ipermedia, come motore dello stato dell'applicazione. Quando un cliente effettua una chiamata API, l'API risponderà con un elenco dinamico di opzioni per varie azioni e termini correlati, ad esempio il funzionamento dei browser moderni. Queste azioni e termini sono trasmessi in band, il che significa che gli sviluppatori non devono consultare documentazione esterna per conoscerli. Le architetture basate su ipermedia favoriscono anche l'interoperabilità perché i clienti esterni possono accedere facilmente ai servizi senza imparare a usarli in anticipo.

Allo stesso tempo, i controlli ipermediali introducono una maggiore complessità in fase di esecuzione: "Il client deve essere in grado non solo di reagire in modo pre-programmato, ma anche di leggere i documenti in arrivo dal server e di utilizzare il contenuto di quei documenti per prendere la decisione sulla sua prossima richiesta", ha detto Richardson.

Costruire e mantenere le funzionalità ipermediali può essere più costoso e richiedere più tempo a causa della struttura dinamica dell'ipermedia. L'API risponde alle richieste dei clienti con un insieme di link per ulteriori azioni, il che risulta più impegnativo dal punto di vista operativo. Inoltre, molte piattaforme client non supportano l'ipermedia, quindi quando un'organizzazione adotta HATEOAS, gli utenti esterni potrebbero dover trovare strumenti compatibili prima di poter accedere a questi servizi.

Oggi, HATEOAS è utilizzato più spesso da biblioteche, organizzazioni non profit, istituzioni scientifiche, coalizioni di mercato o aziende emergenti (organizzazioni che cercano di rivoluzionare un settore), ha detto Richardson, perché promuove apertura e interoperabilità. L'ipermedia può essere efficace anche se usata internamente perché rende le API e le azioni facilmente individuabili dagli utenti, anche da chi non ha conoscenze pregresse dell'ecosistema API. Alcune aziende potrebbero offrire API ipermediali durante la loro fase di crescita, per poi limitare l'accesso dopo aver iniziato a monetizzare il loro prodotto.

Il settore si sta spostando sempre più verso alternative come GraphQL e gRPC per casi d'uso particolari. Mentre il 93% degli sviluppatori afferma di utilizzare servizi web RESTful in qualche modo, secondo il rapporto State of the API di Postman, un terzo ora usa GraphQL e il 14% usa gRPC. GraphQL può recuperare in modo intelligente richieste da più microservizi, persino servizi ospitati in ambienti diversi, e compilarle in un'unica risposta, aumentando l'efficienza e prevenendo un provisioning eccessivo o insufficiente. gRPC, invece, è ideale per streaming, telemetria e altri casi d'uso in cui alte prestazioni e bassa latenza sono preoccupazioni principali.

Sebbene GraphQL e gRPC non riescano a replicare la natura dinamica dell'ipermedia, entrambe le architetture affrontano con maggiore precisione i punti critici legati all'efficienza e alla gestione degli schemi, portando alcune organizzazioni a dare priorità a queste implementazioni rispetto ai controlli ipermediali completi.

Nel modello di maturità di Richardson, passare da un livello di maturità delle API all'altro può presentare sfide sia progettuali che tecniche. Il processo spesso prevede il refactoring del codice del server per ospitare più URI (livello uno) e più metodi HTTP (livello due). Ciò si ottiene aggiornando le regole di routing, le interazioni con il database, i test, la documentazione e i controller.

Le organizzazioni potrebbero iniziare catalogando i propri endpoint attuali, identificando quali possono essere modificati per rispettare i vincoli RESTful e mappando le risorse e i comandi necessari. Gli sviluppatori potrebbero costruire una nuova versione sopra quella attuale dell'organizzazione, così che le chiamate dei client non vengano interrotte durante la transizione. Un set completo di codici di errore può anche aiutare gli utenti a imparare a navigare nei nuovi endpoint API e a risolvere errori senza consultare troppe documentazioni.

Mentre il RMM si concentra su implementazioni tecnologiche specifiche nei sistemi RESTful, i modelli organizzativi adottano una visione più ampia, aiutando le imprese ad allinearsi attorno a un insieme condiviso di principi che favoriscono coerenza, ottimizzazione delle risorse e adattabilità. Sebbene i framework di maturità strategica possano differire da un'organizzazione all'altra, un approccio comune prevede quattro livelli:

Negli ecosistemi API di base o ad hoc, le organizzazioni reagiscono a preoccupazioni immediate piuttosto che lavorare sotto un framework coeso di sviluppo API. Gli sviluppatori creano e ritirano le API secondo necessità con un controllo centralizzato limitato, che può portare a disallineamenti e problemi di governance, sicurezza e observability. Con pochi insight sulle attuali prestazioni delle API, i team non possono allocare efficacemente le risorse o pianificare il futuro.

Gli ecosistemi API standardizzati introducono documentazione coerente, convenzioni di denominazione, codici di errore e pattern di progettazione. Un API gateway potrebbe essere utilizzato per applicare l'autenticazione, l'autorizzazione e altri protocolli API security centralizzati. Gli sviluppatori possono aggiungere, rimuovere e gestire con sicurezza le API all'interno della struttura di governance dell'organizzazione e possono riutilizzare e adattare i componenti senza problemi. I clienti possono facilmente scoprire e conoscere i servizi disponibili tramite un portale dello sviluppatore e un onboarding integrato, aumentando l'adozione complessiva delle API.

Tuttavia, poiché in questa fase ci sono pochi meccanismi per rilevare le prestazioni e la sicurezza delle API, i team potrebbero faticare a mantenere la supervisione sull'ecosistema. Ad esempio, un'organizzazione potrebbe non essere a conoscenza di violazioni di sicurezza, errori di versioning o problemi di autenticazione all'interno di un particolare cluster API.

I framework gestiti utilizzano dati di telemetria, KPI e altre metriche per acquisire le prestazioni delle API in modo più dettagliato. Ad esempio, un sistema di monitoraggio può avvisare gli sviluppatori quando i client devono affrontare un tempo di inattività eccessivo delle API e aiutare a identificare il problema sottostante, che si tratti di sovraccarico del server, interruzioni della rete, disallineamenti del codice o altri problemi.

Gli ecosistemi gestiti potrebbero anche disporre di infrastrutture di governance API più avanzate, che preserva l'autonomia del team fornendo agli stakeholder una chiara comprensione di quali API sono responsabili di gestire. Infine, gli ecosistemi gestiti introducono processi formali di gestione del ciclo di vita, in cui le API vengono monitorate durante le fasi di progettazione, sviluppo, manutenzione, versioning e dismissione. A questo livello, tuttavia, le organizzazioni potrebbero ancora non avere una visione coesa di come l'API management contribuisca agli obiettivi aziendali più ampi.

I framework ottimizzati o strategici combinano governance, standardizzazione, gestione del ciclo di vita, metriche e best practice con business planning a lungo termine. Con la supervisione dell'intera rete, le organizzazioni possono scalare e allocare risorse in modo efficiente e rispondere dinamicamente alle condizioni di mercato in evoluzione. Invece di considerare le API solo come componenti tecnici, le organizzazioni possono implementare API al servizio di obiettivi aziendali più ampi. I framework strategici aiutano le organizzazioni a elaborare roadmap e strategie lungimiranti, accelerando l'innovazione e migliorando l'efficienza operativa.

Le organizzazioni potrebbero elaborare modelli di maturità delle API per affrontare specifici punti critici o obiettivi operativi. Le aree di interesse più comuni includono:

Questi modelli di maturità si concentrano su principi di progettazione API come l'adozione di protocolli, pratiche e standard specifici che contribuiscono a migliorare l'esperienza utente. L'RMM è un esempio di framework basato sul design, ma altri modelli potrebbero concentrarsi su GraphQL, gRPC e altri stili architettonici.

I modelli di governance si concentrano sul grado in cui le organizzazioni possono mantenere il controllo e la supervisione sui loro ecosistemi API. Ai livelli più alti, le organizzazioni mantengono un'elevata conformità, qualità dei dati e sicurezza, preservando al contempo l'autonomia degli stakeholder.

I framework basati sulla governance considerano anche la qualità dei meccanismi di applicazione di un ecosistema API, incluso se esso incorpora controlli automatizzati e processi di validazione. I modelli di proprietà, invece, assegnano le API a team specifici in modo che ogni API sia considerata.

I framework di maturità incentrati sulla sicurezza valutano l'aderenza di una rete API alle best practice di sicurezza. Nelle prime fasi, le organizzazioni potrebbero affidarsi alle chiavi API o all'autenticazione HTTP di base, che mancano di controllo granulare e sono vulnerabili all'esposizione. I sistemi avanzati potrebbero introdurre l'autenticazione e l'autorizzazione basate su token e l'accesso zero-trust. I framework più sofisticati aderiscono ai principi di gestione delle identità e degli accessi, come l'utilizzo dei protocolli di autorizzazione OAuth e OpenID Connect (OIDC).

I documenti API sono guide tecniche che forniscono istruzioni su come gli sviluppatori possono utilizzare e integrare una particolare API. La documentazione può includere tutorial ed esempi di codice, oltre a note di rilascio e parametri di chiamata accettabili.

Inizialmente, le organizzazioni potrebbero non disporre di un processo standardizzato per la creazione e la manutenzione della documentazione delle API, offrendo agli sviluppatori un insight limitato delle funzionalità di ciascuna API. I livelli superiori potrebbero introdurre formati standardizzati per descrivere le specifiche API, come OpenAPI Specification (OAS) o API Blueprint. I framework API maturi potrebbero anche incorporare l'automazione, aiutando a garantire che la documentazione venga aggiornata automaticamente insieme ad ogni lancio.

I modelli di maturità focalizzati sull'observability aiutano le organizzazioni a monitorare la sofisticazione dei loro meccanismi di raccolta dati tra i microservizi. I sistemi di base possono utilizzare la telemetria e le metriche per aiutare le organizzazioni a individuare gli errori, ma non sono in grado di aiutare a identificare le tendenze dei dati a lungo termine.

Le piattaforme più complesse possono tracciare in modo proattivo la latenza, i tassi di richiesta e altre metriche rilevanti, per aiutare le organizzazioni a rispondere in anticipo a tempi di inattività, disallineamenti e altri problemi. Nel livello più alto, le organizzazioni possono identificare modelli dati di alto livello e generare insight attuabili che guidano lo sviluppo futuro delle API.