Cos'è la progettazione di API?

La progettazione di API si riferisce al processo di sviluppo di interfacce di programmazione delle applicazioni (API) che mette a disposizione di sviluppatori e utenti dati e funzionalità applicative. Le API sono ormai cruciali per le organizzazioni moderne perché consentono di aggiungere nuove funzionalità a qualsiasi cosa, dalle operazioni e dai prodotti alle strategie di collaborazione. Non è più un azzardo dire che la maggior parte delle organizzazioni non si chiede più se realizzare programmi API, ma come farlo. 

Un programma API efficace deve prendere forma dalla strategia globale di un'organizzazione per poter contribuire al raggiungimento degli obiettivi aziendali. Una strategia ha le carte in regola quando si riesce a rispondere alle 3 domande seguenti con estrema chiarezza:

1. Perché vogliamo implementare le API?
2. Quali risultati concreti vogliamo ottenere con queste API?
3. Come intendiamo eseguire il programma API per ottenere ciò che ci siamo prefissati?

Perché

Questa domanda viene spesso mal interpretata. Innanzitutto, sarebbe più utile concentrarsi sul valore dell'effetto dell'API piuttosto che sull'API di per sé. In fin dei conti, ciò che conta è il core business dell'organizzazione, non l'API. Un'API mostra il suo valore quando diventa un canale che offre nuovi tipi di accesso al valore esistente di un'organizzazione.

Un altro presupposto comune errato è credere che affinché un'API possa essere preziosa debba essere messa a disposizione a pagamento. Questo può essere vero solo in quei pochissimi casi in cui l'API stessa è il prodotto. Le API, infatti, vengono solitamente usate per accrescere altri parametri: le vendite, le segnalazioni degli affiliati, la consapevolezza del marchio e via dicendo. Per gli utenti il valore dell'API è legato al risultato della chiamata API (richiesta di servizio e risposta), non alla chiamata stessa.

Secondo un sondaggio di Cutter Consortium e Wipro che ha coinvolto 152 organizzazioni, le aziende sono spinte a definire un programma API soprattutto per sviluppare nuove collaborazioni, aumentare il fatturato, sfruttare nuovi modelli aziendali, migliorare il time-to-market e introdurre nuovi canali di distribuzione. Le motivazioni principali dal punto di vista tecnologico sono: migliorare l'integrazione applicativa, accrescere l'integrazione mobile e supportare il collegamento con un numero maggiore di dispositivi. È chiaro che l'organizzazione deciderà di investire nelle API solo se i vantaggi saranno sufficientemente espliciti.

Cosa

La seconda domanda dovrebbe essere: "Quali risultati concreti vogliamo ottenere con queste API?", o in altre parole: "Cosa fanno effettivamente le API e come influiscono sulla strategia aziendale più ampia?".

Il cosa delle API può essere definito con più facilità sfruttando i concetti di vista interna e di vista esterna di un'organizzazione. La vista interna si riferisce alle risorse specifiche e preziose di un'organizzazione. Più preziosi ed esclusivi sono i servizi e le risorse offerte più adatti risultano per un programma API.

Ad esempio, un'organizzazione che utilizza dati esclusivi potrebbe sfruttare appieno questa risorsa garantendo l'accesso ai dati tramite l'API. Contenuti, dati e servizi esclusivi conferiscono un valore elevato all'accesso all'API.

Se si vuole sapere che cosa un'API dovrebbe fare per un'azienda, è necessario esaminare le viste
interne ed esterne. La combinazione delle due viste offre una risposta al cosa.

In pratica, mentre il perché resta spesso immutato, il cosa può variare notevolmente a causa di fattori esterni come i mercati, le considerazioni tecniche o le condizioni economiche. Anche le istruzioni interne sul valore di una risorsa possono cambiare, influendo su ciò che dovrebbe essere ottenuto con un'API.

Come

