Com a popularização de arquiteturas como SOA (Service Oriented Architecture) 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 API’s (Application Programming Interface).

Uma API é um conjunto de interfaces de serviços que são oferecidos para serem utilizados por outras aplicações, que não precisam entender como exatamente estes serviços funcionam, tratando-os como uma caixa-preta. Uma API pode ser privada, quando é exposta apenas dentro dos limites de uma organização, ou pública, quando estes 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 que 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. Esta 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 as API’s destinadas à integração de sistemas corporativos, através de SOA, por exemplo. Neste caso, estamos falando de grandes serviços, geralmente com grande carga de processamento envolvido. Por outro lado, serviços pequenos, ou micros serviços são utilizados em API’s 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, neste 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 API’s públicas, que não têm o controle sobre os clientes.

Sempre que possível, uma API deve evoluir através 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 API’s via web, essa autenticação é realizada através 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 API’s, 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.