5 regras de ouro para um ótimo design de API da Web

Já se perguntou “o que eles estavam pensando?” ao integrar um serviço web por meio de sua API? Se não, você teve muito mais sorte do que eu.

Qualquer desenvolvedor de software sabe como é fácil deixar um projeto se transformar em código espaguete, e as APIs da web não são menos propensas a resultar em uma web emaranhada. Mas não precisa ser assim. Na verdade, é possível projetar ótimas APIs da Web que as pessoas realmente gostem de usar e que você também goste de criar. Mas como? A resposta a essa pergunta é sobre o que trata este post.

Perspectiva

Na maioria das vezes, quando você cria soluções, está projetando para usuários finais que não são programadores ou que geralmente não são tecnicamente sofisticados. Você está dando a eles uma interface gráfica e, se estiver fazendo seu trabalho corretamente, terá uma boa ideia do que eles precisam que a interface faça.

Mas o desenvolvimento de API é diferente. Você está projetando uma interface para programadores , provavelmente sem saber quem eles são. E quem quer que sejam, eles terão a sofisticação técnica (ou pelo menos pensarão que têm a sofisticação técnica) para apontar cada pequena falha em seu software. É provável que seus usuários sejam tão críticos em relação à sua API quanto você seria em relação a eles e vão gostar muito de criticá-la.

E nisso reside parte da ironia, aliás. Se alguém deve entender como criar uma API da Web fácil de usar, é você . Afinal, você é um engenheiro de software assim como os usuários de sua API, então você compartilha a perspectiva deles. Você não?

Bem, embora você certamente entenda a perspectiva deles, não necessariamente compartilha a perspectiva deles. Quando você está desenvolvendo ou aprimorando sua API, você tem a perspectiva de um designer de API, enquanto eles têm a perspectiva de um usuário de API.

Os designers de API geralmente se concentram em perguntas como “O que esse serviço precisa fazer?” ou "O que este serviço precisa fornecer?" , enquanto os usuários da API estão focados em "Como posso usar esta API para fazer o que preciso?" , ou mais precisamente, "Como posso gastar o mínimo de esforço para obter o que preciso dessa API?" .

Essas diferentes questões levam a duas perspectivas muito diferentes. Como resultado, o pré-requisito necessário para projetar uma ótima API é mudar sua perspectiva do designer da API para a do usuário da API. Em outras palavras, faça a si mesmo continuamente as perguntas que você faria naturalmente se fosse seu próprio usuário. Em vez de pensar no que sua API pode fazer, pense nas diferentes maneiras pelas quais ela pode precisar ou querer ser usada e, em seguida, concentre-se em tornar essas tarefas o mais fácil possível para os usuários de sua API.

Embora isso possa parecer fácil e óbvio, é surpreendente como as APIs raramente parecem ser projetadas dessa maneira. Pense nas APIs que você encontrou em sua carreira. Com que frequência eles parecem ter sido projetados com essa perspectiva em mente? O design da API da Web pode ser desafiador.

Dito isso, vamos prosseguir e falar sobre as 5 Regras de Ouro para Projetar uma Ótima Web API , a saber:

1. Documentação
2. Estabilidade e consistência
3. Flexibilidade
4. Segurança
5. Facilidade de adoção

Regra 1: Documentação

Documentação. Sim, estou começando aqui.

Você odeia documentação? Bem, posso simpatizar, mas coloque seu chapéu de “perspectiva do usuário” e aposto que a única coisa que você odeia mais do que ter que escrever documentação é ter que tentar usar uma API não documentada. Eu descanso meu caso.

A conclusão é que, se você quiser que alguém use sua API, a documentação é essencial. Você simplesmente tem que fazer isso direito. É a primeira coisa que os usuários verão, então, de certa forma, é como o papel de embrulho. Apresente bem, e as pessoas estarão mais propensas a usar sua API e tolerar quaisquer idiossincrasias.

Então, como escrevemos uma boa documentação?

A parte relativamente fácil é documentar os próprios métodos da API; ou seja, solicitações e respostas de exemplo, juntamente com descrições de cada um dos elementos em ambos. Felizmente, há um número crescente de ferramentas de software que facilitam e simplificam a tarefa de gerar documentação. Ou você mesmo pode escrever algo que analise sua API, endpoints e funções e gere a documentação correspondente para você.

Mas o que separa uma boa documentação de uma documentação adequada é a inclusão de exemplos de uso e, idealmente, tutoriais. Isso é o que ajuda o usuário a entender sua API e por onde começar. Ele os orienta e os ajuda a carregar sua API em seus cérebros.

Por exemplo, se os desenvolvedores do Twilio listassem todas as classes, todos os métodos e todas as respostas possíveis para sua API, mas não se preocupassem em mencionar que você pode enviar um SMS, rastrear uma chamada ou comprar um número de telefone através sua API, levaria muito tempo para o usuário da API encontrar essas informações e entendê-las de forma coesa. Você pode imaginar ordenar através de uma árvore gigante de classes e métodos sem qualquer insight sobre para que eles foram usados, além de seu nome? Soa terrível certo? Mas é exatamente isso que muitos provedores de API fazem, deixando suas APIs opacas para qualquer um, menos para eles mesmos. O guia do desenvolvedor e API Rackspace CloudFiles é um exemplo; é difícil se orientar a menos que você já entenda o que eles estão fazendo e o que estão fornecendo.

Portanto, escreva tutoriais concisos que ajudem o desenvolvedor a começar a trabalhar rapidamente, com pelo menos um esboço do que eles estão tentando fazer, e aponte-os na direção da lista de funcionalidades mais detalhada e totalmente documentada para que eles possam expandir no que eles têm.

Depois de concluir sua documentação, certifique-se de validar se ela faz sentido para outras pessoas além de você. Envie-o para outros desenvolvedores em sua rede, não dê nenhuma instrução além de apontá-los para a documentação e peça que sigam um tutorial ou criem algo realmente básico em cerca de 15 minutos. Se eles não puderem ter uma integração básica com sua API em 15 minutos, você terá mais trabalho a fazer.

Para alguns exemplos notáveis ​​de documentação excelente e detalhada, confira Twilio, Django e MailChimp. Nenhum desses produtos é necessariamente o melhor em seus mercados (embora sejam todos bons produtos), mas eles se distinguem por fornecer algumas das melhores documentações em seus mercados, o que certamente facilitou sua ampla aceitação e participação no mercado.

Regra 2: Estabilidade e Consistência

Se você já usou a API do Facebook, sabe com que frequência eles depreciam e reescrevem completamente suas APIs. Não importa o quanto você respeite a cultura hacker ou o produto deles, a perspectiva deles não é amigável ao desenvolvedor. A razão pela qual eles ainda são bem-sucedidos é porque eles têm um bilhão de usuários, não porque sua API é ótima.

Mas você provavelmente não tem o luxo de uma base de usuários e participação de mercado tão gigantesca, então você precisará ter uma API muito menos volátil, mantendo versões antigas em execução e suportadas por um longo período de tempo. Talvez até anos. Então, para esse fim, aqui estão algumas dicas e truques.

Digamos, por exemplo, que sua API seja acessível através da URL http://myapisite.com/api/widgets e forneça sua resposta no formato JSON. Embora isso possa parecer bom à primeira vista, o que acontece quando você precisa modificar o formato da resposta JSON? Todo mundo que já está integrado a você vai quebrar. Ops.