L'implementazione e l'esecuzione sono i punti chiave della domanda finale: "Come dobbiamo progettare il programma API per poter ottenere ciò che desideriamo?".

I team devono chiedersi:

• Quale tecnologia viene usata per creare le API?
• Come vengono progettate le API?
• Come vengono mantenute le API?
• Come vengono promosse le API all'interno dell'organizzazione o commercializzate nel mondo esterno?
• Quali risorse sono disponibili?
• Chi dovrebbe essere inserito nel team?
• Come teniamo traccia del successo rispetto agli obiettivi aziendali che sono stati fissati?

Un team API è strettamente correlato a un team di "prodotto" che deve occuparsi di creare, distribuire, gestire e ottimizzare l'infrastruttura da cui altre persone dipendono, a prescindere se i clienti sono interni o esterni.

I team API, come i team di prodotto, possono essere molto variegati, ma devono in genere includere una persona che agisca come il responsabile della strategia e degli obiettivi e che concentri la sua attenzione sul prodotto, membri che si occupino della progettazione assicurandosi di adottare gli approcci migliori, ingegneri che mettano in atto la tecnologia API e personale operativo che gestisca l'esecuzione vera e propria dell'API.

Nel tempo è possibile aggiungere altre persone come membri del team di supporto e della community, API evangelist, rappresentanti della sicurezza e altri ancora.

Nel suo intervento del 2012 alla O'Reilly Open Source Convention, John Musser ha evidenziato 5 "fattori cruciali" per API di impatto:

1. Fornire un servizio di valore
2. Avere un piano e un modello aziendale
3. Creare un'API che sia semplice, flessibile e facile da adottare
4. Fare in modo che sia anche gestibile e misurabile
5. Fornire un ottimo supporto agli sviluppatori

Il primo fattore, fornire un servizio di valore, è importante soprattutto quando si relaziona al perché del programma API. La proposizione di valore è il principale promotore del successo dell'API. Se la proposizione di valore è sbagliata o non esiste affatto, sarà molto difficile o addirittura impossibile trovare degli utenti.

Le aziende che hanno un prodotto digitale o fisico possono generare valore
tramite un'API, se quest'ultima si collega alle offerte esistenti e le migliora. L'API offrirà valore fintanto che è strutturata in modo tale da coprire gli esempi di utilizzo significativi per gli sviluppatori.

Individuare e descrivere il valore dell'API è un processo iterativo. Il primo passaggio consiste nel descrivere i processi che gli utenti vogliono che siano portati a termine. Ad esempio:

• Inviare in automatico comunicazioni urgenti a membri del team durante un'emergenza
• Eseguire il backup di file strategici per assicurarsi che non vengano persi
• Raccogliere dati di esempio per rilevare determinati eventi

Successivamente, occorre identificare le criticità che gli utenti riscontrano prima, durante e dopo aver cercato di completare un processo:

• Garantire l'affidabilità dell'invio con più tentativi, individuare guasti, preoccuparsi del numero di messaggi che sono stati inviati al posto di uno solo e integrare diversi sistemi di distribuzione dei messaggi a seconda della posizione dell'utente
• Garantire la distribuzione sicura dei file, ma anche ridurre al minimo la quantità di larghezza di banda utilizzata dal trasferimento
• Gestire grandi volumi di dati e cercare di correlarli in tempo reale

Il terzo passaggio consiste nel riassumere i potenziali vantaggi che è possibile ottenere:

• Inviare altri tipi di notifiche, creando opportunità anziché avvisi di minacce
• Eliminare altri sistemi di storage una volta raggiunto il livello di affidabilità ottimale
• Innescare automaticamente azioni basate sugli eventi

Quando si prendono in esame queste sfide, pensare in maniera più ampia ed elencare elementi come supporto, documentazione o portali degli sviluppatori, tutto ciò che un utente potrebbe usare. In seguito, descrivere come si intendono eliminare o ridurre fastidi in cui gli utenti dell'API incorrono prima, durante o dopo aver cercato di completare un processo, o problemi che impediscono loro di completarlo. Quindi descrivere come si intende creare vantaggi di qualsiasi tipo per gli utenti dell'API.

