Neste post escrito pelo dev da empresa Take Blip, Manoel Júnior, você acessa dicas de práticas e ferramentas de documentar APIs de maneira mais eficiente. Acompanhe!
Vivemos em um mundo digital cada vez mais integrado e conectado, com diversos serviços comunicando-se entre si e trazendo uma vasta quantidade de recursos e funcionalidades que aprimoram a experiência do usuário final na utilização de algum produto ou serviço.
A maneira mais usual de um sistema de TI possibilitar a integração e oferta de seus serviços é por meio de uma API (Application Programming Interface), que é um conjunto de rotinas e padrões que possibilitam a troca de informações entre sistemas variados e integram serviços, empresas, negócios e parceiros.
Uma integração bem sucedida passa pelo esforço de desenvolvedores e desenvolvedoras que criam soluções visando a plena comunicação entre os sistemas envolvidos.
Uma API bem construída deve facilitar este processo, para isso é preciso aprender como documentar API da maneira correta. O objetivo é apresentar uma documentação que permita que qualquer pessoa, que ainda não tenha pleno conhecimento do domínio da sua aplicação, desenvolva tais soluções de maneira rápida, eficaz e autônoma.
Como documentar API: primeiros passos
Nesse sentido, engajar devs é decisivo para o sucesso de sua API, e a documentação API é a principal ferramenta em que eles e elas se apóiam para utilizá-la — daí sua grande importância.
Sem documentar API de maneira adequada, a pessoa que vai utilizá-la perde tempo tentando desvendar seu funcionamento, o que cria barreiras para a adoção do seu serviço.
A API documentation deve ser bem completa e seu foco principal deve ser nos recursos e endpoints disponíveis.
A seguir, um passo a passo do que não pode faltar ao documentar API. Enumere-os e forneça informações como:
- Descrição da funcionalidade provida
- Parâmetros de entrada — aqui, é importante especificar quais são obrigatórios e quais são opcionais, bem como o tipo do valor esperado para cada um. Da mesma maneira, é importante deixar clara a forma como o valor é recebido (por querystring, pelo cabeçalho ou corpo da requisição, etc.)
- Formato da resposta (e.g. JSON, XML, etc.)
- Requerimento ou não de autenticação
- Limitação de uso
- No caso de uma API baseada no protocolo HTTP, especificação os métodos aceitos pelo endpoint
- Descrição dos possíveis retornos, tanto em caso de sucesso quanto os possíveis valores de erro — especifique, além dos códigos de erro, uma descrição que deixe claro o motivo pelo qual a requisição não pode ser atendida.
Abaixo apresentamos uma imagem da documentação API do Twitter.
O endpoint em questão retorna tweets públicos que correspondem a um ou mais filtros especificados. Perceba que é fornecida uma descrição textual do recurso, além de ser claro quais são os verbos suportados.
A URL do recurso é fornecida em destaque, bem como as informações sobre ele. Perceba que cada parâmetro é descrito em uma tabela contendo nome, se é ou não obrigatório e sua descrição.
Outra boa prática para documentar API é disponibilizar exemplos de uso, com modelos de requisições que possam ser utilizados facilmente. Se possível, mantenha um sandbox para que testes de integração possam ser feitos adequadamente e forneça informações sobre este ambiente na documentação.
De nada adianta construir uma boa documentação API se ela não é facilmente acessível. Disponibilize o documento em um ambiente de fácil acesso, como uma página web por exemplo.
Documentação API interativa
Até aqui, discutimos o processo de documentar API para a elaboração de um documento propriamente dito. Entretanto, em adição à documentação textual, existem hoje diversas ferramentas que permitem de maneira fácil a construção de interfaces de interação com sua API.
Essas ferramentas permitem testar as funcionalidades rapidamente e sem a necessidade de criar códigos. Aqui, vamos focar no Swagger, mas existem outras ferramentas de propósito parecido, como API Blueprint e RAML.
Swagger
O Swagger é uma poderosa ferramenta que ajuda devs a projetar, desenvolver, documentar e consumir serviços web RESTful.
Apesar de ser conhecida principalmente por sua interface Swagger UI, o software inclui suporte para:
- documentação API automatizada;
- geração de código;
- testes.
É uma ferramenta amplamente utilizada aqui na empresa Take Blip, em função de sua fácil integração com o código fonte. Ao mesmo tempo em que a API é criada, é possível documentar a API adicionando anotações no código fonte.
Existem 3 formas de documentar API pelo Swagger:
- Codegen: ao ser executado, o Swagger converte as anotações presentes no código fonte das APIs em documentação. A imagem abaixo mostra como essas anotações são feitas em um código escrito em C#.
- Automaticamente: permite gerar a documentação automaticamente ao mesmo tempo em que a API é desenvolvida.
- Manualmente: o próprio desenvolvedor ou desenvolvedora pode escrever de forma livre as especificações de sua API e publicá-la posteriormente.
Um bom exemplo de como funciona um servidor Swagger pode ser encontrado aqui. Este é um exemplo baseado em uma API de petstore e contempla:
- modelos;
- endpoints com diversas ações;
- autenticação.
A imagem abaixo mostra uma parte da interface do Swagger UI com os endpoints disponíveis.
Ao clicar em cada um deles, é possível executar a requisição preenchendo os parâmetros clicando no botão “Try it out”.
Note que ao final da página encontram-se os modelos das entidades envolvidas na API, contendo seus atributos com seus respectivos tipos. Dessa forma, a pessoa que utiliza esta documentação API sabe exatamente o que esperar nas respostas e o que enviar nas solicitações.
Como podemos perceber, existem diversas formas de manter uma API com um bom nível de documentação. Uma dica é se preocupar com este aspecto logo em sua concepção, para que o desenvolvimento da documentação e da API caminhem juntos.
Investir em interatividade, como vimos com o Swagger, é muito benéfico para as pessoas que desejam utilizar sua API, pois faz com que a integração seja mais dinâmica, rápida e de melhor qualidade.
E finalmente, mas não menos importante, após documentar a API é ideal “testa-la” para averiguar a sua capacidade de explanação.
Procure, se possível, pessoas que não participaram do desenvolvimento e obtenha feedbacks sobre o olhar delas para com a documentação e identifique as possíveis dúvidas e empecilhos que podem surgir.
Seguindo estas dicas e utilizando ferramentas adequadas para documentar API, é bem provável que seus parceiros e clientes irão obter uma boa experiência na integração com seus serviços, fazendo com que sua API tenha êxito em seu propósito.
Tem interesse em assuntos 4Devs? Então assine nossa newsletter e receba atualizações quinzenais sobre TI, inovação e mais temas!
Referências: iMasters, Sensedia, Wikipedia, I’d rather be writing, Sensedia
