Conhecendo as APIs

Acessando a documentação

Figura 1 Catálogo de APIs no menu Documentação.

Figura 2 Cards das APIs do portal

Entendendo a documentação

A documentação das APIs do portal é renderizada pelo Scalar, uma ferramenta aberta que gera automaticamente a documentação de uma API a partir de um arquivo nos padrões OpenAPI. Assim todas as APIs do portal do desenvolvedor do Banestes apresentam a mesma estrutura de documentação, facilitando a leitura do usuário. Observe a Figura 3:

Figura 3 Estrutura de documentação de API

De acordo com a figura anterior, é possível ver a estrutura da documentação da API composta por 4 seções:

A seção 1, diz respeito aos serviços que estão disponíveis nesta API. Geralmente eles aparecem categorizados, ou agrupados em serviços e abaixo de cada categoria segue os subitens representando o serviço propriamente dito. É importante lembrar que quando se diz aqui “serviço” isto quer dizer que cada subitem está associado a um endpoint único (URL da API) que é destacado pelo seu verbo (GET, POST, PUT ou DELETE).

As seções 2, 3 e 4 são conteúdos que serão apresentados de acordo com subitem selecionado no menu. A seção 2 apresentará uma explicação sobre o serviço, bem como os parâmetros que devem ser informados ao chamar o endpoint a partir da aplicação, juntamente a isto, a seção 3 apresentará os possíveis retornos em caso de sucesso ou erro, e o que eles podem presentar e, em ambas as seções, são também especificados os formatos e tipos de valores apresentados em nível de codificação.

Por fim, a seção 4 apresenta a URL do endpoint e exemplos de código que podem ser utilizados tanto para envio da requisição como retorno esperados, permitindo assim, auxiliar o desenvolvedor na implementação das chamadas destes serviços dentro da aplicação que está sendo desenvolvida.