Nel corso di questo processo, i tre esempi che abbiamo riportato sopra possono dare luogo a:

• Un'API di messaggistica multicanale con un'unica chiamata per inviare messaggi e la capacità di riprovare automaticamente fino alla ricezione (ad esempio, Twilio, PagerDuty)
• Un'API di sincronizzazione dello storage con chiamate ottimizzate per controllare in maniera efficiente se è necessario sincronizzare le nuove versioni (ad esempio, Bitcasa, Box)
• Un'API che aggrega più sorgenti di dati in un flusso configurabile, che può essere filtrato, campionato e manipolato con facilità (ad esempio, GNIP, DataSift)

Infine, un esercizio utile consiste nel comporre diverse dichiarazioni che chiariscono il legame tra l'API e il profilo utente. Se è difficile identificare tali dichiarazioni, è necessario riconsiderare il modello API, aggiungendo, modificando, perfezionando o eliminando, se del caso, le funzionalità dell'API. Può accadere che l'API offra un grande valore, ma che sia rivolta a una tipologia di utenti sbagliata.

La dichiarazione globale che riassume e astrae tutte le dichiarazioni di idoneità rappresenta la proposizione di valore della tua API. Nel caso della API di messaggistica di cui abbiamo parlato sopra, la proposizione di valore potrebbe essere qualcosa del genere:

La nostra API di messaggistica offre agli sviluppatori enterprise una funzionalità di messaggistica affidabile, garantita e priva di latenza per applicazioni business critical. L'API è inoltre supportata da kit di sviluppo software (Software Development Kit, SDK) che coprono i linguaggi di programmazione più popolari per garantire una rapida integrazione.

In alcuni casi, può sembrare che il lavoro da eseguire per la creazione di una semplice API interna sia eccessivo. È tuttavia fondamentale focalizzarsi sul valore anche in caso di utilizzo interno. Se la proposizione di valore non è ben definita, proporre l'API agli altri team risulta più complicato. Se, invece, la proposizione di valore è ben definita, l'adozione dell'API sarà più agevole e il programma API contribuirà notevolmente al successo dalla tua azienda.

Il valore del programma API può essere definito con facilità usando queste 5 domande:

1. Chi è l'utente? La risposta dovrebbe includere il rapporto che esiste tra l'utente e l'azienda (clienti esistenti, partner, sviluppatori esterni), il ruolo (data scientist, sviluppatori mobile, membri del team operativo) e i requisiti o le preferenze.
2. Quali criticità degli utenti stiamo risolvendo e/o quali vantaggi stiamo creando per l'utente? La risposta a questa domanda dovrebbe considerare l'attività, le sfide e i vantaggi per il cliente, partendo dalla proposta di valore, indicare se un'esigenza critica è stata o meno soddisfatta (una criticità o un'opportunità di fatturato) e specificare quale parametro è stato migliorato per l'utente (velocità, fatturato, risparmio sui costi, riuscire a fare qualcosa di nuovo).
3. Quali esempi di utilizzo vengono supportati dall'API? La proposizione di valore deve aiutare a identificare le soluzioni alle sfide dei tuoi clienti o le opportunità create dall'API  che risultano essere più efficaci per l'azienda e l'utente. Pianificare l'API in modo tale da affrontare quegli esempi di utilizzo.
4. In che modo il valore per l'utente può essere prolungato nel tempo? Pianificare la proposizione di valore tenendo in considerazione modifiche future. Individuare i traguardi importanti relativamente alle modifiche interne o esterne.
5. Quale valore interno viene creato per l'organizzazione? Considerare i vantaggi interni e in che modo l'API è in grado di contribuire al valore aziendale.

