M365Con 2027 – conferenza online gratuita · 11–22 Jan 2027 · 120 sessions m365con.net

API-first architecture

Concetto

L'architettura API-first progetta le funzionalità di business come API stabili e richiamabili prima di qualsiasi interfaccia utente, in modo che interfacce utente, motori di workflow e agenti AI utilizzino le stesse operazioni.

✦ CONCETTOAPI-first architectureM365.FM
Grafica del titolo: architettura API-first (Concetto)

Trattati anche

L’episodio su API-first architecture parla anche di Computer-Using Agent (CUA), Foundry Agent Service, Service account, Agent observability, Microsoft Agent 365 e Software as a service (SaaS).

Descrizione

L'architettura API-first è un approccio di progettazione in cui le funzionalità di business vengono definite come API stabili e richiamabili prima che venga costruita qualsiasi interfaccia utente. Le stesse operazioni vengono poi utilizzate da interfacce utente, motori di workflow e agenti AI, invece di far sì che ciascun client raggiunga la logica attraverso un percorso proprio. In questo modello l'API è considerata una decisione di prodotto e non un sottoprodotto del codice, perché sviluppatori esterni, partner e agenti AI dovrebbero poterci costruire sopra.

Un elemento centrale dello sviluppo API-first è il contratto dell'API. Secondo l'articolo Microsoft sullo sviluppo API-first, il contratto descrive gli endpoint, i dati di richiesta e di risposta e gli errori attesi, ed è scritto prima dell'implementazione o dell'interfaccia utente. Il contratto è di solito espresso in un formato leggibile dalle macchine, più spesso OpenAPI. Una volta approvato il contratto, i team backend lo implementano, mentre i team front-end e mobile sviluppano a partire dai mock generati da esso. Documentazione, SDK e test possono essere generati dalla stessa fonte, il che mantiene coerenti tra loro i diversi artefatti.

L'approccio viene comunemente contrapposto allo sviluppo code-first. In un'impostazione code-first l'API emerge dal codice esistente, il che può far trapelare dettagli interni nell'interfaccia pubblica. L'API-first inverte quest'ordine: l'interfaccia viene progettata deliberatamente e il codice viene scritto per soddisfarla. La pagina Microsoft segnala anche dei compromessi. Il lavoro contract-first aggiunge uno sforzo di revisione preliminare, mentre un approccio code-first può essere ragionevole per uno strumento interno iniziale in cui i consumatori sono pochi e ci si aspetta che l'interfaccia cambi rapidamente. La pagina è un articolo del fornitore e contiene contenuti specifici di Azure.

Il versionamento è una parte significativa della pratica. Poiché i consumatori dipendono dal contratto, il versionamento viene trattato come un accordo con loro: le modifiche additive sono considerate sicure all'interno di una versione, mentre le modifiche incompatibili richiedono una nuova versione. La dismissione delle versioni precedenti può essere segnalata con un header Sunset, offrendo ai consumatori un percorso definito per migrare anziché un'interruzione improvvisa.

Una ulteriore caratteristica è che un'unica API può servire client web, mobile, partner e agenti dietro un singolo gateway. L'autenticazione e la limitazione della frequenza si applicano quindi uniformemente a tutti i chiamanti, e la logica di business non viene duplicata tra canali separati. Questo è il motivo per cui il concetto è rilevante per i sistemi guidati da agenti, dove gli agenti software hanno bisogno di operazioni prevedibili e documentate da invocare.

L'episodio di M365.FM "Computer-Using Agents: How CUA Could Transform SaaS" collega l'architettura API-first agli ecosistemi di agenti. L'episodio afferma che gli ecosistemi di agenti prosperano quando si adotta un'architettura API-first, perché consente di collegare agenti, sistemi e workflow con chiarezza e prevedibilità. Descrive le API stabili come la spina dorsale dei sistemi intelligenti e afferma che gli sviluppatori possono farvi affidamento per innovare senza timore di interruzioni. Indica inoltre l'estensibilità come vantaggio, che aiuta le organizzazioni ad adattarsi a requisiti in evoluzione. In questa prospettiva, la progettazione API-first si affianca all'investimento in workflow che gli agenti possono creare, automatizzare e scalare.

Le decisioni tipiche relative all'architettura API-first riguardano quali funzionalità esporre come API, quale formato di contratto utilizzare, come versionare e dismettere le modifiche e dove collocare un gateway per l'autenticazione condivisa e la limitazione della frequenza. I team valutano anche il costo iniziale della revisione del contratto rispetto ai vantaggi dello sviluppo parallelo di front-end e backend e della documentazione e dei test generati.

Panoramica compilata con l'AI dagli episodi di M365.FM e dai dati di questa pagina. Puoi migliorarla con il pulsante di modifica qui sotto.

TipoConcetto
TipoArchitecture

Domande frequenti

Le domande contrassegnate con AI sono state scritte con l'AI a partire dai fatti riportati in questa pagina.

Che cosa significa architettura API-first? (AI)

Significa progettare le funzionalità di business come API stabili e richiamabili prima di qualsiasi interfaccia utente, in modo che interfacce utente, motori di workflow e agenti AI utilizzino tutti le stesse operazioni. Il contratto dell'API viene definito per primo e l'implementazione segue.

In che modo l'API-first differisce dal code-first? (AI)

Nello sviluppo code-first l'API è un sottoprodotto del codice esistente e può far trapelare dettagli interni. Nello sviluppo API-first il contratto, di solito scritto in OpenAPI, viene progettato e approvato prima che vengano costruiti l'implementazione o l'interfaccia utente.

Perché l'API-first è rilevante per gli agenti AI? (AI)

L'episodio "Computer-Using Agents: How CUA Could Transform SaaS" afferma che le API stabili costituiscono la spina dorsale dei sistemi intelligenti e permettono a agenti, sistemi e workflow di collegarsi con chiarezza e prevedibilità. Un'unica API dietro un gateway può inoltre servire i client agente insieme ai client web e mobile.

Glossario

Community wiki

Short info above, community knowledge below: add practical tips, examples or corrections. New contributions are reviewed first; trusted members publish directly.

Esperti e aziende per questo argomento

Nessuno ha ancora indicato questo argomento. Aggiungilo al tuo profilo.

Mantenuto da Mirko Peters (Microsoft MVP) · Ultimo aggiornamento: