REL03-BP03 Fornitura di contratti di servizio per API
I contratti di assistenza sono accordi documentati tra produttori di API e utenti definiti in una definizione di API leggibile dal computer. Una strategia di controllo delle versioni dei contratti consente agli utenti di continuare a utilizzare l'API esistente e migrare le applicazioni a un'API più recente quando sono pronte. L'implementazione da parte del produttore può avvenire in qualsiasi momento, purché il processo sia conforme al contratto. Il team dei servizi può utilizzare lo stack tecnologico scelto per soddisfare il contratto API.
Risultato desiderato:
Anti-pattern comuni: Le applicazioni realizzate con architetture orientate ai servizi o con architetture di microservizi sono in grado di funzionare in modo indipendente pur essendo caratterizzate da una dipendenza dal runtime integrata. Le modifiche apportate a un utente o produttore di API non pregiudicano la stabilità dell'intero sistema quando entrambe le parti sono conformi a un contratto API comune. I componenti che comunicano tramite le API di servizio possono eseguire release funzionali indipendenti, aggiornamenti delle dipendenze di runtime o eseguire il failover su un sito di ripristino di emergenza con un impatto reciproco minimo o nullo. Inoltre, i servizi discreti sono in grado di eseguire il dimensionamento in modo indipendente assorbendo la richiesta di risorse senza che gli altri servizi debbano ridimensionarsi di conseguenza.
-
Creazione di API di servizio senza schemi fortemente tipizzati. Ciò si traduce in API che non possono essere utilizzate per generare collegamenti API e payload che non possono essere convalidati a livello di codice.
-
Non adottare una strategia di controllo delle versioni, che costringa gli utenti delle API all'aggiornamento e rilascio o all'esito negativo dell'operazione al variare dei contratti di servizio.
-
Messaggi di errore che divulgano dettagli sull'implementazione del servizio sottostante anziché descrivere errori di integrazione nel contesto e nel linguaggio del dominio.
-
Non utilizzare contratti API per sviluppare casi di test e simulare implementazioni API per consentire test indipendenti dei componenti del servizio.
Vantaggi dell'adozione di questa best practice: i sistemi distribuiti composti da componenti che comunicano tramite contratti di servizio API possono migliorare l'affidabilità. Gli sviluppatori possono rilevare potenziali problemi nelle prime fasi del processo di sviluppo con il controllo del tipo durante la compilazione per verificare che le richieste e le risposte siano conformi al contratto API e che i campi obbligatori siano presenti. I contratti API forniscono una chiara interfaccia di documentazione automatica per le API e garantiscono una migliore interoperabilità tra sistemi e linguaggi di programmazione diversi.
Livello di rischio associato se questa best practice non fosse adottata: medio
Guida all'implementazione
Dopo aver individuato i domini aziendali e determinato la segmentazione del carico di lavoro, puoi sviluppare le API dei tuoi servizi. Innanzitutto, definisci contratti di servizio leggibili dal computer per le API, quindi implementa una strategia di controllo delle versioni delle API. Quando sei pronto per integrare servizi su protocolli comuni come REST, GraphQL o eventi asincroni, puoi incorporare servizi AWS nell'architettura per integrare i componenti con contratti API fortemente tipizzati.
I servizi AWS per i contratti API di servizio
includono servizi AWS come Amazon API Gateway
Passaggi dell'implementazione
-
Definisci innanzitutto un contratto per la tua API. Un contratto esprimerà le capacità di un'API e definirà oggetti e campi di dati fortemente tipizzati per l'input e l'output dell'API.
-
Quando configuri le API in API Gateway, puoi importare ed esportare le specifiche OpenAPI per gli endpoint.
-
L'importazione di una definizione OpenAPI semplifica la creazione dell'API e può essere integrata con l'infrastruttura AWS come strumenti di codice come AWS Serverless Application Model
e AWS Cloud Development Kit (AWS CDK) . -
L'esportazione di una definizione API semplifica l'integrazione con gli strumenti di test delle API e fornisce agli utenti di servizi una specifica di integrazione.
-
-
Puoi definire e gestire le API GraphQL con AWS AppSync mediante la definizione di un file di schema GraphQL per generare l'interfaccia del contratto e semplificare l'interazione con modelli REST complessi, più tabelle di database o servizi legacy.
-
I progetti AWS Amplify
integrati con AWS AppSync generano file di query JavaScript fortemente tipizzati da utilizzare nell'applicazione, nonché una libreria client GraphQL AWS AppSync per le tabelle Amazon DynamoDB . -
Quando si utilizzano eventi di servizio da Amazon EventBridge, gli eventi sono conformi agli schemi già esistenti nel registro degli schemi o definiti con la specifica OpenAPI. Con uno schema definito nel registro, puoi anche generare associazioni client dal contratto dello schema per integrare il codice con gli eventi.
-
Estensione o definizione della versione dell'API. L'estensione di un'API è un'opzione più semplice quando si aggiungono campi che possono essere configurati con campi facoltativi o valori predefiniti per i campi obbligatori.
-
I contratti basati su JSON per protocolli come REST e GraphQL possono essere adatti per l'estensione del contratto.
-
I contratti basati su XML per protocolli come SOAP devono essere testati con gli utenti dei servizi per determinare se l'estensione del contratto è possibile.
-
-
Quando esegui il controllo delle versioni di un'API, valuta la possibilità di implementare il controllo delle versioni proxy laddove un lato viene usato per supportare le versioni in modo che la logica possa essere gestita in un'unica base di codice.
-
Con API Gateway puoi usare mappature di richieste e risposte per semplificare l'inclusione delle modifiche del contratto stabilendo un lato per fornire valori predefiniti per i nuovi campi o per eliminare i campi rimossi da una richiesta o una risposta. Con questo approccio, il servizio sottostante può avere un'unica base di codice.
-
Risorse
Best practice correlate:
Documenti correlati:
Esempi correlati:
Video correlati:
Strumenti correlati:
