Como Visualizar a Documentação de uma API
Acessando a documentação
A maioria das APIs do portal possuem documentação pública, independentemente se precisam ou não de autenticação para serem utilizadas. 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:
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 no portal segue 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:
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, seguem os subitens representando o serviço propriamente dito. É importante lembrar que quando aqui se diz “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).
Para entender melhor sobre do que se trata os termos mencionados, é fortemente recomendável que o usuário leia as FAQS: O Que são APIs? e Quais tecnologias preciso conhecer para utilizar as APIs do Portal do Desenvolvedor?.
As seções 2, 3 e 4 são conteúdos que serão apresentados de acordo com o 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 isso, a seção 3 apresentará os possíveis retornos em caso de sucesso ou erro, e o que eles podem apresentar 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 retornos esperados, permitindo assim, auxiliar o desenvolvedor na implementação das chamadas desses serviços dentro da aplicação que está sendo desenvolvida.