API First: uma Abordagem para Impulsionar sua Transformação Digital

De acordo com o mais recente State of the API Report, do Postman, 74% das empresas estão investindo em API First. Com o aumento considerável no consumo de APIs de IA, e o investimento cada vez mais alto das organizações em segurança, governança e experiência do desenvolvedor, a mudança do paradigma de Code First para API First é uma excelente pedida!

Nesse conteúdo vamos explorar a importância das APIs no contexto atual de mercado, o que é API First, quais são seus principais benefícios e aplicabilidade e como montar uma estratégia para implementar essa abordagem de desenvolvimento.

‍

APIs no Contexto Moderno

API é um acrônimo para application programming interface. São interfaces programáveis de aplicações onde temos a possibilidade de expor um serviço sem expor sua lógica. Dessa forma, outros serviços podem consumi-la de forma estruturada (seguindo um contrato), de acordo com os recursos expostos.

Quando falamos do contexto atual de APIs, geralmente estamos falando de APIs web. E quando falamos de APIs web, a arquitetura de APIs mais utilizada é REST (representational state of transfer). Outros modelos como gRPC e GraphQL também têm sido utilizados com frequência.

Com a grande mudança de modelos tradicionais para modelos de receitas por assinatura, negócios “as-a-service” e a alta demanda por soluções que envolvem o uso de inteligência artificial, o mercado está cada vez mais competitivo e dinâmico. E as APIs têm papel fundamental, pois elas são a “cola digital”, APIs permitem que diferentes aplicações se conectem entre si de forma rápida e segura. Possibilita a criação de novos negócios, seja com APIs internas ou de terceiros. APIs com design e documentação robustos alavancam a experiência do desenvolvedor (DX) e aceleram novas parcerias, diminuem o time-to-market e garantem que mesmo com a dinamicidade do cenário de tecnologia da informação, os ativos técnicos e de negócio se mantenham conectados.

No cenário atual, existem diversas organizações ganhando dinheiro com APIs, seja aplicando o conceito de api-as-a-product, onde APIs são o produto em si, seja monetizando de forma direta através de modelos de assinatura, parceria paga ou pagamento pelo uso, ou seja através de monetização indireta onde a API é a porta de entrada para mais produtos e serviços que aquele negócio pode oferecer. E caso queira tratar uma API pelo que ela é no contexto atual, um ativo de negócio, então a abordagem API First ela faz todo sentido.

Code First

É uma abordagem de desenvolvimento focada no domínio da aplicação. Geralmente se inicia pela criação de classes, modelagem de banco de dados e depois a API, que geralmente é gerada com base no código escrito a partir de anotações ou definições no código. Após a exposição da API, os consumidores iniciam o desenvolvimento da integração.

API First

É uma abordagem de desenvolvimento onde o design da API é priorizado. O foco está na especificação da API, que descreve como os consumidores interagem com o serviço. O intuito é garantir que todas as partes interessadas (stakeholders) participem do processo, fazendo com que a API seja construída de forma colaborativa. Após a geração do contrato (especificação), tanto os times que vão se integrar (consumidores) quanto os times que vão construir o serviço (backend) iniciam o desenvolvimento.

Princípios

‍

Para garantir a aplicabilidade correta de API First, são comumente associados três princípios.

API é a primeira interface de usuário da aplicação

A partir do momento que aplicamos uma abordagem API First estamos garantindo que parceiros e/ou clientes estratégicos participem do processo de concepção da API. Sendo assim, asseguramos que os potenciais consumidores, que vão construir as integrações e consequentemente expor através de seus produtos, tenham a experiência melhorada tanto a nível do desenvolvimento quanto do consumo (direto ou indireto) dos usuários. Devemos ter em mente dois pontos.

1. Como usuários, sabemos que praticamente toda aplicação que utilizamos por “debaixo dos panos” existem APIs que se comunicam com outras aplicações para renderizar o que precisamos visualizar;
2. Os consumidores também são usuários. Pois vão construir as interações com as APIs disponibilizadas e definitivamente a experiência deles durante o desenvolvimento é fundamental para a estratégia de negócio (discutiremos mais sobre quando falarmos dos benefícios). 

