Por um mundo com APIs mais organizadas!

Todos os desenvolvedores de software sabem que um projeto pode facilmente tornar-se uma confusão, e API’s não fogem dessa realidade. Mas o que podemos fazer para desviar desse caminho e criar APIs que funcionem perfeitamente e também sejam amigáveis para quem irá utilizá-las? Neste post cobrirei algumas boas práticas que nos ajudam a atingir estes objetivos.

O desenvolvimento de uma API é diferente do desenvolvimento de outros tipos de software já que estamos criando uma interface para outros programadores que provavelmente serão tão críticos com seu trabalho quanto você será com o deles, uma vez todos já sentiram na pele as dificuldades de utilizar softwares mal construídos.

Porém, para criarmos boas APIs devemos pensar não só como desenvolvedores (com foco em suas funções e quais problemas deve resolver), mas também como usuários; devemos pensar em COMO ela será utilizada, preocupando-nos em desenvolver estas funcionalidades da forma mais acessível.

Existem algumas práticas que podemos empregar durante o desenvolvimento que nos ajudarão a manter o projeto organizado e compreensível. Cito aqui algumas que considero mais importantes:

Documentação

Geralmente a ÚLTIMA preocupação de um desenvolvedor é documentar o que um serviço faz e como faz, mas pense nas inúmeras vezes que você teve que utilizar uma API sem uma boa documentação. Ela é essencial se você espera que alguém utilize a sua API da maneira exata como você a planejou.

Uma maneira relativamente fácil de começar sua documentação é documentar seus métodos (o que eles fazem, exemplos de requisições e respostas, endpoints, etc). E para ir além, considere incluir exemplos e tutoriais, que ajudarão seus usuários a entender sua API.

Consistência

Uma boa API é desenvolvida e mantida sempre pensando no total suporte a seus usuários, estejam eles utilizando sua primeira versão ou seu último lançamento com inúmeras modificações. Por isso é necessário manter versões antigas em funcionamento por um bom período de tempo.

Além de se manterem estáveis ao longo de sua “vida”, APIs precisam se manter consistentes internamente, por exemplo, utilizar o mesmo nome para parâmetros e informações comuns em toda a API.

E por último, mantenha sempre um arquivo de log para especificar as mudanças e mostrar a diferença entre as versões, de modo que os usuários possam decidir quando atualizar.

Flexibilidade

É impossível prever todas as formas que os usuários irão interagir com seu serviço; portanto, é necessário manter um certo nível de flexibilidade com relação aos dados de entrada.

Por exemplo, muitas APIs suportam vários formatos de saída, como JSON, YAML, XML, etc, que podem ser especificados na URL da requisição (isto é, /api/v1/operations.json).

Um outro exemplo são maneiras diferentes de passar os parâmetros dos endpoints. Assim, da mesma forma que sua API suporta vários formatos de saída ela pode também suportar vários formatos de entrada (isto é, variáveis POST simples, JSON, XML, etc), uma vez que cada desenvolvedor tem sua preferências técnicas.

Segurança

Segurança é um dos pontos mais importantes a serem considerados no desenvolvimento de sua API, especialmente se ela trata de dados que não devem ser acessados por qualquer um.

Como desenvolvedor você deve prover exemplos de como os usuários devem se autenticar: se existe a necessidade de escrever qualquer código, isso não deve levar mais do que 5 minutos.

Para a maioria das APIs, podemos usar umas simples autenticação baseada em token com um certificado SSL, onde o token é uma string única e aleatória atribuída para o usuário e que pode ser redefinida a qualquer momento. O serviço pode ser escrito de forma que este token seja passado pela requisição POST ou pelo cabeçalho HTTP. Devemos escolher um token seguro, até mesmo irreversível. Por exemplo, basta gerar um token SHA durante o cadastro ou login do usuário e atribuí-lo a ele no banco de dados. Então podemos consultar a base através desse token e recuperar o usuário ao qual ele pertence.

Além disso devemos prestar atenção em outras questões como validação de acesso a recursos:

1)verificar se mesmo usuários autenticados podem de fato utilizar o recurso requisitado;

2) validar os dados de entrada;

3) autorizar explicitamente as operações permitidas para cada entidade, etc.

Concluindo

Existem muitos APIs de uso privado e público, para resolver problemas específicos e (tentar) facilitar a nossa vida como desenvolvedores. Infelizmente, em sua grande maioria, são difíceis de usar, seja por um design fraco, por falta de documentação, bugs, ou por todos esses fatores reunidos.

Para que a sua API não se encaixe em nenhuma dessas situações, existem diversos fatores que devemos considerar na hora de desenvolvemos nossas APIs de serviços, mas se você utilizar as dicas deste post como guia básico, seu software será certamente adotado por outros desenvolvedores.

Deixe uma resposta

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