# REL03-BP03 Fornire contratti di assistenza per API
I contratti di assistenza sono accordi documentati tra API produttori e consumatori definiti in una definizione leggibile da una macchinaAPI. Una strategia di controllo delle versioni contrattuali consente ai consumatori di continuare a utilizzare le applicazioni esistenti API e di migrare le proprie applicazioni a una versione più recente quando sono pronte. API L'implementazione da parte del produttore può avvenire in qualsiasi momento, purché il processo sia conforme al contratto. I team di assistenza possono utilizzare lo stack tecnologico di loro scelta per soddisfare il contratto. API
**Risultato desiderato:** le applicazioni create con architetture orientate ai servizi o ai microservizi sono in grado di funzionare in modo indipendente pur avendo una dipendenza di runtime integrata. Le modifiche apportate a un API consumatore o a un produttore non interrompono la stabilità dell'intero sistema quando entrambe le parti seguono un contratto comune. API I componenti che comunicano tramite servizio APIs possono eseguire rilasci funzionali indipendenti, aggiornamenti alle dipendenze di runtime o eseguire il failover su un sito di disaster recovery (DR) con un impatto reciproco minimo o nullo. Inoltre, i servizi discreti sono in grado di scalare in modo indipendente assorbendo la richiesta di risorse senza che gli altri servizi debbano ridurre orizzontalmente di conseguenza.
**Anti-pattern comuni:**
+ Creazione di servizi APIs senza schemi fortemente tipizzati. Ciò comporta APIs che non può essere utilizzato per generare API associazioni e payload che non possono essere convalidati programmaticamente.
+ Non adottare una strategia di controllo delle versioni, che costringerebbe gli API utenti ad aggiornare e rilasciare o fallire quando i contratti di assistenza si evolvono.
+ 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 API contratti per sviluppare casi di test e API implementazioni fittizie per consentire test indipendenti dei componenti del servizio.
**Vantaggi derivanti dall'adozione di questa best practice:** i sistemi distribuiti composti da componenti che comunicano tramite contratti di API assistenza possono migliorare l'affidabilità. Gli sviluppatori possono individuare potenziali problemi nelle prime fasi del processo di sviluppo grazie al controllo del tipo durante la compilazione per verificare che le richieste e le risposte siano conformi al API contratto e che i campi obbligatori siano presenti. APIi contratti forniscono una chiara interfaccia di autodocumentazione APIs e forniscono una migliore interoperabilità tra diversi sistemi e linguaggi di programmazione.
**Livello di rischio associato se questa best practice non fosse adottata:** medio
## Guida all'implementazione
Dopo aver identificato i domini aziendali e determinato la segmentazione del carico di lavoro, puoi sviluppare il tuo servizio. APIs Innanzitutto, definisci contratti di assistenza leggibili automaticamente e poi implementa una strategia di controllo delle APIs versioni. API Quando sei pronto per integrare i servizi tramite protocolli comuni come REST GraphQL o eventi asincroni, puoi incorporare AWS servizi nella tua architettura per integrare i componenti con contratti fortemente tipizzati. API
**AWS APIservizi per contratti di assistenza**
Incorpora AWS servizi tra cui [Amazon API Gateway](https://aws.amazon.com/api-gateway/) e [Amazon EventBridge](https://aws.amazon.com/eventbridge/) nella tua architettura per utilizzare i contratti di API servizio nella tua applicazione. [AWS AppSync](https://aws.amazon.com/appsync/) Amazon API Gateway ti aiuta a integrarti con AWS servizi nativi diretti e altri servizi Web. APIGateway supporta le [APIspecifiche e il controllo delle versioni Open](https://github.com/OAI/OpenAPI-Specification). AWS AppSync è un endpoint [GraphQL](https://graphql.org/) gestito che puoi configurare definendo uno schema GraphQL per definire un'interfaccia di servizio per query, mutazioni e sottoscrizioni. Amazon EventBridge utilizza schemi di eventi per definire eventi e generare associazioni di codice per i tuoi eventi.
## Passaggi dell'implementazione
+ Innanzitutto, definisci un contratto per il tuo. API Un contratto esprimerà le capacità di un e API definirà oggetti di dati e campi fortemente tipizzati per l'APIinput e l'output.
+ Quando esegui la configurazione APIs in API Gateway, puoi importare ed esportare API le specifiche aperte per i tuoi endpoint.
+ [L'importazione di una API definizione aperta](https://docs.aws.amazon.com/apigateway/latest/developerguide/import-edge-optimized-api.html) semplifica la creazione della propria definizione API e può essere integrata con l' AWS infrastruttura come strumenti di codice come la e. [AWS Serverless Application Model[AWS Cloud Development Kit (AWS CDK)](https://aws.amazon.com/cdk/)](https://aws.amazon.com/serverless/sam/)
+ [L'esportazione di una API definizione](https://docs.aws.amazon.com/apigateway/latest/developerguide/api-gateway-export-api.html) semplifica l'integrazione con gli strumenti di API test e fornisce ai consumatori di servizi una specifica di integrazione.
+ Puoi definire e gestire GraphQL APIs AWS AppSync [definendo un file di schema GraphQL](https://docs.aws.amazon.com/appsync/latest/devguide/designing-your-schema.html) per generare l'interfaccia del contratto e semplificare l'interazione con REST modelli complessi, più tabelle di database o servizi legacy.
+ [AWS Amplify](https://aws.amazon.com/amplify/)i progetti integrati AWS AppSync generano file di JavaScript query fortemente tipizzati da utilizzare nella tua applicazione e una libreria client AWS AppSync GraphQL per le tabelle Amazon [DynamoDB](https://aws.amazon.com/dynamodb/).
+ Quando utilizzi gli eventi di servizio di Amazon EventBridge, gli eventi aderiscono a schemi già esistenti nel registro degli schemi o definiti con Open API Spec. Con uno schema definito nel registro, puoi anche generare associazioni client dal contratto dello schema per integrare il codice con gli eventi.
+ Estendere o modificare il tuo. API L'estensione di un API è un'opzione più semplice quando si aggiungono campi che possono essere configurati con campi opzionali o valori predefiniti per i campi obbligatori.
+ JSONi contratti basati su protocolli come REST GraphQL possono essere adatti per l'estensione del contratto.
+ XMLi contratti basati su protocolli, ad esempio, SOAP dovrebbero essere testati con i consumatori di servizi per determinare la fattibilità dell'estensione del contratto.
+ Quando si effettua il versionamento di unAPI, è consigliabile implementare il controllo delle versioni proxy, in cui viene utilizzata una facciata per supportare le versioni in modo che la logica possa essere mantenuta in un'unica base di codice.
+ Con API Gateway puoi utilizzare le [mappature di richiesta e risposta](https://docs.aws.amazon.com/apigateway/latest/developerguide/request-response-data-mappings.html#transforming-request-response-body) per semplificare l'assorbimento delle modifiche contrattuali, stabilendo una facciata per fornire valori predefiniti per nuovi campi o per eliminare i campi rimossi da una richiesta o risposta. Con questo approccio, il servizio sottostante può avere un'unica base di codice.
## Risorse
**Best practice correlate:**
+ [REL03-BP01 Scegli come segmentare il tuo carico di lavoro](rel_service_architecture_monolith_soa_microservice.md)
+ [REL03-BP02 Creazione di servizi focalizzati su domini e funzionalità aziendali specifici](rel_service_architecture_business_domains.md)
+ [REL04-BP02 Implementare dipendenze liberamente accoppiate](rel_prevent_interaction_failure_loosely_coupled_system.md)
+ [REL05-BP03 Controlla e limita le chiamate di nuovo tentativo](rel_mitigate_interaction_failure_limit_retries.md)
+ [REL05-BP05 Imposta i timeout dei client](rel_mitigate_interaction_failure_client_timeouts.md)
**Documenti correlati:**
+ [Che cos'è una API (interfaccia di programmazione delle applicazioni)?](https://aws.amazon.com/what-is/api/)
+ [Implementazione di microservizi su AWS](https://docs.aws.amazon.com/whitepapers/latest/microservices-on-aws/microservices-on-aws.html)
+ [ Microservice Trade-Offs ](https://martinfowler.com/articles/microservice-trade-offs.html)
+ [ Microservices - a definition of this new architectural term ](https://www.martinfowler.com/articles/microservices.html)
+ [Microservizi attivi AWS](https://aws.amazon.com/microservices/)
+ [Utilizzo delle estensioni API Gateway to Open API](https://docs.aws.amazon.com/apigateway/latest/developerguide/api-gateway-swagger-extensions.html)
+ [Apri API - Specificazione](https://github.com/OAI/OpenAPI-Specification)
+ [ GraphQL: schemi e tipi ](https://graphql.org/learn/schema/)
+ [Associazioni di EventBridge codice Amazon](https://docs.aws.amazon.com/eventbridge/latest/userguide/eb-schema-code-bindings.html)
**Esempi correlati:**
+ [Amazon API Gateway: configurazione di un REST API utilizzo di Open API](https://docs.aws.amazon.com/apigateway/latest/developerguide/api-gateway-import-api.html)
+ [Da Amazon API Gateway all'applicazione Amazon CRUD DynamoDB tramite Open API](https://serverlessland.com/patterns/apigw-ddb-openapi-crud?ref=search)
+ [Modelli di integrazione delle applicazioni moderni nell'era senza server: API Gateway Service Integration](https://catalog.us-east-1.prod.workshops.aws/workshops/be7e1ee7-b91f-493d-93b0-8f7c5b002479/en-US/labs/asynchronous-request-response-poll/api-gateway-service-integration)
+ [Implementazione del controllo delle versioni API Gateway basato su header con Amazon CloudFront](https://aws.amazon.com/blogs/compute/implementing-header-based-api-gateway-versioning-with-amazon-cloudfront/)
+ [AWS AppSync: Building a client application ](https://docs.aws.amazon.com/appsync/latest/devguide/building-a-client-app.html#aws-appsync-building-a-client-app)
**Video correlati:**
+ [Utilizzo di Open API in AWS SAM per gestire Gateway API](https://www.youtube.com/watch?v=fet3bh0QA80)
**Strumenti correlati:**
+ [Amazon API Gateway](https://aws.amazon.com/api-gateway/)
+ [AWS AppSync](https://aws.amazon.com/appsync/)
+ [Amazon EventBridge](https://aws.amazon.com/eventbridge/)