Le revisioni della progettazione API sono morte. Lunga vita alle recensioni sulla progettazione delle API!

Jul 28, 2023

Articoli sulla home page di InfoQ Le revisioni della progettazione API sono morte. Lunga vita alle recensioni sulla progettazione delle API!

22 maggio 2023 8 minuti di lettura

di

Jason Harmon

recensito da

Tommaso Betts

Nel corso della progettazione di API su larga scala, è necessario uno sforzo deliberato per creare coerenza. La differenza principale tra un insieme di API e qualcosa che sembra una vera piattaforma è la coerenza. In questo caso, coerenza significa semplicemente che se si utilizzano più API, fattori come convenzioni di denominazione, modelli di interazione come il paging e meccanismi di autenticazione sono standard su tutta la linea.

Tradizionalmente, i comitati di revisione traumatizzano gli sviluppatori API con scoperte che ritardano quando si ritiene che lo sviluppo sia completo. Quel che è peggio, la progettazione da parte di un comitato può prendere il sopravvento, bloccando il progresso o incoraggiando gli sviluppatori a trovare modi per eludere il processo ed evitare del tutto le sofferenze.

Per sbloccare veramente una piattaforma moderna, l’abilitazione attraverso la governance decentralizzata è un approccio molto più scalabile e coinvolgente. Ciò significa semplicemente che ogni dominio o area funzionale ha un esperto in materia che è stato formato sugli standard e sull'architettura generale per essere una guida competente per gli sviluppatori API.

Proteggi le identità. Servizi digitali sicuri. Consenti agli utenti un accesso scalabile e sicuro alle applicazioni Web e mobili. Inizia la prova gratuita.

Ancora più importante, concordare la progettazione dell'API prima che la maggior parte dello sviluppo sia completata può in gran parte evitare scoperte dell'ultimo minuto che mettono a repentaglio i tempi di consegna (spesso definito approccio "design-first"). L'utilizzo di un formato specifico come OpenAPI (lo standard de facto per le API HTTP/"REST") offre la possibilità di definire un'API prima di qualsiasi sviluppo, consentendo un allineamento e un'identificazione dei problemi molto più tempestivi.

Tenendo presente questo contesto, diamo un'occhiata più da vicino a come condurre revisioni della progettazione API e come sviluppare processi e preparare l'organizzazione per evitare tempistiche prolungate e mancanza di coinvolgimento degli sviluppatori.

Ecco alcuni prerequisiti chiave per garantire un processo regolare:

L'utilizzo delle API è un'esperienza molto distillata e, come tale, l'impatto del linguaggio è sproporzionatamente più elevato rispetto alla maggior parte degli altri ambiti di progettazione. Ogni membro del team può avere un modo leggermente diverso di definire e descrivere i vari termini, il che si manifesta con confusione e diminuzione della produttività per i team API.

Sebbene i portali e la documentazione API siano essenziali per un'ottima esperienza di sviluppo, le API ben progettate dovrebbero raccontare la maggior parte della storia senza doverci pensare troppo. Se i termini sono familiari al consumatore e i modelli di interazione sono evidenti, l’esperienza può essere rapida e indolore. La coerenza è la differenza principale nell'esperienza tra un gruppo di API e qualcosa che sembra un'unica piattaforma.

Quando stabilisci il tuo programma API e il processo di governance, inizia con un linguaggio condiviso. Anche se a prima vista può sembrare impossibile, definire un vocabolario/grammatica condiviso incentrato sul cliente per la tua piattaforma è essenziale e rappresenta un acceleratore generale per un'organizzazione. Molti termini possono avere significati diversi all'interno di un'azienda e, a peggiorare le cose, spesso si tratta di termini che i consumatori finali non riconoscerebbero nemmeno.

Fare questi compiti in anticipo evita conflitti sulla denominazione nel bel mezzo della progettazione delle API. Collabora in ciascun dominio con le parti interessate pertinenti per definire una terminologia condivisa e garantire ampia disponibilità e consapevolezza ai progettisti di API. E una volta stabilita la standardizzazione interna dei termini, non dimenticare di verificare se si adatta anche alle tue esigenze esterne. Usare il linguaggio del cliente e avere una visione incentrata sul cliente dello sviluppo dell'API aiuta i team a evitare di confondere i propri clienti con termini tecnici non familiari, quindi assicurati che ci sia sincronizzazione tra la tua comprensione interna e quella esterna.