View on GitHub

manual-da-engenharia-para-codar

Este é o manual para compromissos de "código com" a engenharia.

Orientações de Design de REST API

Objetivos

Elevar as diretrizes de design de REST API publicadas pela Microsoft.
Destacar decisões de design comuns e fatores a serem considerados ao projetar.
Fornecer recursos adicionais para informar o design de API em áreas não abordadas diretamente pelas diretrizes da Microsoft.

Decisões Comuns de Design de API

As diretrizes da Microsoft para REST API fornecem orientações de design que abrangem uma variedade de casos de uso. As seguintes seções são um bom ponto de partida, pois são considerações provavelmente necessárias em qualquer design de REST API:

Criando Contratos de API

À medida que diferentes equipes de desenvolvimento expõem APIs para acessar vários serviços baseados em REST, é importante ter um contrato de API para compartilhar entre os produtores e consumidores de APIs. O formato Open API é um dos formatos de descrição de API mais populares. Este documento Open API pode ser produzido de duas maneiras:

Abordagem Design-First - A equipe começa a desenvolver APIs descrevendo primeiro os designs da API como um documento Open API e posteriormente gera o código de boilerplate do lado do servidor com a ajuda deste documento.
Abordagem Code-First - A equipe começa escrevendo o código da interface da API do lado do servidor, como controladores, DTOs, etc., e posteriormente gera um documento Open API a partir dele.

Abordagem Design-First

Uma abordagem Design-First significa que as APIs são tratadas como “cidadãos de primeira classe” e tudo em torno de um projeto gira em torno da ideia de que, no final, essas APIs serão consumidas por clientes. Com base nos requisitos de negócios, a equipe de desenvolvimento de API começa descrevendo primeiro os designs da API como um documento Open API e colabora com as partes interessadas para obter feedback.

Essa abordagem é bastante útil se um projeto envolver o desenvolvimento de um conjunto de APIs externamente expostas que serão consumidas por parceiros. Nessa abordagem, concordamos primeiro com um contrato de API (documento Open API), criando expectativas claras tanto para o produtor quanto para o consumidor da API, para que ambas as equipes possam começar a trabalhar em paralelo de acordo com o design da API pré-acordado.

Principais benefícios desta abordagem:

Feedback precoce sobre o design da API.
Expectativas claramente estabelecidas tanto para o consumidor quanto para o produtor, já que ambos concordaram com um contrato de API.
As equipes de desenvolvimento podem trabalhar em paralelo.
A equipe de testes pode usar os contratos de API para escrever testes antecipados, mesmo antes que a lógica de negócios esteja implementada. Ao examinar modelos, caminhos, atributos e outros aspectos da API, os testadores podem fornecer seu feedback, o que pode ser muito valioso.
Durante um ciclo de desenvolvimento ágil, as definições de API não são impactadas por alterações incrementais.
O design da API não é influenciado por limitações de implementação real e estrutura de código.
O código de boilerplate do lado do servidor, como controladores, DTOs, etc., pode ser gerado automaticamente a partir dos contratos de API.
Pode melhorar a colaboração entre as equipes de produtor e consumidor da API.

Planejando um Desenvolvimento Design-First:

Identifique casos de uso e serviços-chave que a API deve oferecer.
Identifique as principais partes interessadas da API e tente incluí-las na fase de design da API para obter feedback contínuo.
Escreva definições de contrato de API.
Mantenha um estilo consistente para códigos de status da API, versionamento, respostas de erro, etc.
Incentive revisões por pares por meio de solicitações de pull.
Gere o código de boilerplate do lado do servidor e os SDKs do cliente a partir das definições de contrato de API.

Pontos importantes a considerar:

Se os requisitos da API mudarem com frequência durante a fase inicial de desenvolvimento, a abordagem Design-First pode não ser adequada, pois isso introduzirá uma sobrecarga adicional, exigindo atualizações e manutenção repetidas das definições de contrato da API.
Pode ser útil primeiro experimentar o gerador de código específico da plataforma e avaliar quanto trabalho adicional será necessário para atender aos requisitos e diretrizes de codificação do projeto, pois é possível que um gerador de código específico da plataforma não consiga gerar uma implementação flexível e mantida do código real. Por exemplo, se o seu framework web exigir que anotações estejam presentes em suas classes de controlador (por exemplo, para versionamento de API ou autenticação), certifique-se de que a ferramenta de geração de código que você usa as suporta totalmente.
Microsoft TypeSpec é uma ferramenta valiosa para desenvolvedores que trabalham com APIs complexas. Fornecendo padrões reutilizáveis, ele pode simplificar o desenvolvimento de APIs e promover as melhores práticas. Criamos alguns exemplos de como aplicar uma abordagem de desenvolvimento Design-First em um pipeline de CI/CD do GitHub para ajudar a acelerar sua adoção em um Desenvolvimento Design-First.

Abordagem Code-First

Uma abordagem Code-First

significa que as equipes de desenvolvimento primeiro implementam o código da interface da API do lado do servidor, como controladores, DTOs, etc., e depois geram as definições de contrato de API a partir dele. Nos tempos atuais, essa abordagem é mais amplamente popular na comunidade de desenvolvedores do que a Abordagem Design-First.

Essa abordagem tem a vantagem de permitir que a equipe implemente rapidamente as APIs e também fornece a flexibilidade de reagir muito rapidamente a quaisquer mudanças inesperadas nos requisitos da API.

Principais benefícios desta abordagem:

Desenvolvimento rápido de APIs, pois a equipe de desenvolvimento pode começar a implementar as APIs muito mais rapidamente após entender os requisitos e casos de uso-chave.
A equipe de desenvolvimento tem melhor controle e flexibilidade para implementar interfaces de API do lado do servidor da maneira que melhor se adapte à estrutura do projeto.
Mais popular entre as equipes de desenvolvimento, tornando mais fácil obter consenso sobre tópicos relacionados e também possui mais exemplos de código prontos para uso disponíveis em vários blogs ou fóruns de desenvolvedores sobre como gerar definições Open API a partir do código real.

Pontos importantes a considerar:

Uma definição Open API gerada pode ficar desatualizada, portanto, é importante ter verificações automatizadas para evitar isso, caso contrário, os SDKs de cliente gerados estarão desatualizados e podem causar problemas para os consumidores da API.
Com o desenvolvimento ágil, é difícil garantir que as definições incorporadas no código em tempo de execução permaneçam estáveis, especialmente em rodadas de refatoração e ao atender várias versões concorrentes da API.
Pode ser útil gerar regularmente a definição Open API e armazená-la em um sistema de controle de versão; caso contrário, gerar a definição Open API em tempo de execução pode tornar mais complexo em cenários em que essa definição é necessária durante o desenvolvimento/tempo de CI.

Como Interpretar e Aplicar as Diretrizes

O documento de diretrizes de API inclui uma seção sobre como aplicar as diretrizes, dependendo se a API é nova ou existente. Em particular, ao trabalhar em um ecossistema de API existente, certifique-se de alinhar com as partes interessadas uma definição do que constitui uma mudança quebra para entender o impacto da implementação de determinadas melhores práticas.

Não recomendamos fazer uma mudança quebra em um serviço que antecede estas diretrizes simplesmente para cumprir.