Criação e implementação de interfaces de programação de aplicativos (APIs) utilizando TypeSpec.

O Microsoft Concise API Design Language foi renomeado e terá uma função mais abrangente na criação de serviços como REST, OpenAPI e gRPC.

Recentemente, abordei o progresso feito pela Microsoft na melhoria das APIs do Azure. Esse esforço resultou na disponibilização de um conjunto de definições de API e SDKs gerados automaticamente, facilitando a integração de aplicativos com a nuvem e a gestão de serviços do Azure através de código.

Nos bastidores, a Microsoft criou uma nova linguagem chamada CADL, o Concise API Design Language, inspirada em TypeScript e Bicep. Essa linguagem possibilita a definição e descrição de APIs de forma mais simplificada, facilitando a implementação de operações de API e a compilação do resultado como uma definição OpenAPI. Além disso, o CADL permite estabelecer diretrizes e padrões comuns como bibliotecas, auxiliando arquitetos e desenvolvedores a colaborarem em projetos de API. Com o CADL, foi possível reduzir uma definição de OpenAPI de 500 linhas para apenas 50 linhas de código.

Ferramentas como CADL são essenciais para dar suporte a plataformas em larga escala, como o Azure, que atualizam suas APIs várias vezes ao dia. É crucial ter APIs consistentes que possam ser utilizadas por usuários e serviços. As APIs modernas são fundamentais para aplicativos de clientes, ferramentas de desenvolvedores e muito mais. Garantir a precisão das definições públicas do OpenAPI é fundamental para fornecer o suporte necessário e permitir que o serviço hospedeiro utilize testes automatizados e gere documentação.

Essa última demanda, a documentação, é extremamente relevante para os desenvolvedores. Às vezes, pode faltar tempo para escrever a documentação, por isso é vantajoso contar com ferramentas que possam gerar documentação útil e, ao mesmo tempo, fornecer um conjunto de endpoints compreensíveis para máquinas. Isso pode economizar tempo para todos os envolvidos.

De “CADL” para “TypeSpec”.

Nos últimos anos, houve muitas novidades em relação ao CADL, que agora passou a se chamar TypeSpec. Este novo nome reflete sua ligação com linguagens fortemente tipadas e sua função na criação e manutenção de especificações de API. A Microsoft o descreve como mais do que apenas um idioma, referindo-se a ele como uma plataforma que integra linguagem e ferramentas para organizar tipos de dados, padrões de API e diretrizes em componentes reutilizáveis.

O TypeSpec é amplamente utilizado na Microsoft, expandindo-se de sua origem na equipe do Azure SDK para a equipe do Microsoft Graph e outras equipes. A adesão de duas das principais equipes de API da Microsoft ao TypeSpec é um indicativo positivo para os demais, demonstrando confiança no kit de ferramentas e garantindo uma comunidade de desenvolvimento ativa para o projeto de código aberto subjacente.

Com certeza, o projeto de código aberto hospedado no GitHub está bastante ativo. TypeSpec 0.56 foi lançado recentemente e recebeu mais de 2000 contribuições. A maior parte do código é elaborada em TypeScript e convertida em JavaScript para funcionar em diversos sistemas de desenvolvimento.

TypeSpec é compatível com várias plataformas e pode ser executado em qualquer ambiente onde o Node.js esteja presente. A instalação é feita através do npm. Embora seja possível utilizar qualquer editor de código para escrever em TypeSpec, a equipe recomenda o uso do Visual Studio Code, pois a extensão TypeSpec para o VS Code oferece um servidor de idiomas e suporte a variáveis de ambiente comuns. Essa extensão opera de maneira semelhante a outras extensões de linguagem no VS Code, fornecendo ferramentas de diagnóstico, realces de sintaxe e completarão de código IntelliSense. Projetos de maior porte podem se beneficiar de uma extensão similar para o Visual Studio.

A base da linguagem TypeSpec é flexível e permite a rápida adição de novos tipos de API, assim como a inclusão de suporte para diferentes linguagens de serialização de dados. As adições são disponibilizadas como arquivos npm, facilitando sua distribuição e compartilhamento através de ferramentas e plataformas conhecidas.

O TypeSpec oferece um playground prático onde é possível testar diversas definições de API. Nele, é possível visualizar de forma rápida como o código de exemplo se adapta a diferentes definições de API, como REST, HTTP, protocolo buffers e JSON schema. A variedade de opções de definição pode facilitar a transição entre diferentes tipos de API.

