Boas práticas no design de API’s

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 dividí-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.

* Mauricio Camillo é arquiteto de sistemas da GFT, companhia de Tecnologia da Informação especializada em Digital para o setor financeiro

Sobre a GFT Technologies SE

A GFT Technologies SE (GFT) é uma consultoria de tecnologia com experiência em viabilizar mudanças nos negócios e que conta com a total confiança por parte de importantes instituições de serviços financeiros para resolver seus desafios de negócios mais críticos. Especificamente quanto à definição de respostas em face às constantes mudanças regulatórias atuais – além de promover inovação para atender às demandas da revolução digital.

A GFT oferece assessoria, capacidades criativas e tecnológicas aliadas a uma cultura de inovação e conhecimento especializado do setor de finanças para transformar os negócios de nossos clientes.

Por meio da plataforma de inovação CODE_n, a GFT oferece às start-ups internacionais, aos pioneiros de tecnologia e às empresas estabelecidas no mercado o acesso a uma rede global, o que lhes permite aproveitar as tendências disruptivas do mercado de serviços financeiros e aproveitar ao máximo seu pensamento inovador

Com sede na Alemanha, a GFT Technologies SE obteve uma receita consolidada de cerca de 374 milhões de euros em 2015 e conta com uma equipe global que abrange 12 países e mais de 4000 colaboradores. As ações da GFT estão listadas na Bolsa de Frankfurt no TecDAX (ISIN: DE0005800601).