Nel 2016 Google scrisse il documento “API Design Reviews at Scale” perchè aveva notato che un’enorme crescita nel numero di API da gestire stava comportando, per gli utenti, inconsistenze e problemi di usabilità. Per far fronte a tutto questo Google ha instituito un processo leggero, scalabile e distribuito per progettare e revisionare API.
Qualsiasi azienda può beneficiarsi dell’utilizzo di tale processo. Scopriamo di seguito 5 elementi di questo processo per migliorare la progettazione, la revisione della progettazione e l’usabilità delle tue API.
1 – Prospettive differenti rafforzano la revisione della progettazione delle API
La parte importante è che la progettazione delle API e la revisione non sono orientate al codice sorgente quindi non devi fare code review ma devi rivedere e progettare l’intuitività, la completezza e la consistenza delle API.
Un brain storming con gli stakeholder deve tradursi nella corretta comprensione del problema che l’API risolve sia dal punto di vista dell’utilizzatore diretto delle API, sia dell’utilizzatore finale della funzionalità, sia dei system integrator, sia del business.
Tale attività permette di distribuire l’impegno e renderlo efficace evitando perdite di tempo durante lo sviluppo ed eventuali insuccessi.
2 – La revisione inizia con la descrizione
Ne avevamo parlato nell’articolo “Gli 8 passi del ciclo di vita delle API“; occorre avere un comune linguaggio e descrivere correttamente il funzionamento delle API, per far questo è possibile utilizzare le OpenAPI Specification(OAS), le Postman Collection o anche le AsyncAPI.
A prescindere dalla scelta stilistica è fondamentale che questi “artifact” seguano uno standard coerente e consistente durante tutto il progetto, ciò al fine di utilizzarli sia come baseline per la documentazione delle API sia per l’implementazione di possibili automazioni tecnologiche. In pratica questi “artifact” diventano uno strumento live per l’accrescimento della conoscenza ed il testing.
3 – Definizione delle style guide
In enormi ecosistemi di API è indispensabile che tu definisca una comune style guide semplice da seguire, capire ed implementare. La style guide deve definire i processi su come si contribuisce allo sviluppo delle API, come si modifica e come evolve.
In pratica definire una style guide vuol dire fornire una serie di criteri determinati per ottenere i risultati richiesti dal business, tra questi criteri puoi trovare:
- metodi di autenticazione;
- convenzione sull’URI e sui relativi parametri;
- error handling;
- struttura e formato del payload;
- versioning;
- filtri degli input e degli output.
La style guide, insieme alla descrizione, ti permette anche di mitigare gli impatti del turnover del personale che nell’ambito dello sviluppo è sempre molto dinamico.
4 – Adattare la progettazione all’organizzazione
Sembra ovvio, ma occorre adattare la progettazione e la revisione delle API al tipo di organizzazione, alle funzioni delle API, ai casi di uso ed al motivo che ha portato alla necessità dello sviluppo.
Occorre mediare tra formalizzazione e agilità, pur sembrando un concetto semplice nella pratica è molto complesso ed occorre che tu faccia un’analisi puntuale dei costi e dei benefici dell’applicazione di determinate metodologie anche considerando gli aspetti di sicurezza relativi all’esposizione pubblica delle API.
5 – Feedback Management
Il miglioramento parte grazie alla collaborazione di tutti. Devi essere in grado di instaurare un processo di Feedback Management che ti consenta di ricevere segnalazioni da parte degli stakeholder.
Implementare test e verifiche automatiche ti può garantire il funzionamento di una API ma solo grazie ai feedback degli stakeholder puoi garantirne l’utilità.
Conclusioni
Evitare la revisione della progettazione ed il dar vita a cicli di miglioramento continuo vuol dire condannare il proprio ecocosistema di API ad inconsistenze e problemi. Ha affrontato già questo problema Google risolvendolo applicando processi di progettazione e di revisione della progettazione di API. Rendere operativi i suggerimenti sopra descritti richiede un costante impegno che viene ripagato nel tempo da qualità ed utilità delle API oltre a capacità di adattamento a scenari differenti anche nei team di sviluppo.
Glue Labs e le API
Abbiamo sviluppato ed integrato API in Web Service e Web Application, Middleware ed Embedded System. Grazie all’esperienza maturata in tantissimi settori, con numerosi Clienti e con un solido gruppo aziendale ti garantiamo le competenze per assisterti e supportarti per qualsiasi tuo progetto di sviluppo e nella realizzazione di API, anche Cloud Native, con garanzia 12 mesi da qualsiasi bug. Contattaci subito e senza impegno per maggiori informazioni.