É positivo observar a inclusão de suporte para buffers de protocolo no TypeSpec, uma vez que esses são empregados na especificação de chamadas gRPC, as quais estão se tornando cada vez mais cruciais para a implementação de APIs de microsserviços de alto desempenho. Essa adição também tende a facilitar o desenvolvimento multi-nuvem, pois os buffers de protocolo são essenciais para diversos serviços na Plataforma Google Cloud.

Iniciar com TypeSpec

A configuração é fácil, e assim que você tiver feito o download do TypeSpec CLI, chamado tsp, poderá iniciar a criação da sua primeira especificação de API. O software emprega um método interativo para selecionar um modelo de API e um conjunto adequado de bibliotecas para a definição de API que você está focando, como o openapi3 para a versão atual do OpenAPI.

Próximo passo: a etapa seguinte consiste na instalação das dependências. Após isso, estará preparado para iniciar a edição do código TypeSpec, trabalhando no arquivo principal tsp. O site de documentação em expansão contém muitas informações úteis, embora seja direcionado principalmente para o trabalho com descrições HTTP ou OpenAPI. Mesmo assim, essas abordagens são amplas o suficiente para a definição de APIs, podendo ser utilizadas como referência para outros formatos de API e SDK.

Você pode ter uma boa ideia de como usar o TypeSpec para criar uma API REST simples e apresentá-la como uma descrição OpenAPI. Trabalhar com o código TypeSpec será bem familiar, pois sua sintaxe é bastante semelhante a linguagens como C# e TypeScript. Para começar a definir sua primeira API, comece importando as bibliotecas para HTTP e REST antes de configurar o seu serviço.

A maior parte dos elementos no TypeSpec são baseados em decoradores, que são descritores especiais para os elementos de uma API. Esse método envolve começar com informações gerais e adicionando detalhes conforme a API é desenvolvida. Inicialmente, você utiliza informações conhecidas, como nomes de serviços e URLs de endpoints, e então inclui parâmetros para suportar APIs que são planejadas para funcionar em diversas regiões.

Os namespaces agrupam elementos relacionados, como nomes de aplicativos, rotas para acessar recursos específicos e o modelo de dados subjacente. Com essas informações em mãos, é possível iniciar a inclusão de operações HTTP em suas rotas, bem como quaisquer chamadas específicas necessárias. Outras opções permitem a adição de parâmetros a uma descrição, o que possibilita a definição de estruturas de API mais complexas. Essa abordagem permite o uso de técnicas semelhantes tanto para GraphQL quanto para outros serviços baseados em HTTP, não ficando restrito apenas às APIs REST.

Depois de concluir a redação da descrição de sua API, é chegada a hora de entregá-la no formato desejado. No caso de uma API REST, é possível empregar o emissor OpenAPI versão 3, acionando-o durante a execução do compilador TypeSpec. Outra opção é incluir a descrição no arquivo de configuração do seu projeto atual, para que seja chamada automaticamente ao executar o compilador. Os emissores desempenham um papel fundamental no TypeSpec, pois fazem o mapeamento do seu código para a descrição da API. A Microsoft oferece um framework de emissores que pode ser utilizado para agilizar o desenvolvimento dos seus próprios emissores. Ainda assim, a criação de emissores continua sendo uma das partes mais complexas do processo.

Observe que a Microsoft disponibiliza documentação específica sobre a utilização do TypeSpec com o Azure, pois possui um conjunto público de bibliotecas que definem os padrões de API do Azure. Essa documentação é voltada principalmente para os usuários internos da Microsoft, indicando que o uso do TypeSpec pode facilitar a aprovação em revisões de código. O mais útil nesse contexto é um conjunto de bibliotecas que estabelecem os padrões do Azure, os quais podem auxiliá-lo na aplicação das melhores práticas do TypeSpec para as definições do OpenAPI.

Ferramentas como TypeSpec estão se tornando cada vez mais essenciais no desenvolvimento moderno. Em arquiteturas orientadas a serviços, é crucial ter APIs bem planejadas e documentadas antes de iniciar a codificação em ambos os lados da API. Portanto, é positivo ver uma ferramenta que originalmente foi criada para facilitar a vida dos engenheiros da Microsoft se tornar mais amplamente disponível. Será interessante observar como a comunidade do TypeSpec se expandirá e quais outras bibliotecas e iniciativas surgirão a partir dela.