Riuscire a calcolare il valore di un'API è un importante traguardo nella progettazione del programma API. Tuttavia, bisogna ricordare che le API generano anche costi che devono essere compensati dal valore. Il valore deve essere reale anche se non può essere misurato in termini monetari. Ecco come valutarlo:

• Qual è l'attività chiave dell'organizzazione?
• In che modo può essere utilizzata un'API per accelerare o incrementare tale attività?

In alcuni casi le API possono portare a opportunità completamente nuove che esulano dal modello aziendale esistente di un'organizzazione, ma anche in questo caso, sfruttando generalmente risorse o competenze esistenti per farlo in modi nuovi.

Riepilogando, la determinazione del giusto modello aziendale è fondamentale per realizzare API efficaci per tre motivi:

1. Porta all'attenzione dell'organizzazione il valore dell'API, spingendola a impegnarsi a lungo termine nel programma API. Senza questo tipo di impegno è spesso difficile disporre delle risorse necessarie per completare le attività necessarie per stabilire ed eseguire un programma API efficace.
2. Aiuta a definire la funzionalità del prodotto, indispensabile per soddisfare le terze parti e incrementare l'attività.
3. Garantisce la giusta considerazione dei ruoli e delle responsabilità all'interno di un'organizzazione e di chi detiene quali parti del valore generato dall'API. Ciò implica anche la definizione dei vantaggi ottenuti dagli utenti dell'API e di come questi si rapportano ai vantaggi ottenuti dal provider dell'API.

I principi fondamentali di una buona progettazione di API possono variare durante l'implementazione. Tutte le automobili sono dotate di volante, freno e acceleratore. Un guidatore esperto potrà riscontrare differenze nelle luci di emergenza, nell'apertura del bagagliaio o nel funzionamento della radio, ma raramente avrà difficoltà a capire come guidare un'auto a noleggio.

L'obiettivo dei migliori team API è ottenere questo livello di progettazione "pronto all'uso": API il cui utilizzo non deve essere spiegato a chi è esperto.

Semplicità

La semplicità della progettazione delle API dipende dal contesto. Una progettazione può essere semplice per un esempio di utilizzo, ma molto complessa per un altro. Ecco perché è necessario bilanciare la granularità dei metodi di progettazione di API. La semplicità può essere ottenuta riflettendo su vari livelli, tra cui:

• Formato dei dati. Supporto di XML, JSON, formati proprietari o una combinazione di questi.
• Struttura del metodo. I metodi possono essere estremamente generici restituendo un ampio set di dati o molto specifici per rispondere a richieste mirate. Inoltre, i metodi vengono generalmente chiamati in una determinata sequenza per ottenere determinati esempi di utilizzo.
• Modello di dati. Il modello di dati sottostante può essere molto simile o molto diverso rispetto a quello effettivamente esposto tramite l'API, influendo sull'utilizzabilità e sulla manutenibilità.
• Autenticazione. Meccanismi di autenticazione diversi hanno punti di forza e di debolezza diversi. Il più adatto dipende dal contesto.
• Policy di utilizzo. I diritti e le quote degli sviluppatori devono essere facilmente comprensibili e utilizzabili.

Un'API semplice può non essere flessibile. Un'API creata per essere semplice corre il rischio di essere eccessivamente personalizzata e limitata a esempi di utilizzo molto specifici, senza lasciare spazio ad altri esempi di utilizzo.

Affinché un'API sia flessibile, per prima cosa occorre scoprire su quale spazio potenziale di operazioni si basa, inclusi i sistemi e i modelli di dati sottostanti, e capire quali sottoinsiemi di operazioni sono praticabili e preziosi. Per trovare il giusto equilibrio tra semplicità e flessibilità è utile:

• Cercare di esporre operazioni di dimensioni minime, che combinate possono coprire l'intero spazio.
• Identificare gli esempi di utilizzo più comuni e preziosi. Progettare un secondo livello di meta-operazioni che combinano diverse operazioni di dimensioni minime per servire questi esempi di utilizzo.

