Em um mundo TypeScript, a geração de código é fundamental para SDKs de API

É uma medida de quão complexo o ecossistema de APIs se tornou o fato de empresas como a Stainless, um gerador de SDK para APIs, existirem.

O fundador Alex Rattray trabalhou anteriormente na equipe de plataforma de desenvolvimento da Stripe, e conversei com ele recentemente sobre por que a geração de código (codegen) é crítica para as APIs atuais, o trabalho que Stainless fez com OpenAI e o estado das APIs em 2024.

Enquanto estava na Stripe, Rattray criou um sistema de geração de código que geraria automaticamente um SDK para uma API. Esses tipos de sistemas “basicamente foram escritos à mão antes”, disse-me Rattray, e por isso ele se tornou conhecido no Stripe como “a pessoa do SDK”. Ele logo percebeu que construir um sistema SDK para gerenciamento de API é uma oportunidade de mercado no espaço de ferramentas para desenvolvedores.

“Basicamente, todo mundo com uma API quer um SDK se eles se importam com a experiência do desenvolvedor”, disse ele. “Mas construí-lo sozinho dá muito trabalho – é proibitivamente caro fazer um bom trabalho. Às vezes as pessoas pensam que é fácil e você pode simplesmente retirá-lo; e então isso se transforma em um terrível fardo de manutenção.”

Um problema difícil… por causa da digitação estática

O ecossistema de API na web já existe há décadas, então perguntei a Rattray por que demorou tanto para um mercado se abrir para SDKs de API.

“É apenas um problema surpreendentemente difícil”, respondeu ele, acrescentando que as soluções de código aberto disponíveis são “mais trabalhosas do que você imagina”.

API SDKs são um problema difícil devido ao surgimento do TypeScript nos últimos cinco anos.

A razão por que é um problema difícil devido ao surgimento do TypeScript nos últimos cinco anos – “e outras linguagens de tipo estaticamente”, acrescentou ele, observando que isso agora inclui nomes como Python e Ruby (ambos tradicionalmente de tipo dinâmico). A ascensão de linguagens de tipo estaticamente, como TypeScript, mas também Go e Kotlin, tornou a criação de um SDK para um sistema API muito mais complicada do que era anteriormente.

“Com a digitação estática, você precisa especificar cada parâmetro de solicitação e campo de resposta. Portanto, a ordem de grandeza das coisas que você precisa fazer para sua API vai de dezenas a (…) 150 endpoints. E, por exemplo, uma grande equipe de engenharia pode gerenciar um API SDK de 150 pontos de extremidade, mas você está vendo milhares a dezenas de milhares de parâmetros de solicitação e campos de resposta. E cada caractere tem que estar correto, certo? Como se você errasse alguma coisa, aquela coisa estava quebrada.”

“O desenvolvedor agora espera que tudo o que eles fazem seja totalmente digitado”, acrescentou ele, “e então, se você estiver interagindo com uma API e não tiver tipos para isso, você sentirá que está se agarrando ao escuro.”

‘Você absolutamente precisa do Codegen’

Se a digitação estática agora é um requisito para trabalhar com APIs, então “você absolutamente precisa do codegen”, disse Rattray. Como disse uma postagem recente no blog do Stainless, “construir SDKs que suportam tipos estáticos abrangentes em uma variedade de linguagens era totalmente impensável sem a geração de código”.

“Nosso código é um pouco como usar o React, quando estamos criando um novo SDK no lado do codegen.”
– Alex Rattray, CEO da Inoxidável

Acontece que Codegen atende aos pontos fortes do Rattray. O site Stainless afirma que Rattray “criou o sistema codegen de biblioteca cliente com patente pendente do Stripe”. Este tipo de sistema está no centro do que o Stainless oferece.

Rattray disse que o sistema de codegen inoxidável é inspirado na tecnologia de compilador, mas também – talvez surpreendentemente – no React.

