Non solo Microservizi: API, Prodotti, Piattaforme

Cosa intendiamo per API e che cosa sono?

Ogni volta che abbiamo a che fare con questo termine abbiamo in mente l’interfaccia utente per il testing con Swagger, piuttosto che una visione architetturale con ad esempio Amazon con il suo Gateway e le lambda function o più in generale una parte del mio programma.

Partiamo dalla definizione:

Una API, Application Programming Interface, è un intermediario software che consente a due applicazioni di dialogare tra loro. E’ un insieme di funzioni che consente di creare applicazioni che accedono alle funzionalità o ai dati di un’altra applicazione o servizio.

Oggi sono molto di più, ovvero sono una sorta di chiave di accesso ad un universo di concetti, strumenti, architetture ed in generale un ecosistema che raccoglie sforzi ed iniziative sempre più avanzate.

La vera svolta si ebbe nel 2002, grazie a Jeff Bezos e il suo mandato.

Jeff Bezos’ Big Mandate

Il Jeff Bezos’ Big Mandate del 2002, più volte poi riportato come Bezos moment per indicare tutti quei CEO che decidono di colpo di virare il business verso le API, ha avuto una valenza notevole per il business di Amazon.

Bezos si tolse il cappello dell’architect per indossarne uno da imprenditore, rendendosi conto dell’aumento dei costi dei team interni (mancanza di modi coerenti e ben gestiti di scambiare dati e capacità tra loro) e dal conseguente rallentamento delle pianificazioni di business.

Il Bezos Mandate ci ricorda i seguenti concetti cardine:

• Connubio tra Business e IT.
• Esposizione di dati e funzionalità.
• Fondarsi sulla comunicazione tramite interfacce e standardizzare le interazioni dei dati.
• Essere agnostici dal punto di visto delle Tecnologie usate.
• Progettare per “l’Esterno” come paradigma.

Per chi volesse approfondire sul Bezos Mandate, Stefano consiglia la lettura dell’articolo “Have you had your Bezos moment? What you can learn from Amazon” [1].

MVP e VPI

Secondo Deloitte Consulting le API sono passate dall’iniziale stato di tecnica di sviluppo ad un driver del modello di business. Le risorse principali di un’organizzazione possono essere riutilizzate, condivise, e monetizzate tramite API che possono estendere la portata dei servizi esistenti o fornire nuovi flussi di entrate. Dovrebbero essere gestite come un prodotto, costruito su una tecnica complessa improntata ad includere sistemi e dati legacy e di terze parti.

Avere un prodotto vuol dire quindi collocarlo sul mercato al momento giusto. Il contesto attuale che vede un mercato in continua e rapida evoluzione, le aziende si sono organizzate di conseguenza definendo un nuovo modello, l’MVP ovvero Minimum Viable Product. Brevemente un MVP è una versione di un prodotto con caratteristiche appena sufficienti per essere utilizzabile dai primi clienti che possono quindi fornire feedback per lo sviluppo futuro. Concentrarsi sul rilascio di un MVP significa che gli sviluppatori potenzialmente evitano il lavoro lungo e non necessario.

Le API quindi diventano prodotto, API as Product, e portano al concetto di VPI, ovvero Value Proposition Interface. Non sono più orientate all’applicativo ma vengono progettate insieme al business per offrire un prodotto che  esprima la Value Proposition aziendale.
Per ulteriori approfondimenti, Stefano ci consiglia il libro “API Product Management – Product Strategy and Execution for the Digital Economy” [2].

API Economy

Un prodotto collocato in un mercato determina un’economia. Con API Economy ci riferiamo al modo in cui questi software possono positivamente influire sulla redditività di un’azienda, consentendo di scalare rapidamente grazie all’accesso a dati e servizi di terze parti o trasformare i propri servizi e dati in una piattaforma che attrae partner su cui costruire nuovi servizi e che porta nuovi clienti.

Si distinguono due categorie:

