Conhecendo as APIs
Acessando a documentação
A maioria das APIs do portal possuem documentação públicas, independentemente se precisam ou não de autenticação para utiliza-las. Assim, para conhecer a documentação de uma API o usuário poderá acessar de duas formas: Pelo menu principal (Figura 1) ou através dos Cards expostos na página principal conforme mostrado na Figura 2:
Figura 1 Menu de Documentação do menu principal.
Figura 2 Cards das APIs do portal
Tanto a Figura 1 como a Figura 2, apresentam pontos de acesso (respectivamente link e botão) que ao serem clicados, redirecionam o usuário para a página de documentação.
Entendendo a documentação
A documentação de APIs do portal seguem o padrão ReDoc que se trata de um padrão aberto que permite gerar automaticamente a documentação de uma API a partir de um arquivo JSON 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.