“Então, a geração de código, eu penso nela como um nicho, quase esquecido, um canto da ciência da computação, que fica ao lado dos compiladores”, disse ele. “Mas é um pouco diferente. Portanto, quando construímos nosso sistema de geração de código, nos inspiramos muito nos compiladores e na teoria dos compiladores, mas também nos inspiramos nos renderizadores e nas UIs. Portanto, nosso código é um pouco como usar o React, quando estamos criando um novo SDK no lado do codegen.”

Usando IA e trabalhando com OpenAI

Stainless trabalhou com OpenAI e Anthropic até agora; e, de fato, o próprio produto usa um pouco da magia da IA.

“Portanto, a principal maneira de usarmos IA generativa para melhorar nosso produto é, quando alguém se inscreve no Inoxidável, geramos, com IA, uma espécie de primeira estimativa de como é a configuração do Inoxidável.”

Ele explicou que uma configuração do Stainless é o que mapeia a API de um cliente para seu SDK – “portanto, este endpoint deve ter este nome de método e as bibliotecas”.

Inox em ação.

Ele foi rápido em apontar, porém, que o designer humano da API deve tomar as decisões finais.

“E essa é uma daquelas coisas em que usamos algumas heurísticas e muita IA para criar esta primeira versão, mas cabe ao designer da API tornar tudo perfeito.”

A parceria com a OpenAI, no entanto, veio antes da IA ​​generativa ser adicionada ao produto Stainless. Stainless trabalhou com OpenAI em seu TypeScript/Node SDK para a API OpenAI, que foi lançado último agosto. Esse relacionamento começou através da “máfia Stripe”, com um ex-funcionário da Stripe que agora trabalhava para a OpenAI abordando Rattray.

“Quando ele se juntou à equipe de API (OpenAI), ele percebeu que eles tinham desafios com seus SDKs – eles estavam tendo dificuldade em dedicar os recursos necessários para ter a experiência de desenvolvedor que desejavam. E então ele sugeriu que entrássemos em contato; e naquela época, já estávamos trabalhando com a Anthropic e apoiando suas bibliotecas clientes essencialmente através do mesmo processo.”

O ecossistema API

Quando conversei com o especialista em API John Musser há alguns anos sobre o ecossistema de API, ele apontou que hoje em dia há muito mais diversidade em formatos de API. Embora REST (Representational State Transfer) ainda seja de longe o formato líder para oferecer APIs, outros formatos como GraphQL, gRPC, WebSocket e webhooks estavam ganhando popularidade.

Inoxidável quer resolver os problemas do REST, especialmente no mundo das linguagens de tipo estaticamente.

Essa diversidade de API ainda prevalece hoje, mas Rattray me disse que sua empresa é puramente baseada em REST porque ainda é o maior formato de API. No entanto, o que o Stainless quer fazer é corrigir os problemas do REST, especialmente neste mundo de linguagens de tipo estaticamente.

“As pessoas tiveram muitos problemas e dificuldades com REST. Quero dizer, fundamentalmente, se você não usa um gerador de SDK como o Inoxidável – e o Inoxidável não existia até hoje – (então) você não terá tipos estáticos adequados ao consumir as APIs. E isso é realmente um grande problema, especialmente para pessoas que usam linguagens como Go e Java — mas também, novamente, neste ponto, realmente para qualquer desenvolvedor”

Embora Rattray reconheça os pontos fortes de outros formatos, ele acha que as empresas não deveriam “misturar e combinar” suas APIs.

“Essa natureza fraturada do ecossistema também apresenta muitos problemas”, explicou. “Se você é um líder de engenharia, (…) você acabará muitas vezes em situações em que terá sua API GraphQL para o frontend, APIs gRPC para seus microsserviços e (e) uma API REST para sua API pública.”

Rattray diz que a visão do Stainless é “tornar o REST basicamente tão bom quanto GraphQL ou gRPC – ter todas as vantagens que possuem, para que as equipes possam usar apenas uma tecnologia simples em qualquer lugar”.

A postagem Em um mundo TypeScript, a geração de código é fundamental para SDKs de API apareceu pela primeira vez em The New Stack.