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.

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.

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.)

À 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.