API vem primeiro, depois a implementação

Quando damos a devida importância para as APIs, precisamos garantir que cada estágio do ciclo de vida das APIs esteja seguindo recomendações e boas práticas. Se tratamos as APIs como cidadãos de primeira classe (first-class citizen), então entendemos que qualquer modificação, melhoria, ajuste ou implementação realizada em uma API pode ter grande impacto nos consumidores. Refatoração, otimização e adequação fazem parte de qualquer aplicação. Mas as APIs não devem ser modificadas na mesma frequência, pois podem causar impacto negativo na experiência do desenvolvedor, que pode precisar ajustar a integração à medida que as implementações são realizadas e a API é modificada. 

API deve ser descritiva e sempre que possível auto-descritiva

Documentação é fundamental não somente para o desenvolvimento de software, mas para qualquer tipo de negócio! E com APIs não é diferente. Com API First uma documentação robusta se faz ainda mais necessária, pois as APIs em muitos casos serão a porta de entrada para novos parceiros, clientes e negócios. Então é de extrema importância que a documentação seja autodescritiva, com exemplos em várias linguagens, que tenham SDKs e clients para facilitar e agilizar o desenvolvimento e entendimento dos consumidores. Que o propósito e possibilidades da API estejam bem descritos, seus recursos, operações, autenticação e autorização, casos de uso e etc.

Os princípios API First são direcionadores que garantem que APIs tenham sua devida importância e sejam tratadas como ativos de negócio. 

Benefícios

Redução de custos no desenvolvimento

Um dos grandes problemas com a abordagem API First é que os consumidores só iniciam a integração quando o backend já está minimamente pronto. O que acaba aumentando o time-to-market. E esse não é o único problema, também temos a possibilidade dessa API não estar modelada conforme esperado, o que pode gerar retrabalho para os times de backend. Uma das principais vantagens do API First é a colaboração entre times. Como as partes interessadas participam da concepção do design da API e o desenvolvimento é iniciado pós definição do contrato, custos são reduzidos pois o tempo de desenvolvimento é otimizado (consumidores não precisam de esperar o backend pois é utilizado conceito de mock a partir do contrato) e com consumidores estratégicos participando desde o início a probabilidade da API ser desenhada conforme os requisitos técnicos e de negócio é muito maior, evitando retrabalho.

Aceleração do time-to-market

Em uma abordagem API First os consumidores estratégicos participam do design da API e podem iniciar o desenvolvimento sem depender totalmente do backend. Após publicação, mesmo potenciais consumidores que não tenham participado terão em mãos uma documentação robusta e autodescritiva. O que acelera o desenvolvimento fazendo com que a entrega de valor seja mais rápida, acelerando o time-to-market.

Experiência do Desenvolvedor (DX) melhorada

A documentação facilitará o desenvolvimento. E a disponibilização de mocks facilita a experimentação. Desenhar a jornada dos consumidores é essencial, e principalmente a fase de onboarding. Aplicando API First garantimos que o onboarding seja facilitado pois a documentação guiará o próprio desenvolvimento através de exemplos, snippets de código, casos de uso e mesmo suporte quando necessário.  No contexto atual falamos muito sobre B2D (negócios para desenvolvedores) e DX (experiência do desenvolvedor) e esses dois conceitos são intrínsecos ao API First.

Minimização dos riscos de falha

Em uma abordagem API First as partes interessadas participam desde a concepção da API, e continuam na fase de feedback (testes), sugerindo melhorias, possibilidades, e tudo isso sendo feito à medida que o time de backend também está desenvolvendo. E continuam fazendo parte após a publicação e durante todo o ciclo de vida da API. É importante ressaltar que as partes interessadas não são apenas consumidores estratégicos, mas também pessoas de negócio, arquitetura, segurança, frontend, backend, operações e etc. Desse modo, riscos sejam de integridade, confiabilidade, disponibilidade ou mesmo em relação aos requisitos esperados têm menor probabilidade de se tornarem um problema. Pois todos os alinhamentos e adaptações necessárias são realizados em tempo de desenvolvimento. 

