Por: Mauro Pichiliani

Atualmente, o desenvolvimento de aplicações Web envolve o conhecimento e o uso de algum tipo de API. Neste artigo, vou comentar sobre quais tipos de documentação e recursos são úteis para promover uma API e auxiliar o desenvolvedor que precisa aprender a usá-la.

Já faz algum tempo que desenvolvo software de diferentes tipos, e recentemente tenho participado de alguns concursos e Hackathons. Durante essas atividades, geralmente preciso aprender alguma API nova para realizar uma tarefa. Contudo, na maioria das vezes, acabo me deparando com problemas de documentação e falta de informações necessárias para o uso da API.

Por causa dessa frustração, resolvi escrever este artigo com algumas recomendações e dicas para quem cria APIs. É importante destacar que não é só uma boa documentação que vai levar uma API ao sucesso de uso, ou seja, existem outros aspectos importantes para sua a adesão. Neste artigo, vou me concentrar nos principais pontos que gostaria de encontrar sempre que tiver que aprender a usar uma API. Do ponto de vista prático, estes itens que vou citar funcionam como um checklist que os criadores da API podem seguir.

1. Exemplos. Exemplos para tudo quanto é lado

Muitos desenvolvedores preferem ir direto para exemplos de código e gastam pouco ou nenhum tempo estudando e aprendendo conceitos. Por isso é importante sempre fornecer diversos exemplos de uso de API. Isso quer dizer que é preciso ir muito além do básico “Hello, World”. Uma boa dica é fornecer pelo menos um exemplo para cada funcionalidade importante da API.

Também vale a pena disponibilizar exemplos em cada uma das principais linguagens/ambientes nos quais a API vai ser utilizada e destacar como ela se comporta em determinada situações (falta de Internet, limite de uso excedido e outros). Nota: os exemplos podem ser didáticos, porém, quanto mais próximos da realidade e do objetivo no qual as pessoas vão usar a API, mais adequada vai ser a utilidade do exemplo.

2. Tenha um playground/ambiente de testes

O desenvolvedor que está começando a utilizar uma API certamente vai fazer diversos testes antes de colocá-la em um uso oficialmente (em produção). Devido a esse comportamento, faz muito sentido que a API possa ser utilizada em um ambiente de testes ou avaliação, pois assim é possível “brincar” e descobrir o que é possível fazer com a API. Em certos casos, especialmente em APIs que envolvem o uso de valores monetários, vale a pena investir em versões de avaliação com algum tipo de limitação de uso por tempo ou funcionalidades.

Algumas APIs requerem diversos passos para serem utilizadas, como cadastro, autorização, obtenção de token e validação. Apesar de essas etapas serem importantes, elas acabam afastando alguns desenvolvedores que desejam realizar um teste rápido. Para esses casos, recomenda-se a criação de um playground ou ambiente pronto para que o desenvolvedor possa ter um gostinho de como a API funciona sem ter que passar por diversos passos de configuração de ambiente e obtenção de recursos de autorização e autenticação.

3. Documentação além do básico

A documentação é um recurso obrigatório para quem produz uma API. Existem diversos tipos de documentação, mas o que procuro quando estou aprendendo é algum que vá além de um simples JavaDoc ou algo gerado automaticamente. Procuro, em particular, diagramas, arquiteturas e algum tipo de informação visual que me permita entender os pré-requisitos, como é o fluxo de passos, as características e os detalhes necessários para que eu consiga realizar a tarefa que preciso com a API. Guias para iniciantes (Getting Started) também são ótimos pontos de partida para quem caiu de paraquedas no site da API e não tem ideia de onde e como começar a usá-la.

Um dos itens importantes de uma boa documentação é deixar claro onde a API pode e deve ser utilizada, e onde não faz sentido empregá-la. Isso é importante para que o desenvolvedor saiba até onde é possível ir com ela e quais são os cenários e casos de uso em que ela não é recomendada. Também é muito útil destacar na documentação a lista atualizada de bugs para cada versão da API, pois não há nada mais frustrante do que perder muito tempo quebrando a cabeça com um bug para descobrir só depois que ele já foi arrumado em uma versão mais atual da API.

4. Um bom FAQ e RTFM

Eu gosto muito dos FAQs (Frequently Asked Questions ou Perguntas Frequentes) quando estou aprendendo a usar uma API. Esse formato de perguntas rápidas e respostas me ajuda muito a compreender o objetivo e as particularidades de uso da API. Sem contar que desse modo fica fácil descobrir o que outras pessoas estão tentando fazer com a API.

Contudo, não vale a pena colocar no FAQ informações antigas, desatualizas ou que não fazem mais sentido com tecnologias obsoletas. Também é importante adotar um tom mais leve, bem humorado e didático na escrita do FAQ em relação à documentação oficial, pois um texto mais amigável incentiva os desenvolvedores a trabalharem com a API. Por outro lado, deve-se evitar sarcasmo, tratar o desenvolvedor como idiota ou simplesmente mandá-lo ler o manual indicando a sigla RTFM.

5. Um canal de comunicação com o desenvolvedor

Uma API de sucesso deve ter algum tipo de canal de comunicação com o desenvolvedor. Esse canal pode ser um e-mail, Twitter, formulário de contato ou qualquer outro meio que permita ao desenvolvedor que tem uma dúvida técnica ser ouvido. Destaco que indicar qual é o tempo médio de resposta nas comunicações assíncronas (como o e-mail) ajuda muito a ter aquela sensação de que o “cliente” é importante e que ele vai ser ouvido.