Portanto, planeje com antecedência e faça a versão de sua API desde o início, incorporando explicitamente um número de versão na URL (por exemplo, http://myapisite.com/api/widgets?version=1 ou http://myapisite.com/api/widgets/v1 ) para que as pessoas possam confiar no funcionamento da versão 1 e possam atualizar para qualquer versão subsequente quando estiverem prontas para isso. Se você precisar eliminar uma versão anterior em algum momento, vá em frente, mas avise com bastante antecedência e ofereça algum tipo de plano de transição.

Um bom esquema de URL incluirá versões principais na URL. Qualquer alteração no formato de saída ou nos tipos de dados suportados deve resultar na atualização para uma nova versão principal. Geralmente, é aceitável manter a mesma versão se tudo o que você está fazendo é adicionar chaves ou nós à sua saída, mas para estar no lado seguro, sempre que a saída for alterada, aprimore uma versão.

Além de serem estáveis ​​ao longo do tempo, as APIs precisam ser consistentes internamente. Já vi muitas APIs que alteram nomes de parâmetros ou métodos de POSTing de dados, dependendo do endpoint que está sendo usado. Em vez disso, você deve lidar com parâmetros comuns globalmente em sua API e usar herança ou uma arquitetura compartilhada para reutilizar as mesmas convenções de nomenclatura e manipulação de dados de forma consistente em toda a sua API.

Por fim, você precisa registrar e publicar um log de alterações para mostrar as diferenças entre as versões da sua API para que os usuários saibam exatamente como atualizar.

Regra 3: Flexibilidade

Garbage in, garbage out (GIGO) é um mantra bem conhecido para a maioria dos programadores. Aplicado ao design da API da Web, esse princípio orientador tende a ditar uma abordagem bastante rígida para a validação de solicitações. Parece ótimo, certo? Sem bagunça, sem problemas.

No entanto, como em tudo, é preciso haver algum equilíbrio. Como não é possível prever todas as formas como os usuários vão querer empregar seu serviço, e como nem toda plataforma cliente é consistente (ou seja, nem toda plataforma tem um suporte JSON muito bom, uma biblioteca OAuth decente etc.), é bom tenha pelo menos algum grau de flexibilidade ou tolerância em relação às suas restrições de entrada e saída.

Por exemplo, muitas APIs suportam uma variedade de formatos de saída, como JSON, YAML, XML, etc. al., mas só suportará a especificação do formato na própria URL. No espírito de permanecer flexível, você pode permitir que isso também seja especificado na URL (por exemplo, /api/v1/widgets.json ), ou você também pode ler e reconhecer um cabeçalho HTTP Accept: application/json ou oferecer suporte a um variável querystring, como ?format=JSON e assim por diante.

E já que estamos nisso, por que não permitir que o formato especificado não faça distinção entre maiúsculas e minúsculas, para que o usuário possa especificar ?format=json também? Esse é um exemplo clássico de uma maneira de aliviar a frustração desnecessária do usuário de sua API.

Outro exemplo é permitir diferentes maneiras de inserir variáveis. Assim, assim como você tem uma variedade de formatos de saída, permita também uma variedade de formatos de entrada (por exemplo, variáveis ​​POST simples, JSON, XML, etc.). Você deve pelo menos estar suportando variáveis ​​POST padrão, e muitos aplicativos modernos também suportam JSON, então esses dois são um bom lugar para começar.

O ponto aqui é que você não deve presumir que todos compartilham suas preferências técnicas. Com um pouco de pesquisa sobre como outras APIs funcionam e através do diálogo com outros desenvolvedores, você pode obter outras alternativas valiosas que são úteis e incluí-las em sua API.

Regra 4: Segurança

A segurança é obviamente uma das coisas mais importantes a serem incorporadas ao seu serviço da Web, mas muitos desenvolvedores o tornam ridiculamente difícil de usar. Como provedor de API, você deve oferecer exemplos úteis de como autenticar e autorizar ao acessar sua API. Esta não deve ser uma questão difícil na qual um usuário final passa horas trabalhando. Tenha como objetivo que eles não precisem escrever nenhum código ou levem menos de 5 minutos para escrevê-lo.

Para a maioria das APIs, prefiro uma autenticação simples baseada em token, em que o token é um hash aleatório atribuído ao usuário e ele pode redefini-lo a qualquer momento se for roubado. Permita que o token seja transmitido por meio de POST ou de um cabeçalho HTTP. Por exemplo, o usuário pode (e deve) enviar um token SHA-1 como uma variável POST ou como um cabeçalho em um formato como “Autorização: da39a3ee5e6b4b0d3255bfef95601890afd80709”.

Além disso, escolha um token seguro, não um identificador numérico curto. Algo irreversível é melhor. Por exemplo, é relativamente simples gerar um token SHA durante a criação do usuário e armazená-lo no banco de dados. Em seguida, você pode simplesmente consultar seu banco de dados para qualquer usuário que corresponda a esse token. Você também pode fazer um token gerado com um identificador exclusivo e um valor salt, algo como SHA(User.ID + "abcd123") e, em seguida, consultar qualquer usuário que corresponda; por exemplo, where TokenFromPost = SHA(User.ID + "abcd123") .

Outra opção muito boa é OAuth 2 + SSL. Você deveria estar usando SSL de qualquer maneira, mas o OAuth 2 é razoavelmente simples de implementar no lado do servidor, e as bibliotecas estão disponíveis para muitas linguagens de programação comuns.

Se a API que você criou deve ser acessível em um site público via JavaScript, você também precisa validar uma lista de URLs por conta para o token. Dessa forma, ninguém pode inspecionar as chamadas para sua API, roubar o token do seu usuário e usá-lo para si.

Aqui estão algumas outras coisas importantes para se ter em mente:

• Funcionalidade de lista de permissões. As APIs geralmente permitem que você faça operações básicas de criação, leitura, atualização e exclusão nos dados. Mas você não deseja permitir essas operações para todas as entidades, portanto, certifique-se de que cada uma tenha uma lista de permissões de ações permitidas. Certifique-se, por exemplo, de que apenas usuários autorizados possam executar comandos como /user/delete/<id> . Da mesma forma, todos os cabeçalhos úteis enviados na solicitação do usuário também precisam ser validados em uma lista de permissões. Se você estiver permitindo cabeçalhos de tipo de conteúdo, verifique se o que o usuário enviar realmente corresponde a uma lista de tipos de conteúdo com suporte. Se isso não acontecer, envie de volta uma mensagem de erro, como uma resposta 406 Não Aceitável. A lista branca é importante, pois muitas APIs são geradas automaticamente ou, em vez disso, usam uma lista negra, o que significa que você precisa ser explícito sobre o que não deseja. No entanto, a regra de ouro da segurança é começar com absolutamente nada e permitir apenas explicitamente o que você deseja.

• Proteja-se contra falsificação de solicitação entre sites (CSRF). Se você está permitindo autenticação de sessão ou cookie, você precisa se certificar de que está se protegendo contra ataques CSRF. O Open Web Application Security Project (OWASP) fornece orientações úteis sobre como evitar essas vulnerabilidades.

• Valide o acesso aos recursos. Em cada solicitação, você precisa verificar se um usuário realmente tem permissão para acessar o item específico ao qual está fazendo referência. Portanto, se você tiver um endpoint para visualizar os detalhes do cartão de crédito de um usuário (por exemplo, /account/card/view/152423 ), certifique-se de que o ID “152423” esteja referenciando um recurso que o usuário realmente está autorizado a acessar.

• Valide todas as entradas. Todas as entradas de um usuário precisam ser analisadas com segurança, de preferência usando uma biblioteca bem conhecida se você estiver usando entradas complicadas como XML ou JSON. Não construa seu próprio analisador, ou você estará em um mundo de dor.

Regra 5: Facilidade de Adoção

Esta é realmente a regra mais importante do grupo e se baseia em todas as outras. Como mencionei durante a regra de documentação, experimente isso com pessoas que são novas na sua API. Certifique-se de que eles possam começar a funcionar com pelo menos uma implementação básica de sua API, mesmo que seja apenas seguindo um tutorial, em alguns minutos. Acho que 15 minutos é um bom objetivo.

Aqui estão algumas recomendações específicas para facilitar e facilitar a adoção de sua API:

• Certifique-se de que as pessoas possam realmente usar sua API e que ela funcione na primeira vez, sempre. Faça com que novas pessoas tentem implementar sua API ocasionalmente para verificar se ela não é confusa de alguma forma à qual você se tornou imune.

• Mantenha simples. Não faça nenhuma autenticação extravagante. Não faça algum esquema de URL personalizado maluco. Não reinvente SOAP, JSON, REST ou qualquer coisa. Use todas as ferramentas que você puder que já foram implementadas e são amplamente aceitas, para que os desenvolvedores tenham apenas que aprender sua API, não sua API + 10 novas tecnologias obscuras.

• Forneça bibliotecas específicas de idioma para interagir com seu serviço. Existem algumas ferramentas legais para gerar automaticamente uma biblioteca para você, como Alpaca ou Apache Thrift. Atualmente Alpaca suporta Node, PHP, Python e Ruby. Thrift suporta C++, Java, Python, PHP, Ruby, Erlang, Perl, Haskell, C#, Cocoa, JavaScript, Node.js, Smalltalk, OCaml, Delphi e muito mais.

• Simplifique qualquer inscrição necessária. Se você não estiver desenvolvendo uma API de código aberto ou se houver um processo de inscrição de qualquer tipo, certifique-se de que, ao se inscrever, um usuário seja direcionado rapidamente para um tutorial. E torne o processo de inscrição totalmente automatizado sem a necessidade de interação humana de sua parte.

• Fornecer excelente suporte. Uma grande barreira para a adoção é a falta de apoio. Como você lidará e responderá a um relatório de bug? E quanto à documentação pouco clara? Um usuário não sofisticado? Fóruns, rastreadores de bugs e suporte por e-mail são começos fantásticos, mas certifique-se de que quando alguém postar um bug, você realmente o resolva. Ninguém quer ver um fórum de cidade fantasma ou uma lista gigante de bugs que não foram resolvidos.

Conclusão da API da Web

Os serviços da Web e suas APIs são abundantes. Infelizmente, a grande maioria é difícil de usar. Os motivos variam de design ruim, falta de documentação, volatilidade, bugs não resolvidos ou, em alguns casos, todos os itens acima.

Seguir as orientações desta postagem ajudará a garantir que sua API da Web seja limpa, bem documentada e fácil de usar. Essas APIs são realmente raras e, portanto, são muito mais propensas a serem amplamente adotadas e usadas.