APIs do Google, Twitter, GitHub, React, DOM. Parece que tudo se transformou em APIs? O que é uma API e porque este conceito passou a ser tão onipresente? A grande maioria dos aplicativos que utilizamos hoje em dia possuem alguma forma de interface construída exclusivamente para a interação humana. Podendo ser elementos gráficos em um site ou aplicativo móvel, chatbot, ou, até mesmo uma voz condensada em um(a) assistente pessoal.

Humano vs Máquina

Existe ainda um tipo particular de interface, aquela construída com intuito de integrar diferentes softwares e/ou máquinas. Essa talvez seja a pior definição possível sobre o que é uma API, mas espero que seja possível compreender minha linha de raciocínio. API - Interface de programação de aplicativo (onde programação é a palavra-chave).

Quando pensamos na construção de software, em diferentes momentos existe a possibilidade ou a necessidade de que soluções troquem informação entre si, máquina para máquina, e nesse sentido a única interface de comunicação entre elas é uma API. É importante entender aqui que sua definição não está profundamente ligada a REST APIs (falaremos sobre isso no futuro) e que existem múltiplos protocolos de comunicação que possibilitam essa troca de informações.

Existem sim soluções que prometem um nível bastante amigável de implementação quanto ao desenvolvimento de software, usando inclusive o conceito de drag in drop, mas, nesse momento ainda é particularmente difícil definir todas as especificidades de um software e abstrair a necessidade de um humano, desenvolvedor, construindo definições e estratégias de implementação, ou para o melhor entendimento, transcrevendo regras do mundo físico para universo digital, esse cenário hoje se mostra tão confuso quanto seria para um pedestre pedir comida na janela de um drive-through ou para um motorista dirigir seu carro direto para a mesa de um restaurante, simplesmente não é a melhor ferramenta para o trabalho.

É especialmente difícil para um software conviver com qualquer tipo de mudança e abstrair ou modificar o comportamento de suas interfaces, assim como é habitual para qualquer ser humano adaptar-se a qualquer tipo de mudança em seu cotidiano, isso nos leva a dois aspectos aos quais eu considero os mais importantes na construção de uma API, e o que os diferencia essencialmente das interfaces de usuário que discorremos no início deste post. Formato e Contrato.

Formato

O formato é o conjunto de tecnologias e linguagens utilizadas pelo software para interagir com o consumidor. Uma vez que o consumidor é a máquina, as solicitações e respostas devem ser construídas de forma otimizada com as máquinas - linguagem de sinais, canções ou poesia são formas interessantes para os humanos se comunicarem, mas não tão eficientes quando se trata de máquinas.

Contrato

O contrato é o que garante aos desenvolvedores que uma API continuará a responder às solicitações de seus softwares de maneira consistente. Veja, caso em uma interface gráfica exista apenas botão verde nos cantos superior esquerdo e o modifiquemos para um botão vermelho no canto inferior direito, a maioria das pessoas se adapta instintivamente e continua usando o software sem nenhuma instrução ou assistência.

Enquanto que, os softwares são um pouco mais controlados, Caso uma API mude qualquer definição sem dar aos desenvolvedores a oportunidade de atualizar seu código, ou ainda sem manter a retrocompatibilidade, softwares inteiros podem falhar.

Os contratos são uma forma de APIs anunciarem exatamente o que produzem e o que recebem, contanto que os desenvolvedores sigam as regras que foram estabelecidas antecipadamente, as coisas continuarão a funcionar da mesma maneira.

Versionamento e Retrocompatibilidade

Retrocompatibilidade parte da necessidade de manter o funcionamento atual do código a partir da implementação de novas features. Este é um termo usado para apontar que os novos recursos, no escopo de software, são compatíveis com os anteriores. Usando um ambiente real como exemplo, o novo Playstation 5 da Sony é retrocompatível com os jogos disponíveis em sua versão anterior o Playstation 4, o que significa que você pode utilizar seus games sem nenhum tipo de impacto na nova versão.

Para lidar de forma mais assertiva com a retrocompatibilidade das APIs criou-se a diretriz de versionamento, onde mantemos o comportamento atual em uma respectiva versão, e implementamos todas as modificações em sua nova versão.

Como um bom exemplo, podemos olhar para um cadastro comum de usuários. Onde uma API recebe os dados usuais para seu processamento.

/v1/user

Quando da necessidade de mudança desse comportamento, por exemplo a inclusão de novos atributos ou de novas respostas desta API, caso não criemos uma nova versão, possivelmente o comportamento dos softwares que consomem esse recurso será impactado.

/v2/user

Subsequentemente existe também a atualização ou reconstrução do contrato desta API. Se define nesta fase também, a validade da API que foi mantida como retrocompatível, a fim de informar a todos os desenvolvedores qual é a validade da versão anterior, e qual é o prazo disponível para a migração.

Paradigmas de API

Então, como você constrói uma API? Existe um conjunto específico de tecnologias e ferramentas que você deve usar? Na verdade não.

Contanto que você use um formato apropriado e coloque um contrato em vigor, você pode usar qualquer paradigma de programação, linguagem ou tecnologia que desejar, até mesmo um arquivo JSON estático em um servidor pode funcionar como uma API, se documentado e publicado corretamente.

Existem, no entanto, algumas diretrizes e especificações que se aplicam às APIs da Web, que conectam um servidor e um cliente pela Web usando o protocolo HTTP. Estas são apenas recomendações sobre coisas como convenções de nomenclatura, quais URLs expor e como transmitir estados de sucesso e erro.

RPC

O paradigma mais antigo era o RPC (Remote Procedure Call), que basicamente funciona como uma função executada em um servidor remoto. Se você quiser criar uma API RPC para adicionar, editar e remover artigos, terá um endpoint em /getArticles para recuperar itens, /addArticle para criar, etc. Como uma função na memória, cada endpoint RPC pode aceitar qualquer número de argumentos.

REST

Uma alternativa mais popular, flexível e usual hoje em dia é o REST (REpresentational State Transfer) e funciona representando entidades como recursos. Em nosso exemplo acima, um artigo seria um recurso, representado em /articles. Para interagir com este recurso, espera-se que o cliente utilize um dos verbos HTTP disponíveis para indicar o tipo de operação - GET para leitura, POST para criação, PATCH ou PUT para atualização e DELETE para exclusão. O REST é caracterizado por utilizar recursos HTTP sempre que possível, como verbos, cabeçalhos e códigos de status.

GraphQL

Um paradigma mais recente que vem ganhando muita força é o GraphQL. Ao contrário de RPC ou REST, GraphQL expõe uma única URL para todas as interações, contando com uma linguagem de consulta personalizada (semelhante ao SQL) para informar ao servidor exatamente quais dados obter e em qual estrutura. É possível que uma única consulta recupere dados de várias coleções de documentos e resolva automaticamente os relacionamentos entre eles. O GraphQL tem um forte foco no desempenho, permitindo que os consumidores recebam apenas os campos de que precisam (embora esse comportamento às vezes seja falsamente retratado como exclusivo do GraphQL, pois o REST também o suporta).

Conclusões

Deste modo, entendemos que APIs são apenas e tão somente mais um tipo possível de interface de comunicação entre máquinas e/ou softwares, estabelecendo formato(s) específico(s) baseado em contratos de trabalho. Em breve vamos discutir por aqui sobre como criar APIs e entrar com mais profundidade no universo dos micro serviços.

Vem comigo, que no caminho eu te explico...