Oi, sou uma API. Veja aqui como me usar melhor

Fonte: http://umbatman.deviantart.com/art/Cyborg-407404538

Fonte: http://umbatman.deviantart.com/art/Cyborg-407404538

Atualmente o desenvolvimento de aplicações Web envolve o conhecimento e uso de algum tipo de API. Neste post 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.
Figura2_api
Já faz algum tempo que desenvolvo software de diferentes tipos e recentemente tenho participado de alguns concursos e Hackathons. Durante estas atividades geralmente preciso aprender alguma API nova para realizar alguma 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 desta frustação resolvi escrever este post 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 post 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

Figura3_
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. Isto 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 na qual 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 adequado vai ser a utilidade do exemplo.

2) Tenha um playground/ambientes de testes

Figura4
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 este 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 tal como cadastro, autorização, obtenção de token e validação. Apesar destas etapas serem importantes, elas acabam afastando alguns desenvolvedores que desejam realizar um teste rápido. Para estes 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

Figura5
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

Figura6Eu gosto muito dos FAQs (Frequently Asked Questions ou Perguntas Frequentes) quando estou aprendendo a usar uma API. Este formato de perguntas rápidas e respostas me ajuda muito a compreender o objetivo e particularidades de uso da API. Sem contar que deste 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 mandar ele ler o manual indicando a sigla RTFM.

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

Figura7_DeveloperToDeveloperCommunicationUma API de sucesso deve ter algum tipo de canal de comunicação com o desenvolvedor. Este 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 deve ser mais simples, curtos e rápido, 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

Figura8_1363963992391Muitas APIs tem 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. Neste 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. Este 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, por exemplo, nova versões de navegadores, recursos para torná-la mais rápida, modificações para suportar novas plataformas e adequações gerais à novas tecnologias e tendências do desenvolvimento Web. Portanto, saber indicar de forma adequada o histórico é importante para fornecer um contexto e deixar claro os motivos pelas quais a API está do jeito que ela é hoje.

8) Tenha um guia de troubleshooting

Figura10_Software-Developer É muito comum encontrar problemas e dificuldades quando se está estudando uma nova API ou quando certas condições do ambiente mudam. Nestas ocasiões é importante tem 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. Este tipo de guia é muito útil quando se está debugando um problema e não se sabe qual dos componentes da solução está falhando. Nesta situação um guia de diagnóstico e instruções passo a passo são extremamente úteis para ajudar a primeiro entender o que está acontecendo e, sem seguida, tomar alguma atitudes para remediar o problema.

9) Invista em um roadmap e novas funcionalidades

Figura11_wXSbV
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 última versões da API e quais é o planejamento para as próximas versões. Desta forma o criador da API mostra seu compromisso em manter este 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

Figura12_Triathlon-beginner-flexible-woman
Uma API geralmente faz fazer parte de um software maior, mesmo que este 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 este serviço de alguma maneira isso me motiva a utilizá-lo também. Em particular me sinto incentivado ao ver projetos completamente diferentes utilizando um mesmo serviço, pois esta flexibilidade pode me ser útil no futuro.

11) Fomente a comunidade

Fonte: http://www.pocket-lint.com/news/132386-barclays-banking-on-code-playground-and-digital-driving-license-to-enhance-our-digital-skills

Fonte: http://www.pocket-lint.com/news/132386-barclays-banking-on-code-playground-and-digital-driving-license-to-enhance-our-digital-skills

Ninguém quer ser aquele convidado que chega primeiro na festa e percebe mais tarde que ele foi o único que apareceu. Isto quer dizer que fomentar uma comunidade é algum 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 que os membros da comunidade saem para tomar umas e conversar sobre o projeto. Independente 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.



Esta entrada foi publicada em Programação e marcada com a tag , , , , , , , , . Adicione o link permanente aos seus favoritos.

5 respostas a Oi, sou uma API. Veja aqui como me usar melhor

  1. Maycon Brito disse:

    Excelente artigo Mauro! Estamos em processo de criar uma API em nossa empresa para uso interno e integração com outros sistemas em nosso ambiente. Sua publicação veio a calhar na hora certa para nós. Obrigado e um abraço!

  2. devls disse:

    Sinceramente, muitas das coisas que você escreveu são bobagens. Coisas de quem quer tudo fácil. Se quer realmente aprender algo leia o manual e estude. Agora se você é um desenvolvedor medíocre que só quer moleza fica complicado.

  3. Pingback: Dicas para quem cria, mantém e usa uma API - Peguei do

  4. Pingback: Avaliação do novo Ford Ka | Blog do Mauro Pichiliani

  5. Tiago disse:

    Olá, Gostei muito do post! acabei caindo aqui de paraquedas ao pesquisar por “como estudar uma api” gostaria de saber se você tem algum material que indica neste caso?

Deixe uma resposta

O seu endereço de e-mail não será publicado. Campos obrigatórios são marcados com *