Tudo que os PMs precisam entender sobre documentação de API
Thais Cirqueira

Thais Cirqueira

Group Product Manager | API Specialist

7 minutos de leitura

10 Perguntas e respostas em entrevistas para Analista de Dados

Já começo me adiantando que sim, sabemos que Product Managers não são Engenheiros, não precisam saber codar e isso é o que realmente se espera. Mas como pudemos acompanhar neste artigo, existem diversas oportunidades que você, como uma pessoa de produto pode explorar dentro do universo de APIs, seja para incrementar seu produto, ou para que isso se torne seu produto. 

Aqui, vamos começar trazendo tudo – ou quase tudo – que você precisa saber para poder consumir APIs

Consumindo APIs

Um dos principais benefícios do uso de APIs é que elas permitem que seu produto pegue carona em outros para agregar novas formas de valor aos seus usuários. 

Imagine um e-commerce que não consegue oferecer para seu cliente o rastreamento do produto? Isso simplesmente é capaz de ser feito através de integrações com APIs.

No artigo O básico sobre APIs para não-devs trouxemos alguns conceitos básicos para que você consiga entender o universo das APIs. Mas, afinal, por que eu deveria aprender a ler uma documentação de API?

Motivos pelos quais você deveria aprender a ler a documentação da APIs

Considerando que você, Product Manager, tem um produto em mãos, e enxerga uma oportunidade de integração com uma API de outra empresa.

  • Explore as oportunidades: lendo e entendendo a documentação da API, você tem a oportunidade de explorar o que é possível com as APIs que estão disponíveis para você. Assim, depois de ler uma documentação, você pode descobrir funcionalidades que antes desconhecia e gerar novas ideias para seu próprio produto.
  • Acionar as bandeiras vermelhas: a leitura da documentação da API irá lhe dar a oportunidade de identificar bandeiras vermelhas em potencial, o que pode inviabilizar ou prejudicar a integração com seu produto. Além disso, outro ponto importante, se os documentos não forem atualizados em 3 anos, considere isso uma bandeira vermelha!
  • Validar o comportamento: a documentação é – ou ao menos deveria – ser a sua única fonte de verdade para testes de integração de API. Você precisará usar a documentação da API para verificar se está se comportando como deveria.

Além disso, vale lembrar que hoje em dia os documentos da API não são mais domínio exclusivo dos engenheiros – espera-se que os PMs e membros do time não-devs (QA, design) tenham uma compreensão de como as APIs funcionam.

Partes importantes da documentação

Agora que você sabe que precisa ler uma documentação, vamos trazer quais os principais pontos que você precisa entender e se atentar ao ler uma documentação de API:

Autenticação: Informações sobre como você deverá se conectar com a API

Para se conectar a uma API e utilizar sua funcionalidade, você precisa se autenticar e provar que é um usuário com os autorizados a usar a API.

Isso é feito usando um token. No geral, para utilizar os serviços você deve se registrar e autenticar usando esse token.

Esse token é gerado através do usuário e senha disponibilizado pela empresa. Esse token também costuma ter um tempo de expiração e, no geral, sua aplicação deve considerar essa informação para que não ocorram erros desnecessários e que seja possível obter sucesso nas requisições.

Recursos: Quais são os recursos que estão disponíveis para você acessar através desta API

APIs REST permitem acessar recursos. Assim, pense nos recursos como pacotes pré-concebidos de informações que são úteis para o usuário da API e vinculados à proposta de valor geral do produto que você está usando.

Então, como Product Manager, você pode ter a tarefa de explorar a funcionalidade de uma API específica e os tipos de recursos disponíveis para você são uma parte crítica dessa análise.

Se quiser usar a API do Shopify para marcar um pedido como atendido, você precisará garantir que a API permite fazer isso.

Se você planeja usar a API Mailchimp para recuperar as estatísticas de abertura de sua campanha mais recente, será necessário verificar se um recurso de campanha está disponível.

Bibliotecas de cliente: formas empacotadas de integração com a API por meio de linguagens de programação

Uma coisa que você notará ao ler a documentação da API é que muitas vezes há exemplos de diferentes linguagens de programação.

Muitas documentações irão apresentar várias formas diferentes de começar, usando diferentes linguagens de programação, como por exemplo:

  • Rubi
  • Node.js
  • PHP
  • Java

Estes são exemplos de bibliotecas que foram empacotadas para funcionar com linguagens de programação específicas. A funcionalidade principal da API permanece a mesma nas diferentes linguagens de programação. Mas a maneira como você interage com a API é um pouco diferente dependendo da linguagem de programação na qual seu produto está integrado.

Como uma pessoa de produto que não desenvolve, você não precisa se preocupar muito com isso – a capacidade de compreender a funcionalidade que está disponível para você por meio dos recursos é mais importante. Assim como a capacidade de descobrir como testar a API.

E para isso, você precisa saber quais endpoints estão disponíveis.

Endpoints da API: Quais endpoints estão disponíveis para você usar.

  • Formato da solicitação: As solicitações são enviadas para as APIs e, em troca, respondem com informações. Além disso, o formato da solicitação específica como uma solicitação para a API deve ser formatada.

Cada vez que você usa uma API, você envia uma solicitação para um local específico (e endpoint) e a API responde com uma resposta específica, dependendo do que você solicitou. Então, a documentação da API deixará claro o que a API espera ver na solicitação.

  • Formato de resposta: Como as APIs irão responder quando você enviar uma solicitação. O formato de resposta específica como uma resposta HTTP é formatada quando você recebe a resposta.

A documentação da API que vale a pena ler sempre incluirá exemplos sólidos de trabalho sobre o que esperar da resposta.

Se a resposta que você e sua equipe estão recebendo de uma API não corresponder à documentação da API, isso deve ser considerado um grande sinal de alerta.

Às vezes, será uma incompatibilidade inocente entre uma versão desatualizada dos documentos e a API, mas outras vezes isso pode sugerir que o fornecedor da API não está mantendo as especificações da API corretamente, o que sem dúvida tornará a vida mais difícil para você no futuro. linha se você planeja usar APIs para partes críticas do seu produto.

  • Códigos de resposta: Quais códigos de resposta estão incluídos na resposta

Os códigos de resposta são simplesmente números que representam coisas diferentes que podem então ser interpretadas pelos engenheiros.

Código de resposta HTTPSignificado
200Sucesso. Está tudo bem.
301O recurso que você procura foi movido permanentemente.
400Há um problema no lado do cliente. O código de erro mais famoso é o erro 404. Isso significa que o servidor não pode mapear a solicitação para um recurso.
500Há um problema no lado do servidor.

Conclusão

Em suma, como mencionamos no início, de todos os diferentes conceitos técnicos que os Product Managers devem ter conhecimento prático, as APIs estão no topo da lista.

Muitas vezes somos jogados no fundo do poço e, em particular, para gerentes de produto juniores, isso pode ser bastante assustador.

Mas, com um pouco de experiência prática e conhecimento prático dos fundamentos das APIs, além da capacidade de ler a documentação com confiança, agora você deve estar bem preparado para a próxima vez que uma parte interessada não técnica começar a conversar sobre APIs com você.