È possibile che il concetto di hypermedia, il motore dello stato dell'applicazione (HATEOAS), possa migliorare ulteriormente la flessibilità poiché consente modifiche del runtime nell'API e nelle operazioni del client. HATEOAS migliora la flessibilità semplificando il versioning e la documentazione. Tuttavia, durante la progettazione di API, occorre porsi un gran numero di domande.

La progettazione di API deve essere analizzata prendendo in considerazione le 5 domande seguenti:

1. Abbiamo progettato l'API in modo tale che possa supportare i nostri esempi di utilizzo? Dopo aver identificato gli esempi di utilizzo principali, è necessario progettare l'API in modo che sia in grado di supportarli. La flessibilità consente di escludere esempi di utilizzo che possono essere meno frequenti, ma che devono comunque essere supportati ai fini dell'innovazione.
2. Abbiamo scelto di essere RESTful solo per il gusto di esserlo? Le API RESTful sono di moda oggi come oggi, tuttavia non è indispensabile seguire questo trend. Alcuni scenari di utilizzo sono perfettamente adatti a questo tipo di API, altri preferiscono invece stili architetturali diversi, come GraphQL.
3. Abbiamo esposto il modello di dati senza pensare agli esempi di utilizzo? Un'API dovrebbe essere supportata da un livello che astrae dal modello di dati attuale. Di norma è meglio non avere un'API che accede direttamente al database, anche se esistono dei casi in cui è necessario.
4. Abbiamo programmato i nostri datacenter adattandoli alle aree geografiche più importanti? La progettazione di API deve prendere in considerazione anche elementi non funzionali come la latenza e la disponibilità. Assicurati di scegliere datacenter che si trovano in zone limitrofe a quelle in cui risiedono la maggior parte dei tuoi utenti.
5. Stiamo sincronizzando la progettazione di API con gli altri prodotti? Se l'API non è l'unico prodotto della tua azienda, assicurati che la sua progettazione sia coordinata con la progettazione degli altri prodotti. È possibile che tu decida di disaccoppiare completamente la progettazione dell'API dagli altri prodotti. In questo caso è comunque necessario comunicare con chiarezza questa decisione sia internamente che esternamente.

Una metrica che permette di migliorare la progettazione di API semplificandone l'adozione è il Time To First Hello World (TTFHW), una metrica che indica il tempo impiegato da uno sviluppatore per ottenere un prodotto almeno parzialmente valido utilizzando l'API. È un ottimo modo per metterti nei panni di uno sviluppatore che vuole usare la tua API per scoprire cosa serve per far funzionare qualcosa.

Al momento di definire l'inizio e la fine del parametro TTFHW, consigliamo di coprire il maggior numero possibile di aspetti del processo di coinvolgimento dello sviluppatore, ottimizzandolo in modo che sia il più rapido e pratico possibile.

La possibilità di procedere con rapidità sviluppa negli sviluppatori la convinzione che l'API è ben strutturata e che tutto funzionerà come previsto. Ritardando troppo il "momento del successo" si rischia di perdere gli sviluppatori.

Oltre al TTFHW, consigliamo un'altra metrica: Time to first profitable app (TTFPA). Questa metrica è più complicata perché la parola "profitable" (redditizia) cambia definizione a seconda dell'API e della strategia aziendale. Prendere in considerazione questo aspetto è utile perché forza a pensare agli aspetti correlati alle operazioni API nel quadro più ampio del programma API.

I 2 principi alla base dell'esperienza degli sviluppatori sono:

