Documentação de APIs: Como escrever e exemplos!

O que é documentação de APIs?

Documentação de APIs é um conjunto de instruções que informam aos desenvolvedores e a outras partes interessadas como usar a sua API e seus serviços para um fim específico. Ele geralmente contém exemplos de código, tutoriais e detalhes sobre suas funções, classes e tipos de retorno. Ele fornece essencialmente aos desenvolvedores todas as informações de que precisam para construir integrações com a API e fazer chamadas de API com o software.

Chamadas de API são um tipo de pedido feito pelo desenvolvedor de terceiros para a API da plataforma. As chamadas API estão descritas na documentação e dizem ao desenvolvedor exatamente o que eles podem pedir para a API fazer e como.

A documentação da API explica claramente seus endpoints, interpreta o porquê de você querer usá-los, e dá muito exemplos específicos de como você gostaria de usá-los.

APIs são importantes porque significa que os desenvolvedores não precisam continuar desenvolvendo as mesmas soluções de software do zero. Com as APIs é possível que os desenvolvedores possam aproveitar outras plataformas que já foram criadas e integrar suas funcionalidades em seus próprios programas. Muitas plataformas grandes têm APIs, incluindo Twitter e GitHub.

Tipos de API

Para a equipe

Você pode ter uma API que é interna para sua empresa e, portanto, destinada a ser usada apenas por membros de seu time. A finalidade deste tipo de API seria simplificar a transferência de dados entre as equipes e sistemas, portanto, os desenvolvedores internos da sua empresa são os responsáveis pelo uso dessa API.

Para os Parceiros

APIs de parceiros são compartilhadas fora da organização, mas apenas com aqueles que têm uma relação de negócios com a empresa que fornece a API. Apenas clientes autorizados têm acesso à API e como consequência as medidas de segurança tendem a ser mais rigorosas com este tipo de API.

Para os usuários finais

APIs para usuários finais ou as APIs abertas podem ser usadas por qualquer desenvolvedor sem restrições. Esses tipos de APIs não possuem autenticação particularmente rigorosa e medidas de autorização porque os fornecedores querem que a API seja adotada pelo número de desenvolvedores máximo possível. Às vezes, este tipo de API estará disponível por uma taxa de assinatura que é escalonada dependendo do número de chamadas de API realizadas.

Quem escreve a documentação API?

Naturalmente, como os desenvolvedores são os que constroem as API, eles são frequentemente encarregados de escrever a documentação. Infelizmente, a documentação impulsionada pelo desenvolvedor pode muitas vezes ser excessivamente técnica porque os desenvolvedores estão muito perto do assunto. A documentação escrita pelos desenvolvedores também pode cair no esquecimento, pois os desenvolvedores estão realmente focados na construção e realização da manutenção da API.

Por esta razão, muitas empresas empregam escritores técnicos profissionais para criar a documentação da sua API. Escritores técnicos têm a capacidade técnica de entender a API e as habilidades criativas para ser capaz de escrever conteúdo envolvente para usuários finais que são desenvolvedores.

Os desenvolvedores de API fornecem ao escritor técnico as informações de que ele precisa para documentar a API precisamente. Se houver alguma parte em falta na documentação, os desenvolvedores podem ajudar o escritor técnico a preenchê-los, terndo como o resultado final um documento claro e acessível ao seu público alvo.

Além disso, confira nosso artigo sobre Como criar uma experiência encantadora de desenvolvedor de API com a documentação

Benefícios da documentação API

Para provedores que queiram oferecer uma API, o desenvolvimento da documentação pode ter muitos benefícios importantes para sua organização.

Melhore a experiência do desenvolvedor da API

Em primeiro lugar, a documentação da API melhora a experiência do desenvolvedor. Não importa o quão boa a sua API é se potenciais desenvolvedores não entenderem como usá-lo. Uma boa documentação da API ajuda os desenvolvedores a compreender os diferentes pontos de extremidade que tem para oferecer e exemplos de casos de utilização específicos. A partir do momento que você melhora a experiência do desenvolvedor, você também aumenta o número de potenciais usuários que você é capaz de atrair para o seu produto.

Com isso, é possível reduzir o tempo gasto com desenvolvedores internos de integração ou parceiros externos. Uma boa documentação da API significa que suas equipes de suporte e sucesso precisam gastar menos tempo integrando novas equipes internas de desenvolvedores ou parceiros externos. Novos usuários da sua API têm todas as informações de que precisam para começar com a sua plataforma e trilhar uma experiência de sucesso. Quando os processos são documentados, ele remove a necessidade para que determinados membros da equipe possam intervir.

Atualizações eficientes de manutenção de produtos e atualizações mais rápidas

Quando você documenta a sua API efetivamente, isso significa que você pode gerenciar a manutenção do seu produto e atualizá-lo mais rápido. Com a documentação da API, você sabe exatamente o que seu produto se destina a fazer e como deve ser feito para ajudar usuários finais. A documentação lhe dá uma visão mais íntima da API e permite que você amplie mais rapidamente atualizações que serão adotadas pelos usuários.

