Os construtores de API devem vender para desenvolvedores ou morrer lentamente

No passado, a facilidade de desenvolvimento raramente era considerada quando se tratava de integrações de API. Publicar uma referência do Swagger (agora conhecido como OpenAPI) era muitas vezes o máximo que uma empresa poderia e faria por seus usuários desenvolvedores. Depois disso, você estava sozinho. Esperançosamente, armado com algumas bebidas geladas, você conseguirá sair daquela floresta.

Imagem gerada pelo ChatGPT

Mas hoje, os produtos amigáveis ​​ao desenvolvedor estão ganhando rapidamente vantagem no mercado. Qualquer ferramenta que torne um produto mais acessível para uso dos desenvolvedores pode melhorar os resultados financeiros de uma empresa, de modo que as empresas de sucesso não medem esforços para encontrar e fornecer essas ferramentas.

Estamos nos aproximando rapidamente de um ponto de inflexão. As empresas têm mais opções de ferramentas do que nunca para fornecer aos desenvolvedores uma ótima experiência. Isto levou a um aumento no número de empresas que competem com plataformas estabelecidas, e a melhoria da experiência do desenvolvedor é o principal diferencial competitivo. Por exemplo:

• Reenviar vai atrás do Mailchimp.
• PostHog está atrás do Google Analytics, Amplitude e LaunchDarkly.
• Airbyte está indo atrás de Fivetran.
• Dub.Co está indo atrás do Bit.ly.
• Hex está indo atrás de Jupyter.

A lista continua e sua empresa pode estar nela.

A razão é que muitas plataformas de API nunca foram projetadas pensando nos desenvolvedores. As APIs foram aparafusadas aleatoriamente em produtos de software como serviço (SaaS) existentes, com pouca atenção à experiência do usuário.

Então por que você deveria se preocupar?

Há muitos motivos pelos quais a experiência do desenvolvedor precisa ser considerada nas ferramentas usadas pelos desenvolvedores.

Integração mais rápida desbloqueia receita para APIs externas

O tempo que leva para uma integração entrar em operação é medido em semanas ou às vezes meses. Quando os desenvolvedores têm que lutar com processos complicados, escrever código do zero, lidar com vários erros e assim por diante, isso alonga os ciclos de vendas e deprime o crescimento da receita.

APIs internas afetam a produtividade do desenvolvedor

A produtividade do desenvolvedor é um KPI crucial para a maioria das empresas. De acordo com o Relatório sobre o estado da API de 2023 do Postman, mais de 55% dos engenheiros gastam 10 ou mais horas por semana trabalhando com APIs. A produção do desenvolvedor melhorará se suas APIs internas não forem obstáculos para sua equipe de engenharia. Manter seus desenvolvedores satisfeitos com seu trabalho melhorará a qualidade de seu produto e os resultados financeiros da empresa.

Os desenvolvedores têm muito poder nas decisões de compra

Como o tempo e a produtividade dos desenvolvedores são tão valiosos, eles geralmente têm muita influência nas decisões dos fornecedores. Freqüentemente, eles terão direito de veto se forem usuários primários ou mesmo secundários. E eles são um público muito específico: sua apresentação de vendas ou demonstração encenada não funcionará. Eles exigirão acesso à sua plataforma. Se o seu produto não impressionar, seu negócio provavelmente fracassará.

A IA pode não gostar da sua plataforma SaaS

AI é o usuário mais novo que seu produto precisa oferecer suporte. Com a forte ressalva de que ainda estamos no começo, a IA funciona melhor por meio de APIs. Informações incorretas, imprevisibilidade e interfaces hostis reduzem a capacidade da IA ​​de utilizar os recursos da sua plataforma.

A competição é mais forte

