Belvo

Como criar uma API que os desenvolvedores amem

Como criar uma API que os desenvolvedores amem

O produto principal da Belvo é um conjunto de APIs fintech que conecta os usuários com seus dados bancários, financeiros e fiscais. É principalmente um produto baseado em API, ou seja, é consumido através de endpoints API e usado como uma base para criar produtos de terceiros. Como a maioria dos produtos API, a Belvo é um produto para empresas (B2B).

Porém, como criar uma API de sucesso nesse meio? Existem alguns desafios particulares. O mais óbvio é, sem dúvida, o esforço inicial de integração necessário para rodá-lo. Quando uma nova empresa adota a Belvo, isso movimenta toda uma equipe de desenvolvimento focada em integrar a Belvo com seu produto, algo que normalmente demanda recursos escassos como engenheiros, PMs, designers, sem falar do valioso tempo de roadmap.

Dado o quão crítico pode ser este processo de integração inicial, ele deve ser feito da maneira mais suave e eficiente possível. Além da própria API, um bom produto API deve ser complementado com ferramentas, recursos e documentação para minimizar qualquer fricção potencial e proporcionar aos desenvolvedores total autonomia.

Este post cobre o que acreditamos ser o kit de ferramentas básico de um produto API e que tem sido usado desde o lançamento da Belvo. Ou seja, as ferramentas básicas que implementamos na Belvo além da própria API.

Experiência de auto-serviço para desenvolvedores

Quando começamos a criar a Belvo, nos reunimos para entender quais eram os recursos que deveríamos priorizar desde o Dia 1 para que o processo de integração fosse o mais suave possível. Olhamos para empresas como Stripe e Twilio e tentamos entender o que elas tinham em comum e como elas conseguiam proporcionar experiências de desenvolvimento tão ricas.

Dashboard da Belvo para os desenvolvedores

A única coisa que todas as grandes empresas de API têm em comum é o foco no auto-serviço para os desenvolvedores e seu comprometimento com as ferramentas e processos relacionados a esta experiência.

Nenhum engenheiro quer passar por inúmeros passos e chamados de vendas para conseguir acessar os endpoints de uma API. Oferecer uma experiência de auto-serviço é o que pode fazer com que integrar um produto como a Belvo seja algo feito em poucos dias e não em vários meses.

Criar essa experiência envolve simplificar alguns processos como criação do sandbox, download de SDKs, geração de credenciais API, acesso à documentação, geração de análise API e desenvolvimento de instalações de depuração. Tudo deve ser acessível através de um portal de desenvolvedores, facilmente localizável, e sem ser limitado por qualquer barreira para geração de leads.

Documentação de alta qualidade

A primeira coisa a se levar em conta é a documentação da API, que deve ser criada lado a lado com a própria API. Uma boa documentação conta com dois eixos diferentes: as guias de desenvolvimento e os docs da API.

  • As guias de desenvolvimento devem cobrir somente temas mais amplos, tais quais “como começar” ou “como funciona a autenticação” de forma guiada, como um tutorial.
  • Os documentos sobre os endpoints da API, por outro lado, são materiais de referência que contem informações detalhadas sobre cada endpoint da API, incluindo entradas, saídas e códigos de erro e de êxito.

Uma coisa que aprendemos ao longo do caminho é que, embora engenheiros e gerentes de produto possam escrever a documentação, eles não são especialistas em conteúdo, e preferem muito mais começar a desenvolver a próxima feature do que passar horas refinando a documentação. Contar com produtores de conteúdo técnico que se concentram exclusivamente na documentação foi um passo importante para melhorar a qualidade da nossa documentação.

Nós também descobrimos que, além das guias de desenvolvimento e dos documentos sobre os endpoints, os desenvolvedores valorizam conteúdo como os exemplos do guia rápido, amostras de código e, o acima de tudo, a coleção Postman cobrindo todos os endpoints da API com parâmetros e valores de configuração pré-carregados. A última ainda nos permite dar suporte a exemplos de implementação conhecidos, em vez de nos aprofundarmos na integração específica de cada cliente.

Building-API-product-Belvo-blog-internal-1
Coleção Postman cobrindo todos os endpoints API.

