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:
Antipadrões comuns: As aplicações criadas com arquiteturas orientadas a serviços ou microsserviços podem operar de forma independente e, ao mesmo tempo, ter uma dependência de runtime 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.
-
Criar APIs de serviço sem esquemas altamente tipificados. Isso ocasiona APIs que não podem ser usadas para gerar vinculações de API e payloads que não possam 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 estabelecer 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 Amazon API Gateway
Etapas da 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.
-
A importação de uma definição de OpenAPI 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
e o AWS Cloud Development Kit (AWS CDK) . -
A exportação de uma definição de API 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 APIs do GraphQL com o AWS AppSync definindo um arquivo de esquema GraphQL 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.
-
Projetos do AWS 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 . -
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ções e respostas 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:
Documentos relacionados:
Exemplos relacionados:
Vídeos relacionados:
Ferramentas relacionadas:
