Como produtizar uma API

June 01, 2024

Tempo de leitura: 12 minutos

Introdução

As APIs (Application Programming Interfaces) desempenham um papel crucial no desenvolvimento de software moderno. Elas permitem a comunicação entre diferentes sistemas, possibilitando integração e interoperabilidade. No entanto, para que uma API seja considerada de sucesso, ela deve ser pensada, desenhada e desenvolvida como um produto. O objetivo desse artigo é trazer uma nova perspectiva no desenho de APIs, em que elas devem ser pensadas e projetadas como produto, partindo da premissa de que uma API deve ser pensada para resolver um determinado problema, assim como qualquer produto. Nessa linha, por analogia, a disponibilização de uma API deve seguir um ciclo de vida, da mesma forma que fazemos para um produto, seja ele físico ou digital.

Para te ajudar nessa jornada de uma API como produto, serão apresentadas algumas bibliotecas, frameworks e ferramentas que podem auxiliá-lo durante esse processo.

Os acrônimos e suas limitações

Não é novidade que trabalhar com o desenvolvimento de software é conviver com uma constante “sopa de letrinhas”. Quando falamos da disciplina de desenho, implementação e manutenção de APIs, termos como REST, SOAP, HTTP, JSON, XML, dentre outros, fazem parte do vocabulário básico.

Se por um lado o uso de acrônimos facilita a comunicação, por outro, seu excesso pode nos afastar da concreta definição de um conceito. Por definição uma API “é uma maneira para dois ou mais programas de computador ou Componentes se comunicarem entre si.”¹. Contudo, em uma definição mais ampla, uma API seria um código capaz de resolver um determinado problema (application), entregue por meio de uma abstração simplificada e (re)utilizável (interface) de forma programável (programming).

As APIs são a tecnologia mais poderosa disponível atualmente, sendo mais relevantes do que ferramentas derivadas da Inteligência Artificial (IA). Não dá para ser um “terraplanista” tecnológico e duvidar dos impactos atuais e futuros das soluções que utilizam IA. Aliás, grande parte das imagens utilizadas neste artigo foram geradas usando uma ferramenta de IA, porém através de uma API. Nesse sentido, entendemos que uma API é uma tecnologia complementar e fundamental para o uso e adoção das soluções de inteligência artificial.

As APIs são poderosas, e isso é um fato. Elas são fundamentais na tecnologia moderna por vários motivos:

• Interoperabilidade: Elas permitem que diferentes sistemas se comuniquem e funcionem juntos de forma eficiente.
• Reutilização: Desenvolvedores podem reutilizar funcionalidades existentes sem precisar reescrever código.
• Escalabilidade: Facilitam a expansão de serviços e a adição de novas funcionalidades de forma modular.
• Inovação: Abrem portas para novas integrações e serviços que podem ser construídos sobre as APIs existentes.

A partir da extrapolação do conceito de API podemos afirmar que elas estão em todos lugares. Seja na comunicação do sistema operacional com a tela do seu celular, seja nas assinaturas dos métodos de uma biblioteca em uma linguagem de programação ou ainda em uma API REST que gere uma imagem, todas são aplicações do conceito de API. De forma geral, temos dois tipos de API: locais e remotas.

Podem ser consideradas como APIs locais:

• POSIX (Portable Operating System Interface): Um padrão para manter compatibilidade entre sistemas operacionais UNIX. Fornece uma API que permite a interação com o sistema operacional de maneira uniforme.
• Java APIs: Conjunto de APIs oferecidas pela linguagem de programação Java, como java.util, java.io, e java.net, que fornecem funcionalidades essenciais para manipulação de dados, entrada/saída e comunicação de rede.

Por outro lado, são exemplos de APIs Remotas:

• REST (Representational State Transfer): Arquitetura amplamente utilizada para desenvolver APIs que permitem a comunicação entre cliente e servidor usando HTTP.
• SOAP (Simple Object Access Protocol): Protocolo para troca de informações estruturadas em ambientes descentralizados e distribuídos.
• gRPC (gRPC Remote Procedure Call): Framework de RPC de alta performance desenvolvido pelo Google, que usa HTTP/2 para transporte e Protobuf para serialização.