Ajuda tanto usuários internos como externos a ampliar a API e suas capacidades

Um dos principais benefícios da documentação de API é que ela ajuda os usuários internos e externos a entenderem a API, o que ele pode ser usado para e como você pode implantar a API nos seus próprios fins. Se você não explicar o potencial dos recursos da API então os novos usuários não saberão como usá-la e você enfrentará uma adoção lenta de produtos. Usuários potenciais de uma API usam a documentação como uma forma de tomar a decisão de usar ou não o seu produto.

A fonte de referência para os membros da equipe consultarem as metas da API

Os membros internos da equipe da sua organização podem consultar a documentação da API quando quiserem familiarizar-se com os objetivos da sua API. Mesmo aqueles que não estavam diretamente envolvidos na construção da API ou escreveram a documentação entenderam a finalidade da API e poderão apoiar o trabalho da equipe de desenvolvimento da API.

Permite identificar erros rapidamente e problemas

Quando você documenta a API, isso permite que você identifique rapidamente bugs e problemas como resultado do teste da API para documentar todos os seus recursos. Se a sua API não funcionar como projetado, este feedback pode ser transmitido para a equipe de desenvolvimento da API que pode tomar medidas para corrigir quaisquer problemas. O resultado é mais profissional e torna a API eficaz que funcionará como esperado.

A estrutura da documentação da API – Design e função

Um esboço

O contorno da sua documentação da API é também conhecido como a visão geral. Ela contém um resumo da API e de seus propósitos e pode informar aos potenciais usuários sobre os benefícios de usar esta API sobre outros.

Tutoriais

Os tutoriais formam a parte principal da API e seu objetivo é ensinar aos usuários o conceito da API e como usá-la eficazmente. Geralmente, ele contém guias passo-a-passo sobre como integrar a API e o que o funcionamento adequado deve parecer.

Autenticação

Autenticação é como o provedor mantém os dados da API seguros para desenvolvedores e usuários finais, e assim poderá ter vários esquemas de autenticação. A documentação da API explica cada método de autenticação para os usuários entenderem como acessar a API.

Definição de endpoint

As definições de endpoint da API são o ponto no qual a API se conecta com o programa de software. O ponto em que a API interage com outro sistema é considerado o ponto de extremidade e pode incluir uma URL do servidor ou serviço.

Status e códigos de erro

Os códigos de status e de erro são usados por APIs para informar aos desenvolvedores quando a API não está sendo executada como esperado, ao lado de uma descrição do status ou erro. Eles podem conter instruções sobre como prosseguir e resolver quaisquer erros que venham a ser detectados.

Exemplos

Quando os usuários entenderem como a API funciona, é bom dar-lhes exemplos que mostrem exemplos de sucesso de chamadas, respostas, manipulação de erro e outras operações que elas podem encontrar ao usar a API.

Glossário

Em vez de explicar todos os termos técnicos durante a sua documentação, você pode vincular a um glossário que fornece definições de termos, esquemas e mais.

Como escrever sua primeira documentação de API

Reconhecer a audiência

Antes de começar a criar qualquer tipo de documentação da API você deve se certificar de que entende a audiência desejada para o seu produto. Você precisa saber exatamente em que tipos de usuários você deseja se concentrar, entender os benefícios que eles obterão da API e da maneira como usarão a sua documentação no campo.

É importante lembrar que o seu potencial público para a sua documentação da API pode ser normalmente dividido em dois grupos. O primeiro é os desenvolvedores que terão interações diretas com a API e a usarão ativamente e precisarão de mais documentação de acordo com as linhas de tutoriais e exemplos de código. O segundo público é composto por líderes técnicos e gerentes de produtos que avaliarão a API e como ela se alinha com os objetivos do negócio.

Criar um mapa de jornada do usuário

Quando os usuários estão interagindo com a documentação da sua API, podem estar em um dos muitos estágios da jornada do usuário. Usuários que estão avaliando a sua API pela primeira vez precisarão de documentação para informar exatamente o que sua API pode fazer e quais problemas ela resolve, bem como definições de funções e endpoints, e como sua API é diferente de outros provedores lá fora.

A criação de um mapa de jornada do usuário permite que você atenda os usuários que estão em diferentes estágios e fornecem uma melhor experiência do desenvolvedor. Desenvolvedores receberão suporte a cada passo do caminho, em vez de se perguntar o que a sua API pode fazer por eles.

Comece com Diretrizes para Cenários Comuns

Existem algumas funções mais comuns para qual a sua API será utilizada e você terá que criar diretrizes para esses cenários. Você deve se certificar de que irá endereçar casos típicos de uso da sua API para que novos desenvolvedores possam entender como utilizar corretamente a API. Cada caso de uso deve ter uma seção separada e incluir uma mensagem de exemplo em cada uma delas.

Fornecer diretrizes para cenários comuns ajudará seus desenvolvedores a colocarem o seu objetivo para funcionar sem precisar passar por sufocos. Ele também mostra aos desenvolvedores do que a sua API é capaz e pode persuadi-los a escolher sua API sobre outros.