• Micro-Economy: le API usate all’interno di aziende per capire le attività/centri di costo che funzionano meglio sfruttando i loro analitici.
• Macro-Economy: le API di terze parti che permettono alle aziende di comunicare con il resto del mondo.

Non possiamo inoltre non parlare di marketplace: con un’API sul mercato un’azienda può avere altri obiettivi oltre quello delle vendite. Altri obiettivi riguardano la ricerca di altri partner, fare innovazione, oppure trovare altre API con il quale integrarsi.

API Platform

Un provider di API è un’organizzazione che espone dati e/o funzionalità tramite un servizio consumabile a livello di codice con una o più API. Un’azienda passa da fornitore a piattaforma quando:

• Consentono l’accesso alla value-proposition fondamentale dell’organizzazione.
• Sono scalabili sia tecnicamente che per il business.
• Consentono ai consumatori di creare valore condiviso.
• Sono determinanti per garantire la posizione dell’organizzazione come leader di mercato.
• Sono viste dal top management come critiche per l’azienda

API Management

Un’organizzazione che fa delle API il suo business deve essere opportunamente strutturata, quindi avremo:

• API Registry: un vero e proprio inventario. Consente ai consumatori di consultare le API disponibili, ed è di aiuto all’azienda per la gestione del loro ciclo di vita (catalogazione delle versioni, promozione ecc.).
• API Gateway: il componente responsabile dell’esposizione e dell’organizzazione delle API ai diversi consumatori. Copre le seguenti aree fondamentali: Pubblicazione, Sicurezza, Standardizzazione, Controllo dell’Erogazione, Logging & Data Capture.
• Developer Portal: fornisce l’interfaccia umana alle API di un’organizzazione, fornisce un’esperienza utente di qualità (sia all’interno che per le terze parti), strumenti e risorse utili per la creazione di applicazioni che utilizzano le API. Inoltre, il portale fornisce le strutture agli sviluppatori per gestire il loro coinvolgimento con l’organizzazione (documentazione, notifiche, metriche).

Data l’importanza del tema, Stefano consiglia la lettura di alcuni libri interessanti [3] [4] [5].

API vs Microservizi

Negli ultimi anni non abbiamo avuto solo il trend delle API bensì anche quello dei microservizi.

La recente proposizione dell’architettura a microservizi porta a fare un po’ di confusione, ovvero identificare API con il termine microservizi. Falso! La realtà è ben altra.

Una API è un contratto che fornisce la guida verso un consumatore di quelle API al fine di interagire con il servizio sottostante.
Un microservizio nasce da un approccio architetturale che separa porzioni o interi monoliti applicativi in servizi di ridotte dimensioni e auto-contenuti.

L’obiettivo di una API non è mostrare le capacità tecniche del microservizio ma esporre il suo valore aggiunto ed il migliore contratto per interfacciarsi con i clienti di cui deve soddisfare le richieste.

Da API Gateway a…

Dall’idea originaria dell’avere un unico strato di API, API Gateway, si è passati al concetto di Backend For Frontend (BFF) ovvero avere diversi rendering di una pagina (per mobile, per web ecc.) e usare stessi servizi ma erogandoli in maniera differente. Passare a BFF non è solo un passaggio a livello tecnologico ma anche organizzativo, come spiega Giulio Roggero in un suo speech sui Feature Teams e microservizi.

Una delle evoluzioni più interessanti dei BFF riguarda l’utilizzo di GraphQL [6], un linguaggio di interrogazione lato server per API in grado di fornire ai client unicamente i dati di cui hanno bisogno.

Un’altra evoluzione riguarda il Service Mesh, quindi mischiare servizi a livello di comunicazione.

Riprendendo il concetto di API come prodotto e conseguente assetto aziendale orientato ad esso, Stefano ci ha parlato di Microservice Design Canvas Editor [7], uno strumento completamente gratuito che permette di realizzare l’architettura di una API lavorando assieme ad un esperto di dominio, per fissare quelle che sono le caratteristiche e funzionalità principali che dovrà avere.