Os exemplos descritos anteriormente demonstram a versatilidade e a ubiquidade das APIs no ecossistema atual de desenvolvimento de software. Contudo, para esta apresentação, podemos considerar API como sinônimo de APIs remotas. Segundo um relatório da empresa responsável pela ferramenta Postman, cerca de 86% dos desenvolvedores utilizam APIs REST².

Nesse ponto, espero que você já tenha se convencido sobre a relevância das APIs, contudo, quais seriam as vantagens de se desenhar uma API como produto?! De forma geral, projetar uma API como produto significa tratá-la com a mesma atenção aos detalhes como qualquer outro produto de software. Para que um produto seja bem desenhado, os seguintes pontos deveriam ser considerados:

• Entendimento do Usuário: Compreender quem são os usuários da API e quais são suas necessidades.
• Qualidade e Segurança: Garantir que a API seja robusta, segura e de alta performance.
• Documentação e Suporte: Fornecer documentação clara e suporte contínuo para os desenvolvedores que utilizarão a API.
• Evolução Contínua: Planejar para melhorias e atualizações constantes com base no feedback dos usuários.

Um produto é algo que pode ser oferecido em um mercado para satisfazer uma necessidade ou desejo. Produtos são projetados cuidadosamente, evoluem com a tecnologia e simplificam a vida dos usuários. Da mesma forma, uma API deve ser projetada para resolver problemas reais, ser fácil de usar, segura e eficiente. Ao tratar uma API como um produto, você assegura que ela agrega valor tanto para sua empresa quanto para seus usuários.

O Ciclo de Vida de uma API

Para criar uma API bem-sucedida, é essencial seguir um ciclo de vida estruturado que inclui:

• design
• desenvolvimento
• testes
• publicação
• monitoramento
• descontinuação

Para cada etapa existem bibliotecas, ferramentas e processos que podem ajudar a garantir que a API atenda às expectativas de seus usuários e stakeholders.

1. Design

O design de uma API começa com a concepção, onde identificamos os benefícios para os usuários e para a empresa. Nesta fase, definimos o comportamento e o estilo arquitetural da API e documentamos tudo.

Ferramentas para Design:

• OpenAPI Specification: Uma especificação padrão para descrever APIs RESTful. Ferramentas como Swagger Editor ajudam a criar e documentar APIs usando a especificação OpenAPI.
• GraphQL Designer: Ferramenta para projetar e documentar APIs GraphQL.
• Prism: Ferramenta para fazer o ”mocking” de APIs baseadas em OpenAPI/Swagger, útil para testes e validação inicial.
• ReDoc: Gera documentação interativa a partir de arquivos OpenAPI/Swagger.

2. Desenvolvimento

No desenvolvimento, adotamos uma abordagem API First, criamos protótipos e seguimos os padrões organizacionais. A segurança deve ser uma prioridade desde o início.

Ferramentas para Desenvolvimento:

• Postman: Uma ferramenta popular para testar APIs e gerar documentação.
• Insomnia: Outra ferramenta robusta para design, teste e depuração de APIs.
• OpenAPI Generator: Gera código automaticamente a partir de especificações OpenAPI.
• Ngrok: Permite expor localmente uma API para teste e desenvolvimento remoto.

3. Testes

Os testes garantem a correta execução e a integridade da API. Incluem testes de contrato, carga, aceitação e penetração.

Ferramentas para Testes:

• Pacts: Biblioteca para testes de contrato, garantindo que diferentes serviços interajam corretamente.
• K6s: Ferramenta de teste de carga para APIs.
• Vegeta: Outra ferramenta para testes de carga.
• SOAPUI: Ferramenta completa para testar serviços web SOAP e REST.

4. Publicação

Na publicação, documentamos a API e fornecemos suporte adequado. Estratégias de deploy, como Canary Release e Feature Toggle, ajudam na transição suave para os usuários.

Ferramentas para Publicação:

• SwaggerHub: Plataforma para colaboração e gerenciamento de APIs usando a especificação OpenAPI.
• Apigee e AWS API Gateway: Plataformas para publicar, proteger e monitorar APIs.
• Kong API Gateway: Gateway de API open-source para gerenciar o tráfego de microsserviços.
• Portal de Desenvolvimento do Spotify e Hotmart: Exemplos de portais bem projetados para desenvolvedores.

