# REL03-BP03 Fornecer contratos de serviço por API
Os contratos de serviço são acordos documentados entre produtores e consumidores de API estabelecidos em uma definição de API legível por máquina. Uma estratégia de versionamento de contrato permite que os consumidores continuem usando a API existente e migrem suas aplicações para uma API mais recente quando estiverem prontos. A implantação do produtor pode acontecer a qualquer momento, desde que o contrato seja cumprido. A equipe de serviços pode usar a pilha de tecnologia de sua preferência para cumprir o contrato de API.
**Resultado desejado:** as aplicações criadas com arquiteturas orientadas a serviços ou de microsserviços podem operar de forma independente e, ao mesmo tempo, ter uma dependência de tempo de execução integrada. As alterações implantadas em um consumidor ou produtor de API não interrompem a estabilidade do sistema geral quando os dois lados seguem um contrato de API comum. Os componentes que se comunicam por meio de APIs de serviço podem realizar lançamentos funcionais independentes, atualizações para dependências de runtime ou fazer failover em um site de recuperação de desastres (DR) com pouco ou nenhum impacto entre si. Além disso, serviços diferentes são capazes de escalar de forma independente a absorção da demanda de recursos sem exigir que outros serviços escalem simultaneamente.
**Práticas comuns que devem ser evitadas:**
+ Criação de APIs de serviço sem esquemas altamente tipificados. Isso resulta em APIs que não podem ser usadas para gerar vinculações de API e payloads que não podem ser validadas de maneira programática.
+ Não adotar uma estratégia de versionamento, o que força os consumidores de API a atualizarem e lançarem ou falharem com a evolução dos contratos de serviço.
+ Mensagens de erro que vazam detalhes da implementação do serviço subjacente em vez de descreverem falhas de integração no contexto e no idioma do domínio.
+ Não usar contratos de API para desenvolver casos de teste e simular implementações de API para permitir testes independentes dos componentes do serviço.
**Benefícios de implementar esta prática recomendada:** sistemas distribuídos compostos por componentes que se comunicam por meio de contratos de serviço de API podem aumentar a confiabilidade. Os desenvolvedores podem detectar possíveis problemas no início do processo de desenvolvimento com a verificação de tipo durante a compilação a fim de verificar se as solicitações e as respostas seguem o contrato da API e se os campos obrigatórios estão presentes. Os contratos de API oferecem uma interface clara de autodocumentação de APIs e oferecem melhor interoperabilidade entre diferentes sistemas e linguagens de programação.
**Nível de risco exposto se esta prática recomendada não for estabelecida:** Médio
## Orientação para implementação
Depois de identificar os domínios de negócios e determinar a segmentação da workload, você pode desenvolver suas APIs de serviço. Primeiro, defina contratos de serviço legíveis por máquina para APIs e, depois, implemente uma estratégia de versionamento de API. Quando estiver pronto para integrar serviços em protocolos comuns, como REST, GraphQL ou eventos assíncronos, você poderá incorporar serviços da AWS à sua arquitetura para integrar seus componentes com contratos de API altamente tipificados.
**Serviços da AWS para contratos de API de serviços**
Incorpore serviços da AWS, incluindo o [Amazon API Gateway](https://aws.amazon.com/api-gateway/), o [AWS AppSync](https://aws.amazon.com/appsync/) e o [Amazon EventBridge](https://aws.amazon.com/eventbridge/), em sua arquitetura para usar contratos de serviços de API em sua aplicação. O Amazon API Gateway ajuda você a se integrar diretamente com serviços da AWS nativos e outros serviços Web. O API Gateway é compatível com a [especificação da OpenAPI](https://github.com/OAI/OpenAPI-Specification) e versionamento. O AWS AppSync é um endpoint gerenciado do [GraphQL](https://graphql.org/) que você configura definindo um esquema do GraphQL para definir uma interface de serviço para consultas, mutações e assinaturas. O Amazon EventBridge usa esquemas de eventos para definir eventos e gerar vinculações de código para seus eventos.
## Etapas de implementação
+ Primeiro, defina um contrato para sua API. Um contrato expressará os recursos de uma API, bem como definirá objetos e campos de dados altamente tipificados para a entrada e a saída da API.
+ Ao configurar APIs no API Gateway, você pode importar e exportar especificações da OpenAPI para seus endpoints.
+ [Importar uma definição da OpenAPI](https://docs.aws.amazon.com/apigateway/latest/developerguide/import-edge-optimized-api.html) simplifica a criação de sua API e pode ser integrada a ferramentas de infraestrutura como código da AWS, como o [AWS Serverless Application Model](https://aws.amazon.com/serverless/sam/) e o [AWS Cloud Development Kit (AWS CDK)](https://aws.amazon.com/cdk/).
+ [Exportar uma definição de API](https://docs.aws.amazon.com/apigateway/latest/developerguide/api-gateway-export-api.html) simplifica a integração a ferramentas de teste de API e oferece ao consumidor de serviços uma especificação de integração.
+ Você pode definir e gerenciar as APIs do GraphQL com o AWS AppSync [definindo um arquivo de esquema do GraphQL](https://docs.aws.amazon.com/appsync/latest/devguide/designing-your-schema.html) para gerar sua interface de contrato e simplificar a interação com modelos REST complexos, várias tabelas de banco de dados ou serviços legados.
+ Os projetos do [AWS Amplify](https://aws.amazon.com/amplify/) integrados ao AWS AppSync geram arquivos de consulta JavaScript altamente tipificados para uso em sua aplicação, bem como uma biblioteca cliente do AWS AppSync GraphQL para tabelas do [Amazon DynamoDB](https://aws.amazon.com/dynamodb/).
+ Quando você consome eventos de serviço do Amazon EventBridge, eles seguem os esquemas já existentes no registro do esquema ou os definidos com a especificação da OpenAPI. Com um esquema definido no registro, também é possível gerar vinculações de cliente a partir do contrato de esquema para integrar seu código aos eventos.
+ Estender ou realizar o versionamento de sua API. Estender uma API é uma opção mais simples ao adicionar campos que podem ser configurados com campos opcionais ou valores padrão para campos obrigatórios.
+ Contratos baseados em JSON para protocolos, como REST e GraphQL, podem ser uma boa opção para a extensão do contrato.
+ Contratos baseados em XML para protocolos, como SOAP, devem ser testados com consumidores de serviços para determinar a viabilidade da extensão do contrato.
+ Ao realizar o versionamento de uma API, considere implementar o controle de versão por procuração em que uma fachada é usada para oferecer compatibilidade com versões para que a lógica possa ser mantida em uma única base de código.
+ Com o API Gateway, você pode usar [mapeamentos de solicitação e resposta](https://docs.aws.amazon.com/apigateway/latest/developerguide/request-response-data-mappings.html#transforming-request-response-body) para simplificar a absorção de alterações no contrato estabelecendo uma fachada para fornecer valores padrão para novos campos ou para retirar os campos removidos de uma solicitação ou resposta. Com essa abordagem, o serviço subjacente pode manter uma única base de código.
## Recursos
**Práticas recomendadas relacionadas:**
+ [REL03-BP01 Escolher como segmentar a workload](rel_service_architecture_monolith_soa_microservice.md)
+ [REL03-BP02 Criar serviços voltados para domínios e funcionalidades de negócios específicos](rel_service_architecture_business_domains.md)
+ [REL04-BP02 Implementar dependências com acoplamento fraco](rel_prevent_interaction_failure_loosely_coupled_system.md)
+ [REL05-BP03 Controlar e limitar chamadas de novas tentativas](rel_mitigate_interaction_failure_limit_retries.md)
+ [REL05-BP05 Definir tempos limite do cliente](rel_mitigate_interaction_failure_client_timeouts.md)
**Documentos relacionados:**
+ [O que é uma API (interface de programação de aplicações)?](https://aws.amazon.com/what-is/api/)
+ [Implementar microsserviços na AWS](https://docs.aws.amazon.com/whitepapers/latest/microservices-on-aws/microservices-on-aws.html)
+ [Compensações de microsserviços](https://martinfowler.com/articles/microservice-trade-offs.html)
+ [Microsserviços: uma definição desse novo termo de arquitetura](https://www.martinfowler.com/articles/microservices.html)
+ [Microsserviços na AWS](https://aws.amazon.com/microservices/)
+ [Trabalhar com extensões do API Gateway para OpenAPI](https://docs.aws.amazon.com/apigateway/latest/developerguide/api-gateway-swagger-extensions.html)
+ [Especificação da OpenAPI](https://github.com/OAI/OpenAPI-Specification)
+ [GraphQL: esquemas e tipos](https://graphql.org/learn/schema/)
+ [Vinculações de código do Amazon EventBridge](https://docs.aws.amazon.com/eventbridge/latest/userguide/eb-schema-code-bindings.html)
**Exemplos relacionados:**
+ [Amazon API Gateway: configurar uma API REST usando a OpenAPI](https://docs.aws.amazon.com/apigateway/latest/developerguide/api-gateway-import-api.html)
+ [Amazon API Gateway para a aplicação CRUD do Amazon DynamoDB usando a OpenAPI](https://serverlessland.com/patterns/apigw-ddb-openapi-crud?ref=search)
+ [Padrões modernos de integração de aplicações em uma era sem servidor: integração do serviço do API Gateway](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)
+ [Implementar o versionamento do API Gateway baseado em cabeçalho com o Amazon CloudFront](https://aws.amazon.com/blogs/compute/implementing-header-based-api-gateway-versioning-with-amazon-cloudfront/)
+ [AWS AppSync: como criar uma aplicação cliente](https://docs.aws.amazon.com/appsync/latest/devguide/building-a-client-app.html#aws-appsync-building-a-client-app)
**Vídeos relacionados:**
+ [Usar OpenAPI na AWS SAM para gerenciar o API Gateway](https://www.youtube.com/watch?v=fet3bh0QA80)
**Ferramentas relacionadas:**
+ [Amazon API Gateway](https://aws.amazon.com/api-gateway/)
+ [AWS AppSync](https://aws.amazon.com/appsync/)
+ [Amazon EventBridge](https://aws.amazon.com/eventbridge/)