Tanto altro ci sarebbe da dire sui microservizi e le API, Stefano per questo motivo ci suggerisce alcune risorse interessanti [8] [9] [10].

Ciclo di vita di una API

La definizione di un ciclo di vita delle API segue la stessa visione di un prodotto portando ad un’evoluzione continua al fine di adeguare e accrescere il marketplace e la value proposition aziendale.

Rimanendo nell’ambito delle API REST, Stefano ci parla del supporto che l’HTTP fornisce al ciclo di vita.

Che succede quando un prodotto è in fase di declino?

La dismissione di una API dev’essere preceduta da un periodo in cui la stessa viene notificata agli utilizzatori come Deprecated. L’azione di Deprecation è attuabile:

• su canali email, rss (syndication), chat per la notifica ad operatori umani
• grazie ad apposito HTTP Header in termini di REST API

Alcuni esempi:

• Deprecato nel passato: Deprecation: Sun, 11 Nov 2018 23:59:59 GMT
• Deprecato nel futuro: Deprecation: Sun, 20 Oct 2022 23:59:59 GMT
• Definitivamente deprecato: Deprecation: true

Quando il prodotto deve essere ritirato, grazie all’ header HTTP Sunset, ci permette di avvisare i client. La specifica di sunsetting è abbinabile a quella di deprecation, e deve essere successivo o lo stesso di quello presente nell’header di deprecation. Ad esempio:

Deprecation: Sun, 11 Nov 2018 23:59:59 GMT
Sunset: Wed, 11 Nov 2020 23:59:59 GMT

HTTP Support – Gestione degli errori e la specifica RFC 7807

Fino ai primi anni 2000 era abitudine gestire i codici di errore con uno status code 200 e al suo interno tante, troppe informazioni. Le evoluzioni delle API hanno reso necessario avere una semantica più ricca. La conseguenza è stata il proliferare
di soluzioni e formati per rappresentare le condizioni di errore nei vari ecosistemi di API delle Internet Companies.

Con il tempo è stata introdotta una specifica per la gestione degli errori, ovvero Problem Details for HTTP APIs [11] più comunemente conosciuta come RFC 7807, che si pone come standard capace di accogliere le differenti esigenze di gestione degli errori nell’ambito delle API:

• Flessibilità di formato grazie al supporto di differenti MIME Type nell’ambito della content negotiation HTTP.
• Supporto ad informazioni aggiuntive.
• Estendibilità delle informazioni ospitate.
• Supporto ad errori multipli sulla stessa risposta.
• Costruito su alcune considerazioni di sicurezza.

La specifica supporta principalmente due tipologie di Content Type previsti come standard IANA:

• application/problem+json
• application/problem+xml

Il formato prevede i seguenti campi:

• Type: (obbligatorio) un URI che identifica il tipo di errore. Il caricamento dell’URI in un browser dovrebbe portare alla documentazione dell’errore, ma non è strettamente necessario. Questo campo può essere utilizzato per riconoscere le classi di errore
• Title: un breve riassunto, in formato leggibile dall’utente, dell’errore. I client devono usare il Type come metodo principale per riconoscere i tipi di errore.
• Detail: spiegazione estesa e human-readable dell’errore.
• Status: il codice HTTP dello stato originario dell’errore.
• Instance: un URI che identifica questa specifica istanza di errore. Questo può fungere da ID per questa occorrenza dell’errore e/o un collegamento a maggiori dettagli sull’errore specifico.

HTTP Support – Gestione dei warning

La gestione degli errori non può coprire le situazioni dove un’esecuzione positiva della API implica comunque delle conseguenze negative o di cui il client deve essere avvisato.
La specifica [12] fornisce un pattern per rappresentare il concetto di warning nelle HTTP API e offre la possibilità di un formato unico in cui è racchiuso il warning grazie ad una rappresentazione JSON.

La specifica prevede uno specifico Header (Content-Warning) per indicare la presenza di un warning nel contesto della data risposta, offrendo in questo un’unica modalità espressa dal valore standard: embedded-warning.