SDKs e bibliotecas

A maioria dos produtos API podem ser acessados de duas maneiras diferentes: ou diretamente através de endpoints API brutos (como REST, GraphQL ou outras soluções), ou através de um SDK ou biblioteca.

Criar SDKs para muitas linguagens de programação tem um custo, que pode ser ainda mais substancial se sua equipe não for especializada nas linguagens de programação para as quais você deseja oferecer suporte. Na Belvo, descobrimos que nossas taxas de sucesso de chamadas API aumentam em até 30% quando um SDK é usado em vez da API REST em bruto. Isto nos deu uma razão sólida para investir em SDKs em várias linguagens de programação

A Belvo oferece bibliotecas de API oficiais para diferentes linguagens de programação, como Python, Ruby e Node.

Para nós, bons SDKs precisam ter três propriedades principais:

  • Devem refletir as necessidades do cliente. Para isso, nós frequentemente perguntamos para nossos clientes e prospects que linguagens de programação eles gostariam que fossem suportadas e as listamos por ordem de prioridade.
  • SDKs devem ser idiomáticos. Em outras palavras, precisam tirar o máximo proveito das funcionalidades e particularidades de cada linguagem.
  • SDKs devem ter o código aberto porque os engenheiros de software querem poder controlar as SDKs que usam em seus projetos, inspecionar seu código-fonte quando o depuram, e talvez até mudar um pouco seu comportamento. Como resultado, os SDKs devem estar disponíveis através de gerenciadores de pacotes como npm, PyPi, ou RubyGems para que possam ser facilmente incluídos em um pipeline de construção como qualquer outra dependência de projeto.

Ambiente sandbox

Um ambiente sandbox permite que desenvolvedores testem um produto API de maneira simples e segura, sem impactar nos recursos de produção. Esses ambientes normalmente têm uma URL específica e possuem algum tipo de limitação, como número de chamadas de API ou valores de resposta fixos.

Uma funcionalidade extra que o ambiente sandbox pode oferecer é a capacidade de, por meio de programação, reproduzir tanto condições do mundo real quanto simulações de erro e diversos casos limite.

Por exemplo, quando certos parâmetros específicos são passados para o sandbox da Belvo, o ambiente acionará respostas de erro sintéticas, devolverá dados de simulação especialmente criados, ou executará outra lógica comercial específica que poderia ser difícil de reproduzir de forma confiável de outra forma.

O ambiente de testes é tão importante quanto o de produção. Pode-se dizer que um erro em um ambiente sandbox é até mais caro do que na produção, uma vez que é frequentemente usado por clientes potenciais para avaliar se devem ou não usar um determinado produto API. Logo, cada erro pode ser um fator decisivo.

Painel de controle para desenvolvedores

É muito importante disponibilizar aos desenvolvedores um lugar onde eles possam entender como as aplicações se comportam e como funcionam as chamadas API, especialmente quando precisam lidar com um grande número de chamadas. Isto inclui códigos de resposta, opções de depuração e outras informações técnicas.

Construir una API
Painel de desenvolvedores da Belvo

Estas são algumas das características básicas de um bom painel de controle para desenvolvedores:

Ter um painel de controle ou painel de controle para desenvolvedores se tornou algo comum para produtos baseados em API. Com ele, os desenvolvedores não precisam reinventar a roda e rodar suas próprias ferramentas de análise e depuração de API.

  1. Gestão de credenciais e configuração do ambiente
  2. Análise da API
  3. Tratamento de erros
  4. Depuração interativa (por exemplo, gerar e reagir a eventos sintéticos)

Precisamos de sua ajuda 😊

Na Belvo, estamos trabalhando continuamente para melhorar a experiência do desenvolvedor na plataforma. Somos obcecados em criar uma plataforma que seja fácil de usar, forneça as ferramentas corretas e dê aos desenvolvedores a autonomia necessária para criar aplicativos rapidamente.

Se estes tópicos despertam seu interesse, sinta-se à vontade para verificar nossa página de carreiras. Estamos em busca de diferentes perfis!

Compartilhe esse post

Mal podemos esperar para ouvir suas ideias!