O sucesso de suas APIs, independente do público principal ser técnico ou de negócio passa por uma documentação bem elaborada, transmitindo seu valor ao negócio de forma clara e sua utilização acessível, ajuda novos usuários a compreender as suas aplicações e reduz o impacto na entrega e, consequentemente, o custo de implementação e suporte.
Quando o assunto é API, sua documentação é um dos elementos principais para que esta tenha sucesso. Trata-se da entrega técnica de todo conteúdo, ou seja, um manual de referência com instruções de como realizar uma integração efetiva da API, além de pormenores a respeito das suas funções, tipos de retorno, argumentos e exemplos de uso.
Logo uma API bem documentada:
Deixa claro o seu benefício do ponto de vista de negócio;
Aperfeiçoa a Developer Experience;
Previne manutenções;
Torna o usuário consciente do papel da API;
Favorece e acelera o processo de integração;
Ajuda no planejamento de orçamento, cronograma e lançamento de novos produtos.
Todo desenvolvedor precisa compreender que suas APIs podem ser utilizadas por terceiros, que apresentam visão de negócios diferentes e conhecimentos técnicos superiores ou inferiores. Dessa forma, a boa documentação de API é o melhor caminho para que qualquer outro desenvolvedor consiga compreendê-la e a utilize corretamente.
Quando explicativa, a documentação permite que desenvolvedores priorizem seu tempo e a força de trabalho durante processo de integração da API. Por outro lado, uma documentação inadequada acarreta em barreiras para a disponibilização e uso da API, uma vez que pode provocar adversidades relacionadas à excedentes orçamentários não previstos e contratempos de suporte. Ademais, quanto maior a clareza e objetividade presente na documentação, melhor e mais longo será o ciclo de vida da API.
A importância de uma boa documentação
O desenvolvimento de uma estratégia de API pública envolve a construção de um ecossistema em torno dela e, consequentemente, passa pela documentação, onde seu principal objetivo é obter a maior quantidade de desenvolvedores conhecendo-as e implementando as com uma boa experiência. Por isso o mais indicado e correto é que não se pule nenhuma etapa na criação da documentação, evitando assim o risco de perder potenciais usuários.
A seguir as 10 dicas fundamentais para uma documentação de sucesso:
1. Elabore uma documentação completa
A documentação acessada pelos desenvolvedores deve apresentar um conteúdo que auxilie durante toda a interação do usuário com a API, por isso é essencial uma atenção especial e detalhada de todos os dados. É importante também destacar as implicações no seu uso e com isso o usuário entenderá mais sobre a estabilidade da API no momento da integração.
2. Apresente a lista de recursos disponíveis
Os métodos e dados disponíveis são itens básicos de toda documentação de APIs. Elaborar essa lista é um dos primeiros passos envolvendo esse documento. Por isso descreva detalhadamente a função de cada método, parâmetros de entrada e saída. Afinal de contas tal lista será uma das principais referências para que desenvolvedores possam traçar um plano de integração da API.
Exemplo: Instagram
3. Disponibilize exemplos
Mostre exemplos de código para que outros desenvolvedores possam fazer a ligação entre conceito que você transmite e a aplicação prática da API.
4. Reforce os dados sobre autenticação
Reforce em todas as páginas da documentação as etapas e informações necessárias para consumi-las. Por mais que pareça repetitivo, reforce sempre que possível, como por exemplo, processo de autenticação, passos obrigatórios, cadastro para geração de chaves de acesso e etc.
5. Fique atento aos Códigos de Erro/HTTP Status
Outro integrante importante da documentação são os códigos de erro ou mensagens de HTTP status da API. Os HTTP Status Codes possuem um padrão, mas o mesmo não ocorre no caso de códigos de erros. Utilize o espaço da documentação para detalhar todas as possibilidades de problemas e erros com os quais o desenvolvedor pode se deparar ao trabalhar com a sua API. Uma escolha interessante é evitar mensagens de erro genéricas e optar por mensagens mais explicativas.
6. Invista em documentação interativa
Permitir que haja interação dos usuários com sua API através da documentação é uma ótima forma de tornar a experiência mais dinâmica e as integrações mais rápidas. Além da documentação estática e descritiva, invista em uma mais dinâmica por meio de serviços como o Swagger, no qual o desenvolvedor consegue autenticar, verificar métodos e fazer chamadas em tempo real, com retornos de saída e códigos de erro.
7. Teste sua documentação
É necessário coerência e dados concretos presentes na documentação de uma API, por esse motivo teste tudo o que foi documentado sobre sua API e de preferência com o auxílio de uma equipe de desenvolvedores que não elaborou a criação dela, assim você terá a sua disposição diferentes olhares daqueles já presentes no projeto.
8. Permita a experimentação anônima da API
Essa é uma maneira de autorizar que outras pessoas tenham a chance de testar sua API de forma rápida e intuitiva, por meio de uma interface web. A vantagem disso é que não há necessidade de instalar nada. Com exploração de API, usuários com menor conhecimento técnico podem brincar com sua API e explorar seus dados.
Outra questão da exploração é dar permissão para clientes em potencial possam experimentá-la sem precisar se cadastrar ou passar por um processo burocrático. O engajamento é consideravelmente maior nessa situação. É possível também oferecer um ambiente de sandbox, já que ele é relativamente simples e pode ajudar os desenvolvedores a conhecer visualmente o valor de sua API.
Exemplo: Catho
9. Limitando a quantidade de requisições
Outro elemento de relevância na documentação é a quantidade de chamadas disponíveis. Esse número pode variar no caso da monetização de APIs, por exemplo você possui uma parceria com uma empresa ou desenvolvedor e nesse caso eles possuem mais chamadas que um usuário comum. De modo geral, tais informações precisam ser claras e de fácil acesso, da mesma forma que a mensagem de erro que aparecerá para o usuário se este ultrapassar o limite permitido
10. Estruturas, métodos de URI
A estrutura e os métodos de cada URI na API devem ser documentados. Isso precisa ser realizado de tal maneira que o usuário tenha acesso a descrições detalhadas de todas as funções disponíveis. Obviamente nem tudo a respeito de um endpoint pode ou deve constar na documentação, isso nos casos em que o usuário não tenha os direitos necessários para usar tais endpoints.
Uma forma de exemplificar isso é através de dois segmentos de APIs: as gratuitas e as disponíveis apenas para usuários business-to-business ou monetizados. No caso da primeira, é possível que algumas funções, por serem restritas, não estejam disponíveis para um usuário comum. Dessa forma, a documentação desse endpoint não deve ser oferecida para alguém sem autorização.
Os benefícios de uma documentação de APIs bem implementada
Dentre todas as fases do ciclo de vida da API, a documentação é uma das mais importantes. Ficar atento a todos os elementos que devem constar no documento é essencial para colher os frutos de uma API bem sucedida.
Saber documentar uma API implica nos seguintes benefícios:
Adoção de mais APIs
Os padrões de adoção já não são mais os mesmos para os desenvolvedores. A elaboração de uma boa documentação de API está diretamente correlacionada a adoção de APIs. Se você oferecer uma documentação clara e acessível, mais usuários encontrarão valor em seus serviços, levando a um crescimento e adoção de mais APIs
Maior conscientização
Quando muitas pessoas utilizam um produto ou serviço tornando-o valioso trata-se do efeito de rede. O mesmo vale para os consumidores de sua API. Quanto mais satisfeitos eles estiverem, com mais afinco eles defenderam seus serviços e assim será possível prever um crescimento no evangelismo e na publicidade boca a boca.
Manutenção e atualizações mais fáceis
Quanto mais detalhada e precisa for a documentação melhor será a manutenção e atualização das APIs. Com isso as equipes internas terão em mãos mais detalhes sobre os recursos, métodos, solicitações e respostas associadas.
Saiba como apresentar as informações
Apesar da significativa importância da documentação de APIs, ela ainda é vista por muitas empresas como um item “opcional” e acaba sendo deixada de lado, especialmente quando o time de desenvolvedores mantém a documentação manualmente a cada lançamento de novas versões.
É preciso levar em conta o que uma boa documentação pode proporcionar como melhora na Developer Experience e aumento nas chances de consumir a API, dado que os usuários encontrarão valor em seus serviços com facilidade.
Confira 3 exemplos de empresas que realizam documentação de suas APIs:
Vale destacar que muitas das pessoas que trabalham com APIs não possuem necessariamente um conhecimento aprofundado do assunto ou mesmo domine os jargões comuns no setor, portanto, escreva de maneira simples, permitindo a compreensão tanto de desenvolvedores como também de tomadores de decisão, ou seja, os não técnicos.
A produção de vídeos, webinars e tutoriais são muito mais explicativos do que documentações extensas, portanto, por mais que o custo seja mais elevado e dificulte a sua realização constante conforme as APIs são atualizadas, o investimento se paga facilmente dado a simplicidade de consumo por parte do desenvolvedor ou agente de negócio.