A importância da documentação de APIs

Como as APIs foram criadas para serem consumidas, é importante garantir que o cliente ou o consumidor possa implementar uma API rapidamente e entender o que está acontecendo com ela. Infelizmente, muitas APIs tornam a implementação extremamente difícil, o que frustra o seu próprio objetivo. Conforme você cria sua API, você deve garantir não só a apresentação de uma documentação informativa da API para ajudar seus desenvolvedores a integrar/depurar conexões, mas também exibir dados relevantes sempre que um usuário faz uma chamada — especialmente uma chamada que apresenta falha.

Apesar de ser extremamente importante ter uma resposta do corpo do texto coerente e bem formatada na documentação da API (o ideal é que ela seja algo desserializado, iterado e compreendido), também é uma boa opção oferecer aos desenvolvedores referências rápidas sobre o que aconteceu com a chamada, inclusive o uso de códigos de status. E, em caso de falha, talvez você queira apresentar mensagens de erro descritivas que informem ao cliente não só o que deu errado, mas também como corrigir o erro.

Planeje-se para a documentação de sua API

Quando você estiver planejando sua API, precisará saber como manterá a documentação dela. Essa é uma área que não deve ser subestimada, já que é comprovadamente o ponto crucial de usabilidade para a maioria das APIs públicas. Embora a documentação possa parecer uma tarefa fácil e rápida, a maioria das empresas informará que ela é um dos maiores desafios e responsabilidades quando se trata de manter as APIs.

A documentação é um dos fatores mais importantes para determinar o sucesso de uma API, já que uma documentação sólida e fácil de entender facilita muito a implementação de APIs, enquanto uma documentação confusa, fora de sincronia, incompleta ou complexa gera uma aventura indesejada — que geralmente faz com que desenvolvedores frustrados utilizem as soluções de um concorrente.

O desafio é que, além de a documentação precisar ter aparência consistente, ela também deve ser consistente com a funcionalidade da API e atualizada com as mudanças mais recentes. Sua documentação também deve ser fácil de entender e ser escrita para desenvolvedores (geralmente, por uma equipe experiente de documentação). Até recentemente, as soluções de documentação incluíam caros sistemas de terceiros, o uso do Sistema de gerenciamento de conteúdo (CMS) existente ou, até mesmo, um CMS dedicado com base em software de código aberto, como Drupal/WordPress. Infelizmente, apesar de as soluções específicas para documentação de APIs oferecerem consistência em relação à aparência da sua API (algo que é mais difícil manter com um CMS), elas ainda dependem de esforços manuais do desenvolvedor (se forem derivadas do código) ou de uma equipe de documentação para mantê-las atualizadas.

No entanto, com a expansão das especificações abertas, como RAML — e as comunidades que a cercam —, a documentação se tornou muito mais fácil. Em vez de tentar analisar comentários de código e fazer com que os desenvolvedores escrevam descrições em linha (geralmente), a equipe de documentação ainda consegue apresentar uma documentação descritiva na especificação da API, com todos os parâmetros/exemplos de código já incluídos, o que facilita a transição para a documentação. E, com a explosão das empresas de software como serviço (SaaS) de documentação de APIs que utilizam e expandem essas especificações, nunca foi tão fácil ou barato criar uma documentação e um API portal eficazes. 

Como escrever uma boa documentação de API

Uma boa documentação deve servir como referência e como uma fonte de instruções, permitindo que os desenvolvedores obtenham rapidamente as informações que estão procurando e, ao ler a documentação, entendam como integrar o recurso/método que estão procurando.

Dessa forma, uma boa documentação deve ser clara e concisa, mas também visual, apresentando os seguintes elementos:

  • Uma clara explicação do que o método/recurso faz
  • Chamadas que compartilham informações importantes com os desenvolvedores, inclusive erros e avisos
  • Um exemplo de chamada com o corpo do texto do tipo de mídia correlacionado
  • Uma lista dos parâmetros usados nesse recurso/método, bem como os tipos deles, a formatação especial, as regras e se eles são necessários ou não
  • Um exemplo de resposta, incluindo corpo do texto do tipo de mídia
  • Exemplos de código de várias linguagens, incluindo todos os códigos necessários
  • (por exemplo, Curl com PHP, bem como exemplos de Java, .Net, Ruby etc.)
  • Exemplos de SDK (se SDKs forem fornecidos) que mostram como acessar o recurso/método utilizando o SDK da linguagem
  • Experiências interativas para experimentar/testar chamadas de API (API Console, API Notebook)
  • Perguntas frequentes/cenários com exemplos de código
  • Links para recursos adicionais (outros exemplos, blogs etc.)
  • Uma seção de comentários em que os usuários possam compartilhar/discutir códigos
  • Outros recursos de suporte (fóruns, formulários de contato etc.)

Ferramentas de documentação de APIs

Um dos principais benefícios do desenvolvimento orientado por especificações é que, em vez de ter que depender de fornecedores caros e complexos — ou de tentar criar uma solução pontual de documentação de APIs com base em um CMS como WordPress ou Drupal —, as especificações como RAML, Swagger e API Blueprint têm sólidas comunidades de código aberto que as cercam e que oferecem para uso ferramentas de documentação criadas previamente. Cada uma delas oferece seu próprio conjunto de ferramentas exclusivo; mas, neste relatório, nós nos concentraremos nas ferramentas disponíveis na comunidade de RAML. A comunidade de RAML já reuniu analisadores de várias linguagens diferentes, como Java, Ruby, PHP e Node, bem como scripts completos para gerenciar a documentação de APIs e, ao mesmo tempo, oferecer ambientes interativos como API Console e API Notebook. Essas ferramentas ajudam você a apresentar uma documentação como exibido nos exemplos de ReadMe.io, Constant Contact e Twilio acima, com pouco ou nenhum trabalho de sua parte (a não ser a instalação e, obviamente, a definição da RAML). Aqui, você pode encontrar várias ferramentas e fazer download delas livremente.

À medida que as empresas reconhecem o valor cada vez maior das APIs, elas estão começando a desenvolver centenas delas. A capacidade de publicá-las devidamente de uma forma em que o desenvolvedor que as consome possa encontrá-las, pesquisá-las e entendê-las facilmente será um aspecto importante que avançará ou prejudicará todo o seu programa de APIs. Uma boa documentação é uma parte importante disso.