Olá pessoal, continuando com a nossa série de artigos sobre APIs, agora vamos tratar do seguinte questionamento que foi feito no primeiro artigo desta série: “Que tipo de documentação temos que fazer para os desenvolvedores poderem entender e consumir os serviços das APIs? Open API?”

Quando falamos de APIs, na essência já estamos falando sobre padrões. API, em tradução livre para o português, é Interface de Programação de Aplicações, e isso significa que existe uma camada de comum entendimento que facilitara a comunicação para a utilização dos serviços de tecnologia por um terceiro. Infelizmente o “comum entendimento”, foi entendido de várias formas diferentes pelas empresas, cada uma criou a sua própria documentação de API, que fácil ou difícil, isso não vem ao caso agora.

Um exemplo corriqueiro que vai te ajudar a entender melhor o problema: Eu, desenvolvedor de aplicativos WEB, quero consumir os serviços de pagamento de cartão de crédito de uma empresa X, ou seja, quero fazer uma integração entre os meus serviços e os serviços desta outra empresa. Os serviços desta empresa têm um conjunto de APIs, que eu devo entender para poder fazer a integração dos serviços. Essa empresa escreveu a documentação dessas APIs em um padrão, esse padrão foi ela mesmo que definiu, depois de vários telefonemas e e-mails entre mim e os desenvolvedores desta empresa, eu entendi as APIs e comecei a fazer a integração. Mas um dia, eu precisei fazer uma outra integração com uma outra empresa, agora eu preciso integrar com os serviços de pagamento, de um banco bem famoso na região. Para a minha surpresa, o padráo de documentação das APIs destes serviços é totalmente diferente da outra empresa que eu fiz integração anteriormente. Apesar de serem APIs, um cliente usou um padrão e o outro usou um outro padrão, dificultando muito a minha vida no processo de fazer as integrações.

Esse terrível problema relatado anteriormente era e é muito comum ainda, e por isso foi iniciado por especialistas do mercado um projeto com o fim de criar um padrão único para se descrever as REST APIs. O resultado recebe o nome de OpenAPI Iniciative (OAI), é um padrão de indústria para descrever as suas APIs. É um padrão open source, neutro de fornecedores e portável. Sua sintaxe é muito simples, usando o formato YAML ou JSON, sendo o primeiro preferível, por ser bem compreensível por pessoas que não são do meio técnico, ajudando a corroborar com a proposta do OpenAPI, que é facilitar o processo de comunicação entre as partes.

Abaixo temos um exemplo de uma API descrita usando o OpenAPI, versão 3.0, no formato YAML.

Abaixo está a documentação gerada a partir do que foi descrito em YAML.

Não precisa ser um expert em OpenAPI para ver o quão fácil é ler o que foi descrito em YAML ou no que foi gerado pela documentação. Agora imagine você, no papel do desenvolvedor da empresa X que precisa consumir os serviços da especificação, mostrados nas imagens anteriores, da empresa Y. Me responda, será fácil ou difícil compreender a proposta desta API?

Mas não é só o problema relatado anteriormente que o OpenAPI resolve, quando falamos FÁCIL COMUNICAÇÃO, envolve TAMBÉM dentro da própria empresa. Imagine você em um papel de PO (Product Owner), ou BA (Business Analyst), que precisa saber se as especificações construídas pelos desenvolvedores de APIs estão corretas, se estão em conformidade com o que foi requerido. Certamente você vai entender facilmente, as entradas e saídas das APIs, garantindo o alinhamento entre o negócio e o time de desenvolvedores, e vice-versa, pois o time também vai ter essa garantia.

Um desenvolvedor de APIs SEMPRE deve começar pela especificação. NUNCA inicie o processo diretamente no código fonte. O OpenAPI, ajuda e garante que quem está pedindo um novo requisito, tenha uma noção exata do que vai ser entregue. Quanto um PO olha a documentação gerada pela especificação, ele já está vendo a documentação que vai ser disponibilizada no Portal do Desenvolvedor, para que os clientes possam utiliza-la. Se o PO gostou e validou a especificação, fica claro e objetivo para o time de desenvolvimento poder iniciar o processo de codificação das APIs, inclusive utilizando geradores de códigos que usam o OpenAPI como entrada de dados.

Na minha humilde opinião, são poucas coisas construídas por nós da tecnologia, que conseguiu atender simultaneamente departamentos diferentes, resolvendo velhos problemas, como por exemplo os problemas de COMUNICAÇÃO.

Sobre a pergunta feita no primeiro parágrafo, a minha resposta é DEVEMOS usar o OpenAPI. Os motivos são inúmeros, mas as palavras FACILITAR A COMUNICAÇÃO deve sempre ecoar na sua cabeça, para que no seu planejamento de implantação de um Gerenciamento de APIs, isso deve ser critério chave. Todo gestor, arquiteto de software ou programador deve se preocupar com as saídas do seu resultado. Se estou criando APIs, qual é a primeira coisa que vai ser objeto de contato pelo seu cliente, que quer consumir os serviços dessas APIs? Se você pensou uma lista XML/JSON, você está completamente equivocado. A primeira coisa que o seu cliente vai ter contato é a documentação que descreve os serviços das APIs. Se essa documentação é pobre, elegível ou utiliza um padrão que o seu cliente nunca viu antes, um problema de COMUNICAÇÃO está começando a se iniciar. Por isso, a saída: documentação que descreve as APIs, devem ter total atenção por todos, lembrem-se disso, evitem dores de cabeça desnecessárias.

Para conhecer mais sobre a especificação, segue links:

https://github.com/OAI/OpenAPI-Specification

Vejo vocês no próximo artigo da série, até mais.

Cleison Melo

Founder and Instructor Estía Training