Boas práticas no design de APIs

Com a popularização de arquiteturas como Service Oriented Architecture (SOA) e recentemente de arquiteturas baseadas em microsserviços, torna-se cada vez mais importante compreender algo que está na base destas tecnologias: o projeto e desenvolvimento de Application Programming Interface (APIs).

Uma API é um conjunto de interfaces de serviços utilizados por outras aplicações, que não precisam entender como exatamente esses serviços funcionam, tratando-os como uma caixa-preta. Uma API pode ser privada, quando é exposta apenas nos limites de uma organização, ou pública, quando esses serviços são oferecidos para que qualquer desenvolvedor possa utilizá-los para construir suas próprias aplicações.

A primeira decisão que enfrentamos ao projetar uma API é escolher quais serviços serão oferecidos e em qual granularidade. É preciso decidir se é melhor oferecer menos serviços, mais pesados, ou dividi-los em diversos serviços menores e mais rápidos, mas que exigirão mais chamadas por parte do cliente. Essa decisão deve ser tomada pensando em como se espera que as aplicações do cliente utilizem os serviços da API sendo criada.

Serviços de maior granularidade são aqueles que realizam serviços de mais alto nível, como APIs destinadas à integração de sistemas corporativos, por meio de SOA, por exemplo. Nesse caso, estamos falando de grandes serviços, geralmente com grande carga de processamento envolvido. Por outro lado, serviços pequenos, ou microsserviços são utilizados em APIs destinadas a serem usadas como bibliotecas ou caixas de ferramentas para outros desenvolvedores. Assim, é preciso avaliar a granularidade correta para cada caso.

Um fator a ser observado, no entanto, é a modularidade dos serviços sendo expostos. Por um lado, os diversos serviços de uma API estarão relacionados a um objetivo comum, porém, quando analisamos cada um destes serviços, é importante que eles sejam independentes entre si, isto é, cada serviço deveria poder ser chamado de forma independente e não esperando que sejam chamados em uma ordem especifica, ou seja, não dependendo do resultado de outros para funcionar corretamente.

Assim como uma aplicação, uma API também estará sempre em evolução, seja por oferecer novos serviços ou sofrendo manutenções corretivas. Porém, nesse caso tem-se uma preocupação a mais: oferecer novos serviços ou atualizações sem que os clientes já existentes da API sejam obrigados a realizar mudanças em seus códigos. Isso é ainda mais crítico no caso de APIs públicas, que não têm o controle sobre os clientes.

Sempre que possível, uma API deve evoluir a partir do acréscimo de novas interfaces, sem alterar as já existentes. Isso possibilita que clientes utilizem a nova versão e, ao mesmo tempo, permite que os clientes antigos possam fazer a migração no seu próprio tempo, se assim o desejarem.

Um outro aspecto a considerar é a segurança no acesso da API. Em diversos setores, como o financeiro, é de fundamental importância garantir que quem está acessando o serviço seja, de fato, um usuário autorizado.

Ao contrário de uma aplicação web, na qual após a autenticação as informações do cliente podem ser armazenadas na sessão, uma API de serviços é stateless, ou seja, não deve se lembrar de chamadas de serviços anteriores.  No caso mais comum de APIs via web, essa autenticação é realizada por meio de tokens. Um servidor de autorização é responsável por fornecer ao cliente, uma vez autenticado, um token, que é de responsabilidade do cliente e deve ser enviado à API a cada nova requisição de serviço como um documento de identidade.

Longe de pretender esgotar o assunto com o debate acerca das boas práticas para o design de APIs, os assuntos aqui levantados são pontos de partida para uma análise que deve sempre ser realizada de acordo com as necessidades específicas do projeto e do cliente, afinal não existem dois projetos iguais.

*Mauricio Camillo é arquiteto de sistemas da GFT