Adicionar amostras de código

Adicionar exemplos de código à sua documentação de API ajuda os desenvolvedores a começarem rapidamente testando a sua API e compreenderem todo o seu potencial. Cada endpoint deve vir com suas próprias amostras de código para os desenvolvedores poderem personalizar o código para atender à especificação exata e testar as funções mais importantes da endpoints.

Amostras de código mostram aos desenvolvedores em potencial como a sua API funciona e torna mais fácil para eles começarem porque eles podem simplesmente copiar e colar o código. Você pode incluir amostras de código em todas as diferentes programações idiomas a sua API está disponível.

Mensagens de erro e status de códigos

Mensagens de erro e status de códigos devem ser incluídos na sua documentação porque eles informam aos seus desenvolvedores quando eles tiverem ou não efetuado uma chamada de API bem-sucedida. Cada mensagem ou código deve conter uma breve descrição do porquê ele está sendo exibido para que os usuários possam entender o que está acontecendo quando interagem com o sistema.

Descrições que vêm juntamente com mensagens de erro devem ser construídas com o propósito de mostrar aos usuários como resolver os problemas sozinhos. Elas devem ser detalhadas e específicas para que os usuários possam entender por que o sistema está retornando um erro.

Mantenha sua documentação atualizada

Depois de publicar a sua documentação pela primeira vez, você precisa se certificar de revisitar regularmente para manter seu conteúdo atualizado. Não há nada que atrapalhe mais os potenciais usuários da sua API do que uma documentação incompleta ou imprecisa.

Sem manter uma documentação eficaz ao longo do tempo, os desenvolvedores não poderão usar a sua API e você experimentará uma queda na adoção. Toda vez que você faz uma atualização ou publica um novo recurso, isso deve ser refletido na documentação e ser considerado uma parte essencial do envio da sua API.

Práticas recomendadas de Documentação da API

1. Adotar uma linguagem clara

Ao escrever a documentação da API, você não estará ciente do nível de experiência que os usuários da sua documentação terão. É por isso que é importante usar uma linguagem clara e simples para que todos possam entender.

2. Incluir documentação de referência

Documentação de referência de APIs é uma lista completa de objetos e métodos expostos pela API, junto com uma descrição de como usar cada uma. Isso ensina aos desenvolvedores sobre tudo o que está disponível e como funciona.

3. Implementar exemplos

Você deve usar exemplos de como sua API funciona o mais frequentemente possível, que podem ser encontrados em qualquer parte de referência da sua documentação. Eles podem ser qualquer coisa que ilustra o conceito da API e ajude os desenvolvedores a começarem com suas próprias chamadas de API.

4. Coloque alguém responsável pela documentação

Você precisa de alguém da sua equipe cujo trabalho é para supervisionar a experiência do desenvolvedor da sua documentação de API. Isto pode ser o trabalho deles em tempo integral se eles forem um escritor técnico ou uma responsabilidade de meio período se também forem um desenvolvedor.

5. Abordagem múltipla de tópicos e tipos

Você precisa se certificar de que a sua documentação da API é abrangente e que abrange referências, guias, e exemplos. Se certas áreas estiverem faltando, você usará essas informações para decidir onde concentrar esforços no futuro.

6. Incorpore a documentação em processos

A sua documentação e a sua API devem se desenvolver em conjunto. Com a evolução da API, vem o desenvolvimento da sua documentação, especialmente juntamente com novos lançamentos de recursos. Automatize o máximo que puder e economize tempo com sua documentação.

7. Forneça guias de início rápido

Guias rápidos são a melhor maneira de integrar novos desenvolvedores na sua API e fazê-los começar a usar sua API. Eles contêm instruções sobre como usar sua API, bem como codificar amostras que fazem acesso ao seu API muito mais fácil.

Melhores exemplos de documentação da API

Aqui estão alguns exemplos de documentação da API na prática que você pode usar para inspirar seus próprios esforços.

GitHub API

A API do GitHub é uma API REST que desenvolvedores podem usar para se conectar com a plataforma GitHub, que é uma ferramenta de desenvolvimento colaborativo para projetos de software. O GitHub oferece uma documentação completa de início rápido para ajudar os desenvolvedores a lidar com a API e seções detalhadas para cada aspecto do uso da API.

Documentação da API da Twilio

A API da Twilio é outra API REST que os desenvolvedores podem usar para se conectar com a plataforma Twilio, um plataforma de engajamento de clientes que capacita as empresas a se comunicarem em escala. A documentação contém tudo que você precisa integrar com o Twilio, incluindo a autenticação com HTTP e SDKs.

Documentação da API do Dropbox

A API do Dropbox permite que desenvolvedores criem integrações com a plataforma de compartilhamento de documentos do Dropbox. Oferece componentes pré-construídos que ajudam os usuários a incorporar componentes do Dropbox, juntamente com uma referência da API para habilitar desenvolvedores para construir integrações e aplicativos personalizados. Ele também oferece vários SDKs oficiais para popular linguagem de programação.