Em geral, os canais de comunicação para desenvolvedores devem ser mais simples, curtos e rápidos, pois quem cria software e chega ao ponto de entrar em contato com o criador de uma API provavelmente já fez diversos testes e encontrou uma barreira que o fez ficar parado e pedir ajuda. Por isso a comunicação deve ser direta e sem rodeios, para que o desenvolvimento não seja atrasado ainda mais.

6. Deixe claro preços, tipo de acesso e limitações de uso

Muitas APIs têm em seu modelo de negócio a cobrança por uso de acordo com algum tipo de lista de funcionalidades, tempo ou número de chamadas. É extremamente importante deixar bem claro quais são os valores, tipos de uso (pacote gratuito, normal ou avançado), modos de pagamento e cobrança, e também como funciona o reembolso, troca de modalidade ou estorno de valores.

É comum que APIs inicialmente sejam gratuitas e, depois que atinjam um certo número de usuários, se tornem pagas. A princípio, tal mudança do modelo de negócio pode frustrar e afugentar alguns desenvolvedores. Nesse caso, o que gostaria de ouvir é uma comunicação clara de como as coisas vão ficar uma vez que o serviço se torne pago, incluindo prazos, limitações, vantagens e desvantagens de como o serviço da API era e de como ele vai ficar no novo modelo de negócios.

7. Mantenha um histórico decente

Todo projeto de software que evolui a cada versão tem um histórico por trás. Esse histórico é importante para mostrar não só a que passo o projeto anda, mas também para deixar claro o rumo que ele está tomando.

Diversas APIs sofrem modificações constantes de acordo com o ambiente, como nova versões de navegadores, recursos para torná-la mais rápida, modificações para suportar novas plataformas e adequações gerais a novas tecnologias e tendências do desenvolvimento Web. Portanto, saber indicar de forma adequada o histórico é importante para fornecer um contexto e deixar claros os motivos pelos quais a API está do jeito que ela é hoje.

8. Tenha um guia de troubleshooting

É muito comum encontrar problemas e dificuldades quando se está estudando uma nova API ou quando certas condições do ambiente mudam. Nessas ocasiões, é importante ter em mãos um guia de resolução de problemas (troubleshooting guide) que vai indicar, passo a passo, quais são os pontos que devem ser observados.

No caso de APIs, um guia de troubleshooting deve dizer passo a passo como realizar um teste de conexão, quais parâmetros são necessários, que tipo de retorno é apresentado para cada requisição e como proceder se algum dos passos falhar. Esse tipo de guia é muito útil quando se está debugando um problema e não se sabe qual dos componentes da solução está falhando. Nessa situação, um guia de diagnóstico e instruções passo a passo são extremamente úteis para ajudar primeiro a entender o que está acontecendo e, sem seguida, tomar alguma atitudes para remediar o problema.

9. Invista em um roadmap e novas funcionalidades

Um fator que o desenvolvedor leva em consideração quando está estudando e ponderando se vale a pena ou não utilizar uma API é a sua continuidade. Ou seja, vale a pena eu estudar, investir tempo e modificar a minha aplicação para usar a API se ela não vai me servir no futuro? Em outras palavras, ninguém quer utilizar um serviço que parece uma cidade do velho oeste abandonada…

Uma boa maneira de deixar claro como anda o projeto de uma API é fornecer um roadmap em um gráfico que mostra as últimas versões da API e quail é o planejamento para as próximas versões. Dessa forma, o criador da API mostra seu compromisso em manter esse serviço no futuro e deixa claro que o projeto é sério, e não simplesmente algo passageiro que tem um futuro incerto.

10. Destaque projetos que usam a API

Uma API geralmente faz parte de um software maior, mesmo que esse software seja apenas uma interface gráfica para seu uso. Se o design de uma API foi bem planejado e ela é algo realmente útil e flexível, é normal esperar que diferentes tipos de projetos façam uso da API.

Destacar e dar ênfase a diferentes projetos que utilizam a API é uma ótima maneira de incentivar pessoas a utilizá-la e valorizar o serviço. Quando estou avaliando uma API e vejo diversos projetos que a utilizam, tenho uma sensação de confiança, pois, se alguém já está utilizando esse serviço de alguma maneira, isso me motiva a usá-lo também. Em particular, me sinto incentivado ao ver projetos completamente diferentes utilizando um mesmo serviço, pois essa flexibilidade pode me ser útil no futuro.

11. Fomente a comunidade

Ninguém quer ser aquele convidado que chega primeiro na festa e percebe mais tarde que ele foi o único que apareceu. Isso quer dizer que fomentar uma comunidade é algo muito importante para que os desenvolvedores que usam a API não se sintam isolados e solitários.

Existem várias maneiras de lidar com a comunidade de uma API incluindo eventos próprios, como Hackathons (maratonas de programação), dojos de programação, encontros onde pessoas se reúnem para fazer a tradução de outras linguagens ou produzir documentação, ou mesmo eventos sociais dos quais os membros da comunidade saem para tomar umas e conversar sobre o projeto. Independentemente do formato do evento, vale a pena investir na comunidade de usuários para que seja possível aprimorar o serviço, ouvir como ele é utilizado e entrar em contato com quem realmente depende do serviço.

Fonte: iMasters

Texto original:
http://imasters.com.br/apis/oi-sou-uma-api-veja-aqui-como-me-usar-melhor/?trace=1519021197&source=home