APIs (em português, interfaces de programação de aplicações) são como os softwares conversam entre si e são, portanto, uma tecnologia chave na conexão de sistemas. Estas interfaces permitem que as equipes de desenvolvimento utilizem dados, funções e aplicações para construir novos produtos de uma maneira simples.
Como Product Manager é extremamente importante entender como funcionam as APIs e o enorme potencial que elas podem ter dentro de sua equipe ou empresa.
Por que usar as APIs?
Os APIs podem ser a chave para que as organizações se expandam rapidamente em novos contextos ou se adaptem a novos mercados com um esforço consideravelmente reduzido.
Através delas, as equipes podem utilizar uma infraestrutura existente e reduzir o tempo de desenvolvimento de meses para semanas.
Aqui estão os conceitos mais importantes que você precisa conhecer sobre as APIs como Product Manager. Com este entendimento, você terá uma base sólida para falar sobre as APIs com confiança aos seus interessados e à sua equipe.
APIs públicas e internas
Antes de começarmos a falar sobre o funcionamento das APIs em si, precisamos fazer uma pequena diferenciação. Podemos separar as APIs em dois grupos, as públicas e as internas.
As APIs internas são aquelas utilizadas pelo software da sua empresa, por exemplo, para se comunicar com os diferentes microsserviços construídos pelo seu time de engenharia. Elas são utilizadas apenas no contexto da empresa para satisfazer necessidades de suas próprias aplicações como, por exemplo, transferir dados internamente.
Já as APIs públicas são projetadas para serem compartilhadas com o mundo exterior. Com elas, desenvolvedores podem construir aplicações para aproveitar as informações e funcionalidades ali presentes. O Slack é um exemplo de empresa que possui uma API pública. Por lá é possível construir uma aplicação que envie mensagens, gere alertas e crie grupos na plataforma.
- APIs internas: construídas pelo time para satisfazer necessidades particulares das aplicações;
- APIs públicas: desenvolvidas com intuito de permitir que desenvolvedores (externos) construam aplicações baseadas naquilo que foi disponibilizado.
Requisições e respostas
Em termos simples, as APIs funcionam usando "requisições " e "respostas". As requisições somos nós interagindo com a API, e as respostas são o resultado dessa interação.
Vamos tomar um exemplo. Usando o API da AccuWeather, somos capazes de solicitar informações sobre o tempo em uma determinada região. Para fazer isso, as seguintes atividades devem ser realizadas:
- Você, como usuário da API, envia uma requisição para o AccuWeather API (interação);
- No corpo desta requisição, você informa à API qual região você deseja receber as informações meteorológicas. A forma como esta descrição é transmitida deve ser descrita na documentação da API (chegaremos a isso em um momento);
- A AccuWeather retorna as informações solicitadas através de uma mensagem no formato de um "JSON" (resposta).
A documentação da API especificará como as informações devem ser passadas e como uma resposta pode ser compreendida pelo sistema.
Métodos HTTP
É necessário especificar o que se chama um método HTTP nas requisições que fazemos a uma API. Estes métodos serão responsáveis por indicar qual ação será executada para um determinado recurso na interação (se queremos apenas obter ou editar um recurso, por exemplo).
Você não precisa aprender todos os métodos HTTP, na versão mais usada atualmente, a 1.1, temos 9 métodos que têm diferentes casos de uso. Os métodos mais utilizados por uma pessoa de produto são o POST e o GET, que lhe permitem criar ou obter informações.
Aqui está um resumo dos métodos HTTP mais comuns:
- POST: usado para criar novos recursos. Por exemplo, se quiséssemos criar uma nova mensagem de texto usando a API pública do Slack, usamos o método POST, já que é assim que se criam novos recursos (neste exemplo, o recurso é a mensagem);
- GET: as requisições do tipo GET são usadas apenas para ler os dados e não para modificá-los. Isto significa que eles são considerados seguros. Por exemplo, no AccuWeather API, o GET é usado para obter as informações meteorológicas de uma região;
- PUT: usado para atualizar/substituir dados. Por exemplo, a atualização do endereço de e-mail de um usuário.
Existem outros, mas vamos nos concentrar apenas neles, já que são os mais comuns. Se você os conhece, você sabe o suficiente.
Endpoints
Um endpoint é um local no qual uma API se conecta com programas de software. Em outras palavras, os endpoints são os locais digitais específicos onde as requisições são feitas e as respostas são recebidas por um programa ou usuário que esteja interagindo com a API.
Tomemos como exemplo um endpoint da API pública da AccuWeather.
GET http://dataservice.accuweather.com/currentconditions/v1/{locationKey}
Neste endpoint, chamado de currentconditions, o usuário pode fazer uma requisição do tipo GET para solicitar os dados das condições atuais para um local específico.
Neste exemplo temos o locationKey como parâmetro passado pelo usuário na requisição. Ele serve como uma forma de especificar para a API qual região estamos buscando as informações.
Vale ressaltar que o mesmo endpoint pode funcionar com mais de um tipo de método HTTP. A utilização de múltiplos métodos não é simultânea (você não pode fazer um GET e um POST na mesma requisição), mas em alguns casos, você pode obter e/ou editar recursos dentro do mesmo endpoint.
Códigos de resposta
Durante o processo de interação com uma API, você pode receber diferentes tipos de mensagens. Estes códigos de resposta são usados para indicar o sucesso ou o fracasso de uma requisição. Em geral:
- Os códigos na faixa de 200 indicam sucesso;
- Os códigos na faixa de 400 indicam um erro com base nas informações fornecidas (por exemplo, um parâmetro obrigatório não foi enviado);
- Códigos na faixa de 500 indicam um erro nos servidores da API.
As mensagens que aparecem em cada caso variam de acordo com a API. Os detalhes das mensagens e os casos de uso da aplicação são descritos na documentação da API (geralmente onde se fala de tratamento de erros).
Autenticação e autorização
A maioria das APIs exige algum tipo de autenticação do usuário antes de fazer uma requisição a seus serviços.
No caso de APIs públicas, os usuários geralmente têm acesso a algum tipo de credencial que será adicionada a requisição quando ela for enviada. Estas credenciais funcionam como um identificador para a pessoa ou empresa que está interagindo com um determinado serviço.
Por exemplo, quando eu solicito os dados meteorológicos de minha região da API da AccuWeather, a aplicação sabe que sou eu quem está solicitando essa informação e não outra pessoa. Além disso, os métodos de autenticação também servem para limitar ou conceder acesso a certos recursos da API (autorização).
Se não podemos permitir que qualquer grupo de pessoas acesse ou edite certos dados disponíveis através da aplicação, criamos uma limitação para aqueles através de suas credenciais de acesso. Desta forma, quando este grupo tentar fazer uma ação que não está autorizado a fazer, a API enviará uma mensagem de erro em resposta a essa interação.
De uma maneira geral:
- Autenticação: demonstra para a API quem é o usuário que está interagindo com os seus serviços. Na maioria das vezes, a autenticação de um usuário é composta por: usuário, senha, token de acesso;
- Autorização: é uma definição, desenvolvida pelo time que construiu a API, sobre o que os grupos de usuário têm permissão ou não para fazer em suas interações com os serviços ali presentes.
Documentação da API
A documentação acaba sendo o principal ponto de contato das pessoas de produto com as APIs em si. É onde todas as funcionalidades disponíveis serão listadas, e como as interações com a aplicação podem acontecer.
Em alguns casos, podemos ter lugares na documentação onde as solicitações podem ser feitas diretamente do navegador (geralmente isto está em uma página chamada API Reference). Esta página mostra como a requisição será montada e como a resposta será devolvida.
Além disso, a documentação deixa claro quais são os limites para cada tipo de acesso e/ou plano. No caso de APIs que funcionam através de planos, deve haver algum tipo de tabela com o que cada plano pode acessar (e o número de requisições que podem ser feitas em um determinado período de tempo).
Por fim, na documentação devem estar presentes os parâmetros que podem (ou devem) ser passados nas requisições. Quais informações são obrigatórias e de que forma elas precisam ser enviadas dentro do serviço. No exemplo do endpoint da AccuWeather, a documentação deixa claro a forma que o parâmetro (locationKey) deve ser passado para que API consiga compreender o que o usuário deseja. Dessa maneira, o usuário e a API são capazes de se comunicar em uma “mesma língua” e ambos obtêm aquilo que pretendem.
O que esperar encontrar em uma documentação:
- Instruções de autenticação: de que forma você deve provar a API quem é você durante a interação com os serviços;
- Endpoints: quais endpoints podem ser acessados, o que cada um disponibiliza em recurso e qual (ou quais) métodos HTTP utilizam;
- Recursos: o que está disponível através da API. Se voltarmos ao exemplo da API do Slack, a documentação deve explicitar que por ela é possível enviar mensagens, criar grupos, gerar alertas e solicitar informações de usuários, por exemplo;
- Formato da requisição: como você deve enviar as requisições e quais parâmetros podem (ou devem) ser passados;
- Formato da resposta: como a API vai responder às suas requisições. Neste ponto vale ressaltar que uma API pode responder em formatos diferentes do JSON (que falamos no exemplo da AccuWeather). Essa distinção é baseada na arquitetura da API, que pode ser do tipo REST, RPC ou SOAP, e no propósito da aplicação em si;
- Códigos de resposta: quais são os códigos de resposta presentes e como tratar os possíveis erros recebidos.
Então como as APIs podem te ajudar no dia-a-dia?
As APIs têm a capacidade de fornecer à sua equipe o potencial de criar produtos e validar hipóteses mais rapidamente, uma vez que eles estarão utilizando uma infraestrutura já existente.
Em geral, como uma pessoa de produto, você pode olhar as APIs existentes no mercado (públicas) como oportunidades possíveis para fazer testes ou crescer um produto que já possui.
- Como uma API pode me ajudar a otimizar um processo?
- Eu preciso construir minha própria infraestrutura ou vale a pena usar uma infra de terceiros?
- Como isso afeta meu modelo de negócios?
Estas são perguntas válidas a serem feitas quando você começar a considerar o uso de APIs públicas em seus produtos.
Por fim, a construção de APIs como forma de dimensionar um negócio tem sido uma prática amplamente utilizada pelos players em diferentes mercados. Externalizar a sua infraestrutura, abrindo os seus serviços para outras empresas, traz consigo a oportunidade de entrar em um novo mercado (B2B, por exemplo) e crescer de maneira exponencial, mas este é um assunto para outra conversa.
Obrigado!