HTTP Support – Versioning

Scegliere la politica di versionamento di una API può sembrare banale ma in realtà nasconde diverse difficoltà dato che differenti sono le conseguenze rispetto alla strategia scelta.

Sono utilizzabili tre differenti approcci:

• URI Versioning, ad esempio http://host/v1/users
• Query String Versioning, ad esempio http://host/users?api-version=1
• Header/Media Versioning, ad esempio Accept: application/vnd.myname.v1+json

Avere un indicatore di versione diventa necessario specie in ambienti basati su container ma non necessariamente sono da definirsi nelle API dato che è possibile affidarsi ad API Registry e alle versioni, generalmente derivanti dal Semantic Versioning, relativo a sorgenti o specifiche sottese alle API.

Queste idee sono state messe in discussione di recente, perché diverse applicazioni vedono le REST API combinarsi con interfacce. Viene considerato a volte molto più pragmatico evitare il versionamento, così differenti aziende tra cui Badoo e ING, hanno sperimentato soluzioni alternative quali il Continuous Versioning, con evidenti richiami al mondo DevOps.

A conclusione di questa parte sulle REST API, Stefano ci lascia tre libri che trattato la tematica anche da un punto di vista dell’usabilità [13] [14] [15].

Open Source Licensing

Le API rientrano, nostro malgrado, in un discorso relativo ad aspetti legali. Dopo l’avvento dei Cloud Provider come Amazon, Azure e altri, ci si è resi conto che le attuali licenze non fossero sufficienti a supportare i nuovi business introdotti dal mondo cloud.

Molti prodotti open source sono stati utliizzati senza rispettare il copyleft, ovvero ricondividere i sorgenti degli elementi utilizzati. Esempi di punta sono stati Redis’Source Available License (RSAL), la Server Side Public License (SSPL) di MongoDB, la Cockroach Community License (CCL) o le licenze a cui è stata aggiunta la clausola Commons.

E’ importante quindi dare importanza al licensing, ecco perché dal 2013 sono partiti diversi studi per rispondere alla domanda “Se voglio contribuire alla community delle API, quale licenza devo utilizzare?”

Stefano riporta una slide interessante presa dal video Comparing Open-Source Software Licenses:

Si è arrivati alla conclusione che forse è meglio mantenere in casa il proprio materiale software e monetizzare, in termini di API o marketplace, per riuscire ad avere una maggiore diffusione. Il tutto a discapito del guadagno, ma almeno si rende sostenibile il modello di sviluppo software open.

Lo sforzo di alcune software house svedesi, in collaborazione con dei legali del governo svedese, hanno portato alla realizzazione di un servizio online, SWEDISH API LICENSE, che permette la realizzazione di licenze open tramite clausole componibili.

Conclusioni

C’è altro di cui parlare relativamente alle REST API?

Eccome se ce ne sarebbe, Stefano prima di salutarci ci accenna al Richardson Maturity Model o l’API Security Maturity Model, ma il tempo a sua disposizione è terminato.

Ringrazio Stefano a nome di Intré ed XPUG Bergamo per il tempo che ci ha concesso, e a voi cari lettori posso solo che salutarvi dandovi l’appuntamento per il resoconto di un nuovo webinar, magari organizzato dal vivo.

Riferimenti

1. Have you had your Bezos moment? What you can learn from Amazon
2. Libro “API Product Management – Product Strategy and Execution for the Digital Economy”
3. Continuous API Management | Amazon
4. Enterprise API Management | Amazon
5. API Management | Amazon
6. GraphQL
7. MDC Editor
8. Securing Microservice APIs | O’Reilly
9. Microservice Architecture | Amazon
10. Monolith to Microservices | Amazon
11. Problem Details for HTTP APIs
12. Communicating Warning Information in HTTP APIs
13. REST API Design Rulebook | Amazon
14. The Design of Web API’s | Manning
15. Hands-On RESTful API Design Patterns and Best Practices | Amazon