Com o Cadl, é possível resumir em apenas 50 linhas de código uma definição extensa de 500 linhas OpenAPI. Essa ferramenta oferece uma abordagem lógica para que arquitetos e desenvolvedores possam criar e limitar APIs de forma eficiente.
chsyys/KaboomPics
Existe uma vantagem na implementação da Microsoft em grande escala no Azure: Ela identificará problemas mais rapidamente e os resolverá de forma mais eficiente do que a maioria de nós. Anteriormente, essas soluções poderiam levar anos para serem desenvolvidas e integradas às ferramentas do Visual Studio. No entanto, a mudança da Microsoft para o código aberto resulta em soluções sendo desenvolvidas de forma aberta e compartilhadas com a comunidade global por meio do GitHub.
Uma questão importante é o desenvolvimento de interfaces de programação de aplicativos (API) e a busca por maneiras de padronizar todas as APIs do Azure. Atualmente, as definições modernas de API, inclusive aquelas escritas usando o OpenAPI, podem ser extensas e complexas, com algumas linhas do Azure contendo milhares de linhas. Mesmo seguindo a mesma abordagem e diretrizes, as definições de API de equipes distintas tendem a destacar elementos diversos e oferecer métodos variados para lidar com funcionalidades similares.
Com o Azure atualizando sua interface de programação de aplicativos diariamente, é necessário assegurar a consistência das APIs, além de possibilitar a automação da documentação e dos testes. Isso também permite que um desenvolvedor que já está familiarizado com um conjunto de APIs não precise aprender novas técnicas ao adicionar novos serviços a um aplicativo.
Definições contraditórias representam um desafio para nós que estamos implementando as definições de API em nossos aplicativos por meio de ferramentas OpenAPI para criar os pontos finais adequados. Isso se torna ainda mais complicado quando precisamos migrar de REST para GraphQL e gRPC à medida que nossas APIs se desenvolvem e exigem funcionalidades mais avançadas do que simples acesso HTTP.
Introduzindo Cadl.
A Microsoft está transferindo boa parte de seu desenvolvimento de API para uma linguagem chamada Cadl, que auxilia na definição programática de estruturas de API antes de compilar definições do OpenAPI. A ideia é criar uma solução para APIs similar ao que o Bicep faz para a infraestrutura, oferecendo uma forma de entregar definições de API de maneira consistente. Ao separar o design da definição, Cadl pode gerar saídas mais sucintas, assegurando que a ferramenta OpenAPI em plataformas como o Visual Studio possa analisar de forma rápida e eficaz.
Cadl é uma linguagem que, à primeira vista, parece ser semelhante a JavaScript e .NET. A Microsoft a descreve como uma espécie de “TypeScript para APIs”, com a intenção de que seja simples de utilizar para quem já está familiarizado com C#. Como outras linguagens específicas da Microsoft, Cadl se beneficia da vasta experiência da empresa no desenvolvimento de ferramentas, integrando-se facilmente às ferramentas já existentes. É possível inclusive adicionar extensões Cadl ao servidor de idiomas no Visual Studio e Visual Studio Code, garantindo um suporte de destaque com destaque na sintaxe, conclusão de código e formatação.
Criar uma linguagem como o Cadl é altamente eficaz, pois permite que você incorpore restrições arquitetônicas em regras e agrupe construções comuns em bibliotecas. Se uma descrição de API violar as regras arquitetônicas, ela não será compilada, assegurando a aplicação dessas regras no ambiente Cadl. Os designers de API devem seguir as diretrizes estabelecidas pela equipe de arquitetura, um processo que os designers Cadl descrevem como resultando em saídas “corretas pela construção”.
Assim como diversos outros projetos de código aberto da Microsoft, o Cadl está em fase de desenvolvimento no GitHub, acompanhado de uma documentação clara e detalhada. Existe até um espaço online de experimentação, onde é possível testar o código Cadl e compará-lo com as saídas nos formatos OpenAPI e Swagger. De maneira rápida, é perceptível que o código Cadl pode ser significativamente mais conciso do que a saída OpenAPI, por exemplo, uma descrição de API Cadl de 34 linhas se expande para 359 linhas no OpenAPI, ou seja, 10 vezes maior. Além disso, a manutenção do código Cadl é facilitada, já que tudo se ajusta em uma tela com a funcionalidade devidamente agrupada.
Elabore uma descrição da API utilizando o Cadl.
Instalar o Cadl é bastante simples. O compilador e a interface de linha de comando (CLI) estão incluídos na mesma aplicação hospedada no npm. Após o download e instalação, você pode utilizar a CLI para instalar as extensões do Visual Studio e do Visual Studio Code. Agora, você está preparado para criar sua primeira definição de API, iniciando o projeto com o Cadl CLI. Isso guiará você por uma breve série de perguntas para selecionar um modelo base, adicionar um nome e escolher uma biblioteca padrão. Uma rápida compilação verificará se tudo está configurado corretamente para começar a trabalhar.
É fácil definir uma API em Cadl. Basta especificar as conexões REST e OpenAPI no arquivo principal do código Cadl. Em Cadl, os termos-chave são conhecidos como “decoradores” e são precedidos por “@”, o que facilita a leitura dos arquivos pelos usuários.
A definição deve começar com as características do serviço, incluindo o nome e a versão. Também é possível incluir a definição do servidor com um link para o endpoint, útil para sistemas distribuídos em escala global. Este recurso pode ainda fornecer informações adicionais, como as regiões onde a API está acessível. Embora tenha sido pensado para o Azure, é aplicável a qualquer sistema distribuído com múltiplos endpoints.
Em seguida, é preciso estabelecer as rotas e recursos da API. As rotas indicam o caminho para acessar o recurso em relação ao URI do serviço e estão associadas a namespaces que abrangem as operações da API. As operações são especificadas utilizando o verbo HTTP apropriado ou por meio de uma função, como por exemplo “listar”. Quando são utilizados nomes, o compilador irá adicionar o verbo correspondente ao gerar a API. Estas operações podem definir o corpo da solicitação de uma chamada à API REST, permitindo o envio de JSON para uma API mais complexa ou apenas um texto simples para algo mais básico. O mesmo princípio se aplica às respostas também.
Para APIs mais sofisticadas, é possível utilizar a opção autoroute para criar rotas que incluam parâmetros, como nomes de usuário ou IDs, que são enviados para a API através do caminho. Além disso, é possível passar esses parâmetros como parte de uma consulta na URL, oferecendo maior flexibilidade no processo.
A consequência é uma forma relativamente simples de especificar suas APIs REST, que lembra um pouco o trabalho com o framework Express do node.js. Acredito que isso ocorre principalmente devido à forma como o Cadl cria URLs para as chamadas de serviço e abstrai as APIs no código. Ter experiência com ferramentas como Express pode ajudar os desenvolvedores a se adaptarem a essa nova linguagem.
Utilizando o Cadl para estabelecer normas.
“Definir uma API é apenas parte do que o Cadl faz. Ele também estabelece padrões para equipes de desenvolvimento ao fornecer estruturas que devem ser seguidas ao criar uma API. A criação de bibliotecas é fundamental para estabelecer padrões no Cadl, permitindo a gestão de modelos reutilizáveis para funções comuns, com uma sintaxe similar a C#. É interessante observar como a Microsoft utiliza esses recursos para implementar as APIs do Azure.”
Por exemplo, é possível desenvolver uma interface genérica para estabelecer um padrão de API REST, descrevendo os recursos disponíveis. Ao utilizar uma biblioteca existente, é viável ampliar as interfaces da API para se alinharem ao modelo da biblioteca, mapeando-as para uma rota específica. Posteriormente, pode-se empregar uma definição de modelo para construir a API, identificando as possíveis respostas esperadas.
O Cadl oferece uma forma direta de incluir documentação em uma API: Utilize a declaração @doc para adicionar informações que podem ser extraídas ao criar a documentação da definição OpenAI resultante. É um processo rápido e simples, e é dessa maneira que a Microsoft elabora grande parte de sua documentação para a API do Azure. Recomende aos desenvolvedores de API que adotem essa abordagem para não só adicionar documentação no corpo principal de um projeto de API, mas também em qualquer biblioteca que estejam utilizando.
O Cadl é uma linguagem específica de domínio que oferece uma abordagem lógica para a construção e restrição de APIs. Permite aos arquitetos considerarem as capacidades e entregas de uma API, ao mesmo tempo em que dá aos desenvolvedores a liberdade de criar rapidamente definições que correspondam ao código. Além disso, o Cadl facilita a adoção de definições de API consistentes por desenvolvedores de clientes e ferramentas de teste.