Por que devemos começar nossas APIs pelo contrato?
Tags: apidevelopment, openapi, apigovernance
Published: 2020-07-13 21:40:38

---
title: Por que devemos começar nossas APIs pelo contrato?
published: true
date: 2020-03-24 01:56:24 UTC
tags: apidevelopment,openapi,apigovernance
canonical_url: https://medium.com/@juscelioreis/por-que-devemos-come%C3%A7ar-nossas-apis-pelo-contrato-ee1de70af8b3
---

Após uma década desenvolvendo software consigo afirmar o quanto é mais rápido construir código orientado a contrato (_schema_ se preferir chamar assim). Porem nem sempre concordei com essa afirmação, na verdade faz pouco tempo que entendi qual o real ganho em trabalhar com essa abordagem.

Lembro de ter estudado no mestrado (como aluno especial) SOA (faz uns anos isso). Durante esse tempo o professor que seguia muito a metodologia que está nos livros do Thomas Erl, falava que para construir um serviço devemos começar pelo contrato. Nessa época eu discordava muito pois já trabalhava desenvolvendo serviços a muito tempo, entendia bem o WSDL e Web Services e suas especificações como WS-Basisc, WS-Trust, WS-\* e REST, além de dominar uma tecnologia para construir serviços da Microsoft o famoso WCF (Adorava esse framework).

O que eu não entendia na época, mas entendo hoje, era que minha falta de bagagem, minha pouca experiência profissional e ficar isolado no mundo idealizado por um fornecedor de tecnologia, ignorando outros fornecedores além de não focar meus estudos ao conceito de serviços. Eu entendia que essa abordagem era pouco produtiva, provavelmente você caro leitor também ache isso.

O que eu não entendia na época era que para seguir uma abordagem orientada ao desenvolvimento ou melhor primeiro o código (code-first) é que corremos o risco de fazer um serviço especialista demais, dificultando o seu reaproveitamento ou no pior cenário imaginável uma alteração nesse serviço como uma mudança de um nome, exemplo: mudar **Nmoe** para **Nome** (afinal foi um erro de digitação), pode causar com que serviços consumidores quebrem, chegando ao ponto de sair do ar (serio, já vi isso acontecer com mais frequência que gostaria de confessar).

O que me fez mudar de ideia não foram somente os erros que pude presenciar, mas estudar o ser humano. É muito complicado para que desenvolvedores pensem de forma abstrata, evitando transpor as regras internas do serviço para a sua interface, pois tendemos a pensar de forma intuitiva e automática nesse contexto, levando a simplificações e replicações implícitas de padrões.

> _Podemos estar cegos para o óbvio e cegos também para a nossa cegueira_  
> ― **Daniel Kahneman**

O sistema intuitivo e automático em nossos cérebros é uma ferramenta poderosa e eficaz, mas às vezes é bom olhar para as coisas de outra perspectiva (_Vuja De_). Em vez de olhar o serviço sobre a perspectiva de código, vamos olhar primeiro para o seu contrato, sua interface e a partir dela abstrair o problema.

Para construir APIs precisamos de um ativo muito mais importante e complicado, pessoas!

> Programação é uma atividade social.  
> ― **Robert C. Martin**

Lembro das discussões da época, que programar usando SOAP ([_Simple Object Access Protocol_](https://www.w3.org/TR/soap/)) era obsoleto e muito pesado (não reflete minha opinião) e que o futuro era REST ([_Representational State Transfer_](https://www.w3.org/2001/sw/wiki/REST)). Esse último teve um crescimento incrível na comunidade de desenvolvimento de software. Porem nem tudo que vira padrão é o melhor, rs. Em REST não temos a cultura de pensar no contrato primeiro, para falar a verdade não existe uma especificação de contrato padrão. O mercado acabou adotando a especificação OpenAPI ([_OpenAPI Specification_](https://www.openapis.org/)_ — OAS_) como padrão é um dos mais adotados, mas saiba que existem outras especificações como _RAML (_[_RESTful API Modeling Language_](https://raml.org/)), WADL ([_Web Application Description Language_](https://www.w3.org/Submission/wadl/)).

Padrões como esses que citei acima, como o OpenAPI, ajudam a facilitar uma estratégia de desenvolvimento ‘design first’ ou ‘driven-definition’. Essa abordagem permite que as partes interessadas planejem uma API e sua funcionalidade antes de pensar em implementar o código. As próximas alterações e os requisitos de teste podem ser comunicados mais cedo, pois existe um plano para que todos possam trabalhar. Isso sim! É ganho de tempo, e acelera o desenvolvimento de fato. Existem outros benefícios, segue a lista abaixo:

- Trabalhar orientando ao contrato é uma forma de manter o conhecimento, e olha que a cada dia fica mais complexo do desenvolvimento de software.
- Ocultar a estrutura do banco de dados, além de diminuir a probabilidade de ter campos do banco expostos diretamente na interface do serviço. Melhorando e muito a segurança, e evitando problemas como alterar nome de um campo no banco ser obrigado a alterar o serviço.
- Ao pensar nas entidades de domino, facilita a abstração, permite manobras internas do serviço o que pode contribuir com a resiliência de seu serviço.
- É uma abordagem bem integrada com o TDD (Test Driven Design), melhorando o controle de qualidade da sua aplicação, pois ao alterar o contrato (_Schema_) e aplicar o teste de aceitação poderá pegar erros mais cedo no desenvolvimento.

O interessante é que essa abordagem ajuda na construção de uma governança em cima das APIs. Governança da API fornece uma abordagem orientada a políticas, impondo padrões e pontos de verificação ao longo do ciclo de vida da API ( **olha que lindo isso aqui** ).

A sua fronteira não fica isolada apenas no tempo de execução da API, mas também no design através de processos de desenvolvimento. Inclui as diretrizes, padrões e processos a serem seguidos para identificação da API, **documentação da interface** , desenvolvimento, **teste** , implantação, execução e operação. Os padrões e princípios definidos pela governança da API fornecem garantia de qualidade da API, como segurança, disponibilidade, escalabilidade e confiabilidade.

![](https://cdn-images-1.medium.com/max/1024/1*dkCww0dGQ5Nk7G3tlAkmHg.png)<figcaption>Governança</figcaption>

---

{% user juscelior %}