Desenvolvimento de APIs: Design First e Code First

Desenvolvimento
• 20 out 2020

Com a popularidade do desenvolvimento de APIs Rest, surgiu uma grande necessidade no mercado: a integração entre APIs e, consequentemente, a manutenção e a propagação dos contratos envolvidos entre as partes. Chamamos de contrato a comunicação realizada entre duas APIs, onde os dois lados têm acordos de produção e consumo dos dados.

Informada a menção de contratos, agora temos uma nova abordagem de desenvolvimento de APIs, o chamado Design First. Nele, o provedor da API começa a desenvolver sua API pelo contrato. Esse contrato pode ser revertido para os códigos fonte de uma linguagem e acelerar o trabalho do desenvolvedor na construção de serviços.

O Contrato, ou o desenho da API, deve ser independente da linguagem de programação ou idioma e, impreterivelmente, ser legível por humanos e máquinas. Isso para otimizar a adoção e ganhar interoperabilidade entre os aplicativos em torno da API.

Um contrato de API, na especificação OpenAPI (Swagger) seria algo como o exemplo a seguir:

<p> CODE: https://gist.github.com/klyfftoledozup/905782afa584b6488c1553084c1a6c0f.js</p>

‍

Abordagens sobre Desenvolvimento de API

Design First vs Code First

Primeiro o Código (Code First): Com base no plano da regra de negócio definida, a API é codificada diretamente pela equipe de desenvolvimento e, a partir do código, é criada a documentação de contrato que deve ser legível por humanos e máquinas, como um documento Swagger/OpenAPI.

Primeiro o Design (Design First): A regra ou plano de negócios é primeiramente convertida em um Contrato legível por humanos e máquinas e descrita em um formato aberto, como o próprio Swagger e OpenAPI. A partir deste Contrato, são gerados os códigos de Provider e Consumer (Server e Client).

Falando sobre ambas as escolas de pensamento, para desenvolvimento de API, tanto Design e Code first têm em seu cerne o Contrato — ou a geração e, principalmente, a governança do Contrato.

Na abordagem Code first, e que é comum, o desenvolvimento do código acontece logo após o estabelecimento dos requisitos e regras de negócio. Isso porque o código, normalmente o Provider/Server, é escrito antes e, então, é a partir dele (o código) que são gerados o Contrato e a Documentação de API. Esta é passada para quem vai implementar o Consumer/Client. Em seguida, é realizado algum tipo de governança, normalmente de forma desconectada e de difícil manutenção ou reuso, visto que o contrato pode ser alterado no código inicial. Isso acontece sem que o consumidor saiba sobre as mudanças ou, de fato, qual o Contrato da integração em dado momento.

Já na escola que aborda o Design First, é defendida a idéia de que, antes de escrever qualquer linha de código, deve ser feito o desenho e a definição do Contrato da API. Essa linha de pensamento é deveras nova, visto que só pensamos no desenho depois de lutar por alguns anos para manter a interoperabilidade e governança entre nossas muitas APIs. Este movimento tem ganhando força rapidamente, especialmente com o uso dos formatos de descrição da API.

Para entender melhor as duas abordagens, vejamos o processo geral seguido durante o ciclo de vida da API: Como qualquer produto, o conceito da API começa com a equipe de negócios identificando uma oportunidade. A oportunidade é analisada e um plano de capitalização é criado em um documento de texto por estrategistas, analistas e outras pessoas de negócios. Este documento é então repassado à equipe de desenvolvimento, que é quem permite o plano assumir alguma forma tangível.

No gráfico a seguir, ambas as abordagens podem ser vistas de forma simples.

Escolhendo a abordagem correta

Existem vantagens e desvantagens associadas às duas abordagens. No final do dia, a escolha da abordagem correta se resume às necessidades imediatas, estratégicas e tecnológicas, que você deseja resolver com suas APIs. Vamos mergulhar em quando e por que você escolheria a abordagem Design First ou Code First.

Abordagem de Design First

Uma API bem projetada pode fazer maravilhas pela adoção e consumo de suas APIs. E um bom design pode ser melhor alcançado com a abordagem Design First — principalmente se a estratégia de negócio do que você está provendo envolver alta adoção de consumidores diversificados que se integram à sua API. Nisso, será importante uma boa experiência do desenvolvedor.

