Como fornecedores de uma plataforma de integração, APIs são um dos nossos principais materiais de trabalho. E vamos ser sinceros: no dia a dia, lidamos com todos os tipos – boas APIs, meia-bocas e até quase impossíveis de usar. Você também?
Isso fica claro quando a gente nota o quanto de APIs que têm por aí, principalmente agora, que as organizações têm muitos sistemas em uso e precisam integrá-los com o ecossistema existente. Então, dificilmente vamos achar uma aplicação que não tenha uma.
Mas existem APIs e APIs. E a qualidade da API não é mero detalhe: ela influencia diretamente a facilidade ou dificuldade de fazer uma integração.
Como são então as boas APIs? Intuitivamente, quando sentimos as dificuldades de integrar, a gente sabe. Então, neste post, reunimos todos os nossos aprendizados para trazer para você como uma API tem que ser para ser boa para integrar.
Por que a qualidade da API determina a escolha da integração
Há dois métodos de integrar com APIs. Ou você busca os dados fazendo um polling ou, por meio de webhooks, recebe os dados.
No poll, você comanda o fluxo de dados, o que ajuda a manter a performance da integração e a garantir que os dados não se percam. Nesse caso a qualidade da API é determinante. O problema é que você faz polling numa cadência definida, não em tempo real.
Com o webhook, a API vai mandar dados por si mesma. Então não importa muito a qualidade dela. O que você precisa é o que sistema origem dos dados os entregue assim que eles mudem. Então, você tem a vantagem de ter os dados em tempo (quase) real. No entanto, tem pouquíssimo controle sobre o fluxo dos dados. O sistema de origem vai mandar o que tem e você não consegue limitar esse volume, com mecanismos como paginação.
Uma boa API pode ser usada nesses dois métodos de integração. No caso da API ser ruim, você terá dificuldades de integrar no primeiro método. Então o segundo método será basicamente a única escolha, com suas vantagens e desvantagens.
Como ter mais opções é sempre melhor, vamos às características das boas APIs.
10 qualidades das boas APIs
Antes um parênteses. A maior parte do tempo os desenvolvedores estão trabalhando em soluções voltadas para usuários sem conhecimento técnico em desenvolvimento. No desenvolvimento de API, é diferente. Nesse caso, a interface é pensada para outros desenvolvedores. Deveria ser mais fácil, portanto. Mas não é.
Um dos motivos é que desenvolvedores de APIs e usuários de APIs podem ter visões bem diferentes. Designers de APIs estão tipicamente focados em questões como “o que esse serviço precisa fazer?” ou “o que esse serviço precisa prover?”, enquanto usuários de APIs estão buscando responder “como eu posso usar essa API para o que os stakeholders precisam?”.
Como se colocar na perspectiva do usuário, dando a ele na API o que precisa? Essa é a pergunta que deve estar, junto com todos os aspectos funcionais, subjacente ao desenvolvimento de APIs. E então, chegamos às 10 características de boas APIs:
1. São simples, consistentes e com boa usabilidade
Boas APIs são, internamente, o mais simples possíveis. Os desenvolvedores têm que evitar a tentação de adicionar complexidades indevidas, mesmo quando supostamente pretendem ajudar o usuário. Para isso, eles abstraem detalhes da API, do código à execução.
Eles também mantêm o mesmo estilo sempre, sendo previsíveis para os usuários. Parâmetros de métodos não podem mudar dependendo do endpoint usado. Assim, o usuário não é surpreendido por mudanças de padrão não esperadas.
2. São estáveis
APIs precisam ser estáveis. Manter versões antigas rodando com suporte por um longo período, mesmo anos, após a reescrita de uma API, pode ser fundamental para os usuários.
Além de manter versões, oferecer um plano de transição pode ser interessante.
Outra prática de boas APIs é um histórico de modificações, que mostra todas as diferenças entre as versões, para que os usuários saibam exatamente como atualizá-las.
3. Têm registro temporal de modificações nos dados
Quando uma trigger tem de buscar dados de uma API, o que está em jogo é a identificação das mudanças nesses dados. E a única maneira de obter esses dados é por meio da verificação de mudanças num período.
Uma boa API, portanto, permite que a busca nos datasets seja feita por critério de data. Afinal, depois da sincronização inicial, são as mudanças posteriores que mais interessam.
4. Fazem classificação de dados
Esses dados modificados ao longo do tempo precisam estar ordenados de alguma maneira, pelo menos, de acordo com a data de modificação.
Isso facilitará o agrupamento de volumes grandes de dados, por exemplo.
5. Permitem a paginação de dados
Pode haver um grande volume de dados modificados no sistema do usuário, certo? Para lidar com isso sem perder eficiência na integração, precisamos poder especificar que não queremos todos os dados modificados de uma vez, mas apenas parte deles, algumas páginas.
Daí vem essa ideia de paginação, que justifica, aliás, a classificação dos dados. Boas APIs devem ser capazes de limitar o volume de dados que podem ser recebidos de uma vez, assim como a frequência de requisições de dados. Elas também devem registrar quantas páginas sobraram de uma leva.
6. Aceitam JSON
Nem toda API precisa ser REST (embora a maioria seja), mas deve aceitar JSON.
JSON, diferentemente de XML, é mais perecido com nossas linguagens de programação. Isso o torna mais fácil de ser analisado em quase qualquer linguagem.
E com certeza ele vai bem com APIs REST, que são leves, compatíveis com a web e agnósticas. Isso as torna perfeitas para aplicações que requerem um considerável volume de mensagens, como aplicativos mobile. Se um upload é interrompido por algum motivo, as APIs REST tornam fácil a repetição do processo. Com SOAP isso é possível, mas com mais esforço.
7. Têm autorização via OAuth
OAuth, como um standard aberto para autorizações, proporciona melhor usabilidade do que outros métodos. No entanto, para autenticação o OAuth não é suficiente.
8. Têm boa documentação
Esse poderia ser o primeiro ponto dessa lista.
Oferecer boa e exaustiva documentação para uma API é algo que já deveria ser o padrão. Você pode odiar construí-la, mas de uma perspectiva de integração seus usuários vão incomodar menos. É bem melhor investir na documentação do que sentir as demandas vindas dos usuários que tentam trabalhar com APIs mal documentadas.
E isso independe da qualidade da API. Há boas APIs extremamente mal documentadas. Uma boa documentação, além de ser a primeira coisa que os usuários vão ver, é meio caminho andado da integração, diminuindo consideravelmente o tempo, logo os custos do projeto.
E por documentação, o que a gente entende? Que precisa descrever métodos da API, endpoints, funções e possíveis opções de resposta, mas também exemplos e tutoriais. A quantidade de exemplos e de tutoriais distingue uma documentação suficiente de uma documentação excelente.
Mostre a documentação a desenvolvedores que não conhecem a sua API, para validá-la e elevar o seu nível de clareza.
9. Fazem tratamento de erros
Independentemente da simplicidade de uma API, erros podem acontecer. Use os códigos certos de status, ofereça informação adicional para ajudar os usuários a compreender o erro tanto quanto possível para que sejam capazes de corrigi-lo por si mesmos.
Defina como responder a um bug, a problemas na documentação, a usuários menos experientes e por aí vai. No final, isso dará menos trabalho não só para os usuários, mas para você também.
10. São fáceis de adotar
Tenha certeza de que outros desenvolvedores conseguem usar suas APIs com facilidade e que elas funcionem de primeira. Faça verificações constantes, para entender se não há algo dificultando a adoção.
Vá no padrão, em vez de tentar reinventar a roda. No caso de APIs, você precisa falar a língua mais aceita na comunidade.
Além disso, ofereça um excelente suporte. A falta dele pode ser uma grande barreira à adoção da sua API. E tenho certeza de que você quer que ela seja famosa.
Boas APIs: a base de toda boa integração
APIs determinam a facilidade de uma integração, logo é fundamental que elas sejam boas e fáceis de usar.
Vimos 10 características das boas APIs, segundo nossos desenvolvedores.
Incluiria algum item nessa lista?