Há uma explosão de ferramentas disponíveis para ajudar os desenvolvedores a fazerem seu trabalho melhor e com mais eficiência. Antigamente, as empresas podiam se safar com suas especificações Swagger porque não havia muito mais que pudessem fazer. A menos que você fosse Stripe, com um exército de engenheiros à sua disposição, você teria que reunir algumas ferramentas de código aberto bastante medíocres e escrever fluxos de trabalho personalizados apenas para criar algo aceitável. No entanto, nos últimos dois anos, uma revolução eliminou todas as desculpas para não contribuir para a produtividade do desenvolvedor – da sua parte e de seus parceiros ou clientes.

Por que as empresas ficam presas?

As empresas muitas vezes se concentram no desenvolvimento de um sistema para criar documentação atualizada. Isso costuma ser considerado o auge da experiência do desenvolvedor — e costuma ser um erro. Embora seja certamente importante gerenciar sua documentação usando um fluxo de trabalho bem definido e repetível, e quanto ao conteúdo real dos documentos?

Fornecer um snippet de código conciso que replica uma integração é a documentação mais útil que você pode fornecer aos usuários que estão tentando integrar sua API. Para generalizar, se o seu público-alvo são desenvolvedores, então o núcleo da sua documentação precisa ser baseado em código.

Agora você pode estar se dando tapinhas nas costas e pensando: “Bem, temos trechos de código em nossa documentação da API; já somos os melhores da classe.” Mas não tão rápido. O código é muito importante e é aqui que a maioria das organizações falha.

Veja o código na sua documentação. Parece assim?

Ou é assim?

Esses blocos de código mostram como escrever Python para buscar um recurso do cliente em uma API de cobrança, mas não são a mesma coisa. O primeiro bloco de código é um código genérico que não ajudará os usuários a configurar uma integração de produção com a API. É apenas um tema Python curl solicitar. Os consumidores da sua API não a usarão para criar uma integração empresarial.

Enquanto isso, o segundo bloco de código é exatamente como um usuário se integraria a uma API em produção. Ele usa o kit de desenvolvimento de software (SDK) Python do provedor de API. Mesmo neste simples GET solicitação, o SDK dispensa a necessidade de analisar detalhes como a estrutura de URL da sua API. Desde o início, ele pode lidar com questões importantes, como tratamento de erros, segurança, novas tentativas, paginação e muito mais — tudo que o usuário precisa para integrar com sua API.

O que é um SDK?

Por que os SDKs são tão importantes para garantir que seu produto seja adequado aos desenvolvedores?

Tudo se resume a ajudar os consumidores da API a se integrarem mais rapidamente. Quando as pessoas decidem integrar-se à sua API, elas têm um trabalho que desejam realizar. Eles acham que sua API pode ser o caminho mais rápido para resolvê-lo. Mas muitas vezes, construir uma integração com a API é tão penoso (ou ainda mais penoso) quanto o trabalho original. Isso é contraproducente, para dizer o mínimo. Há centenas de coisas que seus usuários preferem fazer do que ler a documentação da API e escrever código de integração básico. Quanto menos você exigir deles, mais felizes eles serão. E os SDKs são a melhor ferramenta para garantir que sua API permaneça discreta.

A definição de SDK é simples: é uma biblioteca que envolve sua API e cuida das partes chatas do processo de integração, como:

• Construindo uma solicitação HTTP
• Gerenciando um token de autenticação
• Tratamento de novas tentativas
• Analisando respostas paginadas

SDKs mais poderosos irão além do básico de manipulação de solicitações e respostas e fornecerão segurança de tipo e dicas no ambiente de desenvolvimento integrado (IDE). Isso significa que os usuários não precisam abrir uma página de documentos; eles obterão todas as informações e comentários necessários diretamente em seu ambiente de codificação. Não existe nada mais eficiente do que isso.

Imagem gerada pelo ChatGPT

Como você constrói SDKs?

Se os SDKs são tão bons, por que nem todas as empresas os possuem? Em grande parte, isso ocorre porque faltam ferramentas há muito tempo: se você quisesse um SDK, precisava construí-lo manualmente, e isso custaria muito tempo e dinheiro.

