Há algum tempo escrevi sobre o trabalho que a Microsoft estava fazendo para melhorar as APIs do Azure. Esse projeto forneceu um conjunto de definições de API e SDKs gerados automaticamente, facilitando a vinculação de seus aplicativos à nuvem e o gerenciamento de serviços do Azure usando código.
Nos bastidores estava uma nova linguagem desenvolvida pela Microsoft chamada CADL, a Concise API Design Language. Com base nos conceitos do TypeScript e do Bicep, o CADL permitiu definir e descrever APIs de uma forma que facilitou o uso do código para definir operações de API e, em seguida, compilar o resultado como uma definição OpenAPI. Ele também permite definir proteções e padrões de definição comuns como bibliotecas, ajudando arquitetos e desenvolvedores a colaborar em projetos de API. CADL foi um avanço no design de API, capaz de produzir uma definição OpenAPI de 500 linhas em apenas 50 linhas de código.
Ferramentas como CADL são essenciais para oferecer suporte a plataformas massivas como o Azure, que recompilam suas APIs várias vezes ao dia. Eles precisam de APIs consistentes que os usuários e serviços possam consumir. APIs modernas são uma dependência fundamental para aplicativos clientes, ferramentas de desenvolvedor e muito mais. Garantir que as definições públicas do OpenAPI estejam corretas é fundamental para fornecer o suporte necessário, bem como permitir que o serviço host use testes automatizados e geração de documentação.
Esse último requisito – documentação – é muito importante para os desenvolvedores. Você pode não ter o tempo necessário para escrever a documentação, portanto, ter ferramentas que possam produzir documentação utilizável ao mesmo tempo em que entrega um conjunto de endpoints legíveis por máquina pode economizar muito tempo de todos os envolvidos.
Do CADL ao TypeSpec
Mais ou menos um ano desde a última vez que escrevi sobre CADL, muita coisa aconteceu. A mudança mais óbvia é o novo nome, TypeSpec, que denota sua herança em linguagens fortemente tipadas e seu papel na geração e manutenção de especificações de API. A Microsoft descreve o TypeSpec como mais do que uma linguagem, em vez disso o chama de “uma plataforma”, pois combina a linguagem e as ferramentas necessárias para transformar tipos de dados comuns, padrões de API e diretrizes de API em componentes reutilizáveis.
TypeSpec é amplamente utilizado na Microsoft, tendo se espalhado de sua casa original na equipe Azure SDK para a equipe Microsoft Graph, entre outros. Ter duas das maiores e mais importantes equipes de API da Microsoft usando TypeSpec é um bom sinal para o resto de nós, pois mostra confiança no kit de ferramentas e garante que o projeto de código aberto subjacente tenha uma comunidade de desenvolvimento ativa.
Certamente, o projeto de código aberto, hospedado no GitHub, está muito ativo. Recentemente, lançou o TypeSpec 0.56 e recebeu mais de 2.000 commits. A maior parte do código é escrita em TypeScript e compilada em JavaScript para que possa ser executada na maioria dos sistemas de desenvolvimento.
TypeSpec é multiplataforma e será executado em qualquer lugar que o Node.js for executado. A instalação é feita via npm. Embora você possa usar qualquer editor de programador para escrever código TypeSpec, a equipe recomenda usar o Visual Studio Code, pois uma extensão TypeSpec para VS Code fornece um servidor de linguagem e suporte para variáveis de ambiente comuns. Isso se comporta como a maioria das extensões de linguagem do VS Code, oferecendo ferramentas de diagnóstico, destaques de sintaxe e preenchimento de código IntelliSense. Projetos de maior escala podem aproveitar uma extensão semelhante para Visual Studio.
A linguagem TypeSpec subjacente é extensível, portanto, novos tipos de API podem ser adicionados rapidamente, bem como suporte para linguagens de serialização de dados. As extensões são empacotadas como arquivos npm, para que possam ser distribuídas e compartilhadas usando ferramentas e plataformas familiares.
O site TypeSpec inclui um playground útil que permite experimentar uma seleção de diferentes definições de API. Você pode ver rapidamente como o código de amostra é compilado em uma definição de API, com amostras que incluem REST, HTTP, buffers de protocolo e esquema JSON. A disponibilidade de definições alternativas pode ajudar na migração de um tipo de API para outro.
É bom ver o suporte para buffers de protocolo no TypeSpec, pois eles são usados para definir chamadas gRPC, que são cada vez mais importantes para fornecer APIs de microsserviços de alto desempenho. Esse suporte também deve ajudar no desenvolvimento entre nuvens, já que os buffers de protocolo são usados para muitos serviços do Google Cloud Platform.
Introdução ao TypeSpec
A instalação é direta e, depois que o TypeSpec CLI, tsp, for baixado, você poderá começar a construir sua primeira definição de API. A ferramenta usa um processo interativo para escolher um modelo de API e um conjunto apropriado de bibliotecas para a definição de API que você deseja, por exemplo, openapi3 para a versão atual do OpenAPI.
A próxima etapa é instalar dependências. Então você está pronto para começar a editar o código TypeSpec, trabalhando no arquivo main.tsp. Há muitas informações boas no crescente site de documentação, embora ele esteja focado em trabalhar com descrições HTTP ou OpenAPI. No entanto, essas abordagens são suficientemente genéricas para definir APIs e você poderá usá-las como guias para outros formatos de API e SDK.
Você pode ter uma boa noção de como trabalhar com TypeSpec construindo uma API REST básica, entregando-a como uma descrição OpenAPI. Trabalhar com código TypeSpec será muito familiar, já que a sintaxe básica deve muito a linguagens como C# e TypeScript. Para sua primeira definição de API, comece importando as bibliotecas para HTTP e REST, antes de definir seu serviço.
A maioria das construções no TypeSpec são construídas em torno de decoradores, descritores específicos para elementos de uma especificação de API. Isso requer começar em um nível alto e adicionar detalhes à medida que você preenche sua API. É uma abordagem que funciona bem: você começa com o que conhece, como nomes de serviços e URLs de endpoint, usando parâmetros para adicionar suporte a APIs projetadas para funcionar em mais de uma região.
Os namespaces reúnem elementos relacionados, como nomes de aplicativos, as rotas usadas para acessar recursos específicos e o modelo de dados subjacente. Depois de obter esses detalhes, você poderá começar a adicionar operações HTTP às suas rotas e quaisquer chamadas específicas que precisem ser feitas. Outras opções permitem adicionar parâmetros a uma descrição, permitindo definir estruturas de API mais complexas. Essa abordagem significa que você pode usar as mesmas técnicas para GraphQL e outros serviços baseados em HTTP; você não está limitado a APIs REST.
Depois de escrever a descrição da API, é hora de entregá-la no formato escolhido. Para uma API REST, você pode usar o emissor OpenAPI versão 3, chamando-o ao executar o compilador TypeSpec. Alternativamente, sua descrição pode ser adicionada ao arquivo de configuração do seu projeto atual, onde será chamada automaticamente quando o compilador for executado. Os emissores são uma peça-chave do TypeSpec, pois mapeiam seu código para a descrição da API. A Microsoft fornece uma estrutura de emissor que você pode usar para acelerar o desenvolvimento de seus próprios emissores. Mesmo assim, a criação de emissores continua a ser uma das partes mais complexas do processo.
Observe que a Microsoft fornece documentação separada para usar o TypeSpec com o Azure, pois possui um conjunto público de bibliotecas que codificam os padrões de API do Azure. Isso se destina principalmente aos usuários internos da Microsoft, pois sugere que o uso do TypeSpec ajudará a passar nas revisões de código. O que talvez seja mais útil aqui é um conjunto de bibliotecas que codificam os padrões do Azure, que podem ser usados para ajudá-lo a explorar as práticas recomendadas do TypeSpec para definições OpenAPI.
Ferramentas como TypeSpec são uma peça cada vez mais importante da moderna cadeia de ferramentas de desenvolvimento. Arquiteturas orientadas a serviços precisam de APIs bem projetadas e documentadas, que devem ser definidas antes de começarmos a escrever o código em ambos os lados da API. Portanto, é bom ver uma ferramenta que foi originalmente desenvolvida para facilitar a vida dos engenheiros da Microsoft, obtendo um lançamento mais amplo. Será interessante ver como uma comunidade TypeSpec mais ampla evoluirá e quais outras bibliotecas e emissores a comunidade criará.