1. La progettazione di un prodotto o un servizio che offra un chiaro valore agli sviluppatori, risolvendo una criticità o fornendo un vantaggio. Il valore può essere monetario, ma anche di altro tipo. Può, ad esempio, aiutare ad accrescere la portata, la conoscenza del brand, la base clienti, le vendite indirette, la reputazione degli sviluppatori o la semplice gioia di usare un'ottima tecnologia che funziona.
2. Il prodotto deve essere facilmente accessibile. Ad esempio, grazie a un meccanismo di registrazione snello (oppure a nessun meccanismo di registrazione), all'accesso a funzionalità di test, a un'ottima documentazione e a un gran numero di codici sorgente gratuiti e semplici.

La maggior parte dei programmi API dovrebbe avere un programma per sviluppatori, a prescindere dal fatto che le API siano messe a disposizione del pubblico, dei partner o dei membri interni. Le disposizioni possono essere più o meno complesse a seconda dei destinatari.

Portale sviluppatori

Il portale degli sviluppatori è fondamentale perché è il punto di ingresso principale tramite il quale gli sviluppatori possono registrarsi, accedere e usare le tue API. L'accesso deve essere semplice e consentire agli sviluppatori di sfruttare immediatamente i vantaggi delle API.

TTFHW è la metrica migliore per misurarlo. Può essere utile semplificare il processo di registrazione, partendo dal presupposto che deve essere il più semplice e rapido possibile. Idealmente, gli sviluppatori dovrebbero essere in grado di invocare le API per esaminare il loro comportamento (richiesta e risposta) senza alcun bisogno di registrarsi. Contenuti supplementari come guide introduttive, documentazione di riferimento dell'API o codici sorgente aiutano, inoltre, a ridurre la curva di apprendimento.

Accelerazione grazie ai partner della community

Come provider di API ti stai muovendo in una community di partner e fornitori, che spesso hanno proprie reti e mezzi di comunicazione e distribuzione dei contenuti. Consigliamo di identificare le alleanze che possono aiutare ad accrescere l'adozione dell'API. Spesso alleanze di questo tipo possono essere trovate quando le API sono complementari e offrono valore agli sviluppatori quando vengono combinate.

Domande da porsi per valutare l'esperienza dello sviluppatore:

1. Come spieghiamo il valore dell'API nei primi cinque minuti? È opportuno sviluppare un "elevator pitch" sulla proposizione di valore dell'API che convinca gli sviluppatori.
2. Quali sono i nostri TTFHW e TTFPA e come li riduciamo? Il TTFHW end-to-end può aiutarti a migliorare il livello di utilizzabilità della tua API. Consigliamo di tenere a mente le metriche TTFHW/TTFPA ogni volta che un elemento viene aggiunto all'esperienza dello sviluppatore (come i portali) e ogni volta che viene apportata una modifica all'API.
3. Qual è il processo di onboarding per gli sviluppatori ed è il più semplice possibile? L'onboarding deve essere appropriato e in linea con gli esempi di utilizzo dell'API. Il livello di sicurezza deve ovviamente essere più alto per le API o l'accesso ai dati più sensibili, che con ogni probabilità richiedono accordi più formali. In tutti gli altri casi deve essere molto semplice e diretto per accelerare il successo dello sviluppatore (TTFHW).
4. Abbiamo fatto tutto ciò che potevamo per assicurarci che gli sviluppatori apprezzino l'API? Sì, se hai trovato la giusta proposta di valore e gli sviluppatori si registrano per usare la tua API. Il loro numero crescerà se li aiuterai ad avere successo.
5. Come offriamo supporto agli sviluppatori se si trovano ad affrontare dei problemi? In generale crediamo nell'approccio self service, che permette una notevole scalabilità. Una buona documentazione, le domande frequenti o i forum possono dare risposta a molte domande degli sviluppatori. Il self-service ha, però, dei limiti. In caso di domande più specifiche o, ad esempio, di problemi relativi alla fatturazione, deve essere presente un meccanismo di supporto.
6. La documentazione fornita è in grado di supportare l'innovazione? Quale supporto viene offerto agli sviluppatori che propongono utilizzi diversi dal solito o pensano di fare qualcosa di nuovo? Le grandi idee possono arrivare da ogni dove.