Divisão de responsabilidades

Na aplicação de API First, são vários perfis envolvidos tanto na concepção quanto no desenvolvimento e posterior operação. Isso faz com que as responsabilidades sejam bem divididas, facilitando e direcionando o trabalho de cada um de acordo com sua expertise e função. Por exemplo, a pessoa de segurança cuidará de aspectos de segurança como definição e validação do PII (personal identifiable information) e LGPD/GDPR; pessoa de backend cuidará dos aspectos de regra/lógica de negócio, pessoa de testes cuidará na pirâmide seja através da automação de testes unitários, de integração e apoio em validações do contrato tanto em aspectos de governança quanto segurança, pessoa de negócio cuidará da parte relacionada a entrega de valor e estratégias/possibilidades comerciais da API e etc. Com as responsabilidades definidas facilitamos o trabalho de cada profissional e incentivamos a colaboração.

Paralelismo de esforços

Com a divisão de responsabilidades temos paralelismo nos esforços. Como já comentado anteriormente, com o paralelismo de esforços além de redução de custos no desenvolvimento conseguimos a partir da concepção do contrato e geração do contrato que consumidores iniciem o desenvolvimento através de mocks/SDKs gerados do contrato e times de backend consigam desenvolver com base na especificação. As correções e ajustes são feitos em tempo hábil e tanto validações técnicas (estrutura e tipo de dados, entidades aninhadas em objetos ou arrays, ou modelagem de recursos e operações) quanto validações de negócio (descrição dos casos de uso, experiência do desenvolvedor, exemplos e estratégia de negócio *go-to-market*) acontecem de forma paralela à medida que o desenvolvimento vai evoluindo.

Reuso

Em uma abordagem API First, a API é concebida com as partes interessadas envolvidas, gerando documentação e processos de desenvolvimento robustos e consequentemente uma API consistente. O processo pode (e deve) ser replicado em outros desenvolvimentos, se lapidando de acordo com o contexto e organização da empresa, podendo assim se tornar uma abordagem viva, colaborativa e que consiga agregar e aculturar sua organização para que se permaneça competitiva no mercado e dinâmica o suficiente para se adaptar a possíveis mudanças. O reuso não é só aplicado no processo de desenvolvimento mas como também pode ser replicado a própŕia API, pois com os contextos e delimitações de negócio bem definidas, a possibilidade de reutilizar a API é alta, fazendo com que ela se torne mais extensível ao negócio. 

Como Implementar?

Assim como qualquer outra estratégia de negócio, a implementação de uma nova abordagem de desenvolvimento não é simples. Precisa de comprometimento e dedicação dos envolvidos, e claro, planejamento! Abaixo, temos recomendações dos principais pontos que devem ser levados em consideração na implementação de uma estratégia de API First.

Levantamento do Inventário de APIs

Frequentemente organizações têm desafios relacionados à governança das APIs. No contexto atual, para construir nossas soluções geralmente utilizamos não somente APIs internas mas também APIs de terceiros, e com a acelerada transformação digital o grande volume de demandas e necessidades de negócio devem ser atendidas rapidamente. Com isso, precisamos tomar cuidado com o conceito de API Sprawl, que é basicamente a proliferação de APIs para atender qualquer necessidade técnica ou de negócio. É inevitável que cada vez mais teremos quantidade maior de APIs trafegando via web, e que APIs são peça-chave para conectar serviços e sistemas. Mas precisamos de uma governança avançada e adaptativa (de acordo com o contexto de cada negócio). Para implementar uma estratégia API First é preciso ter conhecimento do inventário de APIs da organização, tanto APIs internas quanto externas. 

Análises de Dados Produtivos das APIs

Após o levantamento do inventário de APIs, temos visibilidade dos tipos (públicas, internas e restritas), e com isso conseguimos analisar seus dados produtivos e retirar insights de negócio e técnicos para entender o comportamento dos consumidores das APIs, onde a partir disso conseguimos elencar possíveis APIs/negócios suscetíveis ao modelo API First. Aplicar conceitos modernos de observabilidade como open telemetry para padronizar dados distribuídos, framework MELT (metrics, events, logs e traces) para estruturar esses dados, RED (request, error, duration) para acompanhar os dados de telemetria e RUM (real user monitoring) que é um framework que monitora dados de usuários. Esses conceitos são fundamentais para entendermos comportamentos e conseguirmos extrair insights das APIs.

Definir Stakeholders

As partes interessadas são peças fundamentais. Definindo-as, o desenvolvimento da API tende a ser mais assertivo. Consumidores estratégicos poderão participar não só como ouvintes, mas com voz ativa, contribuindo. E possíveis decisões arquiteturais difíceis podem ser profundamente discutidas  e registradas através de ADRs (architecture decision records) em tempo de concepção, garantindo a construção de uma API consistente.

Definir Limites e Contextos de Negócios

A utilização do DDD (domain-driven design) empodera uma estratégia API First pois com o DDD conseguimos focar nos domínios do negócio, definindo-os, delimitando contextos e utilizando uma linguagem ubíqua, para que as partes interessadas (sejam técnicas ou de negócio) consigam facilmente entender e contribuir para o desenvolvimento e/ou evolução de novos negócios. Com os modelos de negócio definidos, a concepção do contrato é facilitada e o desenvolvimento é guiado com base nos contextos de negócio.

Design Especificação API & Style Guide

O contrato estabelecerá padrões e boas práticas para o design das APIs. Quando falamos de APIs REST a especificação recomendada é a OpenAPI. Também é importante que esses padrões e boas práticas estejam descritos de forma clara e transparente (terceiro princípio API First). No style guide é necessário que contenham informações sobre como os times contribuirão para o design das APIs. Definições de status code, versionamento, como lidar com erros e outras boas práticas ou diretrizes da organização são essenciais. O style guide garantirá um design padronizado e seguindo as boas práticas e recomendações tanto de mercado quanto da empresa.

Definir Processos de Governança, Ferramentas e Automações

As ferramentas estão presentes no nosso dia-a-dia justamente para facilitar nosso trabalho. A automação faz parte de qualquer time de qualquer empresa, seja ela de tecnologia ou não. Soluções de IA como Sensedia Copilot podem potencializar a estratégia API First através da geração inteligente de contratos. É importante automatizar todos os testes de unidade e até alguns testes de integração, mas temos que tomar o cuidado para não cair justamente em uma das problemáticas do Code First que é geração automatizada de contratos, que acabam nem sempre sendo condizentes com os requisitos de negócio. Precisamos de uma governança bem definida, em todos os estágios do ciclo de vida das APIs, para garantir também que ela seja adaptativa (de acordo com o contexto de cada negócio).

Criação e Operação do Portal de Desenvolvedores

O portal de desenvolvedores é a porta de entrada para os consumidores das APIs. Então ele deve ter a devida importância. Deve conter recursos modernos de experiência do usuário (UX) e também a navegação deve ser guiada e bem desenhada para que potenciais consumidores tenham a experiência garantida. Isso vale tanto para estratégia de APIs públicas quanto para APIs internas ou restritas, aliando-se ao conceito de engenharia de plataforma.

‍

Considerações

API First é uma abordagem que se torna cada vez mais comum em empresas que estão se transformando digitalmente e querendo se manter competitivas nesse mercado dinâmico. As APIs são ativos de negócio e a estratégia das APIs deve estar alinhada com a estratégia de negócio. Nesse artigo exploramos o que é API First, princípios, benefícios e como implementar. As APIs devem ser tratadas como cidadãos de primeira classe (first-class citizens) e utilizando a abordagem API First é uma das formas de garantirmos que as APIs estão tendo sua devida importância e impactando diretamente novos e existentes negócios nas organizações.

‍