As bases de usuários da maioria das empresas estão espalhadas por diversas linguagens e tempos de execução. Você pode manter um SDK manualmente, talvez até dois. Mas, eventualmente, a carga de manutenção começa a pesar na velocidade de desenvolvimento da API, pois cada mudança requer atualizações em todos os SDKs. É por isso que apenas as maiores empresas avançadas de tecnologia, como Stripe e Twilio, conseguiram executar programas SDK de maneira eficaz.

Felizmente, a situação melhorou dramaticamente nos últimos dois anos. Existem agora vários geradores que podem criar SDKs a partir de uma especificação OpenAPI. Speakeasy é um deles, e ferramentas de código aberto também estão disponíveis. Essas ferramentas democratizaram a criação de SDKs, possibilitando a construção de um programa robusto sem um grande comprometimento de engenharia. Tudo que você precisa é de uma especificação OpenAPI atualizada.

Como você obtém uma especificação OpenAPI?

OpenAPI (anteriormente conhecido como Swagger) é a linguagem de especificação padrão do setor para descrever APIs REST. O objetivo é tornar mais fácil para humanos e ferramentas analisarem sua API rapidamente. No entanto, não foi feito para ser fácil de escrever.

Se precisar criar uma nova especificação OpenAPI, você precisará decidir se deseja gerenciá-la manualmente ou gerá-la a partir do código. Este é um tópico controverso que você precisará avaliar e decidir por si mesmo. Qualquer que seja a abordagem escolhida, os documentos do Speakeasy fornecem dicas sobre como otimizar suas especificações para geração de código limpo.

O que você faz com seus SDKs?

Depois de ter uma especificação OpenAPI, SDKs e documentação, você estará pronto para reunir tudo em uma experiência de desenvolvedor coesa. Isso nos leva de volta ao início — integrando seu SDK à sua documentação:

A maioria das plataformas de documentação deve fornecer uma maneira de substituir seus snippets genéricos por código personalizado que aproveite seu SDK. Se seus SDKs forem feitos à mão, você precisará se lembrar de atualizar os snippets à medida que sua API for alterada. Isso é chato, mas vale a pena fazer, pois tornará sua documentação muito mais poderosa e fácil de usar. Alternativamente, você pode tentar o Speakeasy para gerar trechos para seus documentos automaticamente.

Os snippets de uso que correspondem ao uso de produção são altamente eficazes. Ninguém quer analisar parágrafos de texto explicando sua API. Os usuários desejam copiar e colar um bloco de código em seu aplicativo, ver se funciona e adaptá-lo ao seu caso de uso imediato. Explicação não é necessária.

O esforço vale a pena?

A integração da produção com uma API corporativa envolve muito mais do que apenas fazer uma solicitação HTTP. Tratamento de erros de autenticação, análise de paginação, novas tentativas de solicitação e muito mais devem ser considerados. O status quo para empresas legadas é colocar esse fardo sobre os usuários da API, fazendo com que eles escrevam todas as integrações do zero, o que prejudica o sucesso da API.

Os produtores de API podem competir de forma muito mais eficaz, oferecendo SDKs que proporcionam aos seus consumidores de API um caminho de integração muito mais rápido e fácil de guiar. Se os SDKs forem configurados e integrados aos seus documentos, você estará mais adiantado que 90% das empresas do mercado.

Investir em ferramentas e serviços para desenvolvedores não se trata apenas de atender a uma demanda; trata-se de preparar seu negócio para o futuro e posicioná-lo para o sucesso de longo prazo em um cenário tecnológico em constante evolução. Então, se ainda não o fez, agora é a hora de considerar o que sua plataforma ou serviço pode fazer pelos desenvolvedores e colher os frutos que isso pode trazer para os resultados da sua empresa.

A postagem Os construtores de API devem vender para os desenvolvedores ou morrer lentamente apareceu pela primeira vez em The New Stack.