No segundo semestre de 2022 tive a oportunidade de participar de dois cursos de Technical Writing com a Mari Moreira: o primeiro curso era introdutório à área de documentação técnica, abordando agilidade, Scrum e processos de documentação. E o outro foi focado em documentação de API.
O timing foi ótimo, pois estou atuando com produtos que possuem API e o curso foi importante para sedimentar alguns conceitos que estava vendo no dia-a-dia, além de proporcionar subsídios para propor novos modelos de documentação de API no contexto em que atuo.
Além das aulas on demand do curso, tivemos uma oficina para a criação de um case de documentação de API, que serviu para consolidar os conhecimentos, tirar dúvidas e trocar experiências com os colegas.
O resultado da oficina está em meu Github: https://github.com/ligiadf/TheCatAPI/blob/main/imagens.md
Mas… e o que são APIs, mesmo?
Na sigla em inglês significa “Interface de Programação de Aplicação”, e é um padrão de comunicação entre dois sistemas, permitindo consultar ou adicionar dados sem acessar uma página web ou o banco de dados diretamente.
As APIs podem ser públicas, internas ou de parceiros.
Um dos principais tipos de API são do tipo REST, que, na verdade, são diretrizes para a comunicação entre aplicação e o servidor, como o uso de cache e de OpenAPI para a documentação.
A estrutura básica de uma API pode ser resumida em três pontos principais: autenticação, requisição e resposta.
A autenticação define a forma como é realizado o acesso à API. Existem diferentes tipos como: autenticação básica (usuário/senha), bearer token, API key e até sem autenticação, em geral utilizada para APIs internas.
Requisição e resposta podem ser resumidas na imagem a seguir:
Sendo que a requisição possui diferentes elementos como o recurso, protocolo, método, parâmetro e endpoint.
Endpoint é o endereço da requisição que agrupa todos os demais elementos, exemplo:
GET https://servidor.com.br/transactions/{client_id}
Já a resposta, em APIs do tipo REST, costuma ser um conjunto de dados em formato JSON e um código de status (por exemplo, 200 para sucesso).
De forma resumida: através de uma API é possui consultar, adicionar, atualizar e excluir dados de um determinado recurso em uma aplicação.
Leave a Reply