5. Monitoramento e Manutenção

O monitoramento contínuo é essencial para garantir a performance e a segurança da API. Além disso, o registro de métricas de uso pode ajudar nas decisões futuras.

Ferramentas para Monitoramento:

• Prometheus: Ferramenta open-source para monitoramento e alerta.
• Grafana: Plataforma para analisar e visualizar métricas.
• Stainless: Ferramenta para monitoramento de integridade de API.

6. Descontinuação

Quando uma versão da API precisa ser descontinuada, a comunicação clara e a oferta de alternativas são cruciais. Utilize cabeçalhos HTTP como Sunset³ para notificar sobre a descontinuação e planeje a migração.

Ferramentas para Descontinuação:

• Sunset HTTP Header: Cabeçalho HTTP para indicar a descontinuação de uma API.
• Temporary Resources: Recursos temporários para facilitar a migração dos usuários.

Conclusão

Para que uma API seja bem-sucedida, ela deve ser desenhada e gerida como um produto. Isso inclui entender as necessidades dos usuários, garantir a qualidade e a segurança e por fim fornecer suporte contínuo. Ao seguir o ciclo de vida de uma API e utilizar as ferramentas certas em cada etapa, você pode criar APIs que realmente agregam valor ao seu negócio e aos seus usuários.

As APIs devem ser pensadas como ferramentas para resolver problemas reais. Sempre comece identificando a dor do usuário e desenvolva a API com o objetivo claro de solucionar essa necessidade. Nunca perca de vista as necessidades do seu usuário final, pois são eles que determinarão o sucesso da sua API. Uma API que não resolve um problema de maneira eficaz ou que é difícil de usar, dificilmente será adotada, independentemente de sua qualidade técnica.

Priorize a comunicação e o suporte acima da tecnologia. Uma documentação clara e acessível, um portal de desenvolvedores bem projetado e um suporte eficiente são tão importantes quanto a tecnologia utilizada para desenvolver a API. Eles são fundamentais para garantir que os desenvolvedores possam utilizar sua API com facilidade e eficácia.

Se importe com a adoção das suas APIs. Monitore o uso, peça feedback, e esteja disposto a fazer melhorias contínuas. A adoção bem-sucedida de uma API é um indicador claro de seu valor e relevância para os usuários.

Lembre-se: APIs como produto podem se tornar um grande negócio para sua empresa. Elas não apenas habilitam novas funcionalidades e integrações, mas também podem abrir novas fontes de receita e oportunidades de mercado. Ao tratar sua API como um produto, você está investindo no crescimento e no sucesso da sua empresa a longo prazo.

Por fim, siga um ciclo de vida bem estruturado. Utilize as ferramentas certas em cada etapa e mantenha o foco nas necessidades do usuário. Dessa forma, você criará APIs que não apenas funcionam, mas que também proporcionam uma excelente experiência aos desenvolvedores, impulsionando a inovação e o crescimento do seu negócio.

Agradecimentos

Este artigo foi escrito em conjunto com a Gabriella Mara. Agradeço muito pela parceria de sempre. Também gostaríamos de agradecer a Marcelo Lima, um dos principais promotores da ideia de um portal de APIs públicas na Hotmart, que nos ajudou com toda a parte da analogia entre APIs e produtos de software. Por fim, gostaríamos de agradecer ao Danilo Amaral, cuja apresentação sobre o ciclo de vida de APIs foi utilizada como base para o ciclo descrito neste artigo.

Apêndice: Ferramentas, Bibliotecas e Frameworks

Nessa seção listamos algumas ferramentas, bibliotecas e frameworks que podem te ajudar no processo de desenho, implementação e publicação de APIs. Elas foram organizadas conforme as etapas do Ciclo de Vida de uma API descritas nesse artigo. Essa lista não se esgota em si mesma. Por favor, utilize os comentários para sugerir outras ferramentas que você conhece ou utilizada.

• ← A Invenção do Zero (Arquitetural)
• Sobre Nomes →