Um design eficaz da API ajuda seus consumidores finais a entender rapidamente os recursos e as propostas de valor da sua API, reduzindo o tempo necessário para sua integração com a API, aumentando a probabilidade de ter maior valor de reutilização e envolvimento.

A abordagem de Design First é uma excelente oportunidade para colher feedbacks importantes. A possibilidade dos clientes terem acesso a mocks e documentação antes do código permite que eles testem as interfaces e apresentem, de antemão, sua satisfação ou rejeição ao projeto.

É comum que mocks sejam subestimados. Porém, muitas vezes, esforço e tempo são gastos para construir APIs que não fazem sentido para os clientes, resultando em retrabalho e construção de novas versões.

A identificação de falhas no projeto, antes da implementação do código, reduzirá substancialmente seu custo e tempo de implementação.

Apesar dos benefícios citados, esta abordagem está longe de ser perfeita. Não há uma etapa bem definida de projeto (design). O projeto possui um ciclo de vida circular e irá perdurar enquanto o projeto existir. O projeto é um ser vivo que evolui e se transforma. Manter os clientes atualizados das alterações e evoluções, para então novamente validá-las, é um grande desafio.

Ao entregar APIs de missão crítica

O maior motivo para a abordagem Design First é quando o público-alvo da sua API são clientes ou parceiros externos. Nesse caso, sua API é um canal de distribuição essencial que seus clientes finais podem usar para consumir os serviços que você fornece, e um bom design é fundamental para a satisfação do cliente. Essas APIs desempenham um papel crítico na representação dos serviços da sua organização, especialmente em um ecossistema omni-channel, onde a consistência nas informações e o consumo sem problemas é um importante indicador do sucesso dos negócios.

Garantir uma boa comunicação

O contrato da API pode atuar como o rascunho central que mantém todos os membros da sua equipe alinhados com os objetivos da sua API e com a exposição dos recursos dela. A identificação de bugs e problemas na arquitetura da API com sua equipe fica mais fácil com a inspeção de um design legível por humanos. Detectar problemas no design, antes de escrever qualquer código, é uma abordagem muito mais eficiente e simplificada do que fazê-lo depois que a implementação já estiver em vigor.

Abordagem de Code First

É utilizada especialmente quando a entrega é importante. Os desenvolvedores podem começar a implementar a API muito mais rapidamente se começarem a codificá-la diretamente no documento de requisitos. Isso é importante se sua estratégia de entrada no mercado enfatizar velocidade e agilidade como fatores importantes para o sucesso do programa API. O fato de a automação ser muito mais fácil na abordagem de Code First ajuda a fortalecer esse caso, com muitas bibliotecas suportando código do servidor de andaimes, testes funcionais e automação de implantação.

Entretanto, ao priorizar o código fonte e estabelecer que a documentação seja criada quando houver tempo, pode significar que essa documentação nunca venha a existir ou, no mínimo, que seja fornecida tardiamente.

A ausência de documentação pode acarretar vários problemas que, de uma forma ou de outra, irão consumir tempo e dinheiro. São problemas como recursos duplicados ou novas versões dos existentes – simplesmente por não conhecê-los ou não compreender seu funcionamento –, ou erros de integração devido a documentação desatualizada, todos os quais são muito comuns.

Ao desenvolver APIs internas

A abordagem Code First oferece velocidade, automação e complexidade de processo reduzida, ao custo de uma boa experiência do desenvolvedor. Se a API for consumida apenas pela equipe ou empresa de pequeno porte que a está montando, a abordagem Code First é uma solução prática. Isso é especialmente verdadeiro se a API desenvolvida for pequena, com apenas alguns pontos finais, que serão usados apenas internamente.

Resumo sobre as Abordagens

Agora fica claro que em ambas as abordagens existem pontos positivos e negativos — alguns até críticos. A abordagem adotada para o desenvolvimento de suas APIs é vital para determinar como elas são consumidas e mantidas, como será a governança e o reuso das APIs.
Para a escolha da abordagem correta, pergunte-se sempre: