Introdução

API é um acrônimo para Application Programming Interfaces, que em tradução livre quer dizer: “Interface de Programação de Aplicações/Aplicativos”.

Na prática, são construções de programação que permitem a desenvolvedores criar funcionalidades mais complexas contendo abstração de código, de forma que seja simples sua utilização.

No dia a dia do desenvolvimento de software as APIs entram em cena quando um aplicativo precisa se conectar a outro aplicativo. Mas como?

Tudo começa quando uma aplicação, seja ela front-end ou back-end, inicia uma interação com outra aplicação por meio de uma requisição. Após a recepção dessa requisição, dentro dos parâmetros pré-estabelecidos, a aplicação receptora, realiza a rotina prevista e entrega o dado solicitado por meio de uma resposta.

A MDN¹ em sua documentação traz uma analogia que nos ajuda a desmistificar esse processo:

”Pense no seguinte exemplo: o uso de energia elétrica em sua casa ou apartamento. Quando você deseja utilizar um eletrodoméstico, você precisa somente ligar o aparelho na tomada. Não é preciso conectar diretamente o fio do aparelho diretamente na caixa de luz. Isso seria, além de muito ineficiente, difícil e perigoso de ser feito (caso você não seja eletricista).”

Nesta analogia a tomada e o plug seriam as APIs que se conectam e, transmitem o dado solicitado: a energia elétrica.

Todo esse processo é chamado de transação de API, que pode ocorrer com ou sem acesso a Web. Pois nem todas as APIs são Web APIs.

Tanto as requisições como as respostas podem assumir diversos formatos, à depender da arquitetura e tipo de API, conforme veremos a seguir.

Tipos de API

Existem várias formas de categorizar as APIs, a maneira geralmente utilizada é baseada no escopo de uso pretentido. Em se tratando de escopo, podemos dividir em quatro principais tipos de APIs, que são:

• API Aberta/pública (Open/public)

  Como o nome bem sugere uma API Pública está publicada e documentada publicamente, podendo ser acessada por quem tiver o interesse de fazê-lo. Em alguns casos é necessário o uso de alguma chave de autenticação e ou cabeçalho específico, quais estarão na documentação da mesma. Exigindo assim, pouco ou nenhum gerenciamento de identidade. São exemplos:

  • Nasa - https://api.nasa.gov/
  • AccuWeather - https://developer.accuweather.com/
  • Correios - https://cws.correios.com.br/ajuda

• API de Parceiro (Partner)

  Este tipo de API é baseado em licença usada para facilitar a comunicação entre aplicativos em nível B2B (business to business). API de parceiro destina-se ao uso por parceiros de negócios pagantes para facilitar a comunicação entre vários aplicativos corporativos. Como as APIs de parceiros exigem mecanismos de autorização, mecanismos de autenticação e medidas gerais de segurança mais fortes, elas são muito mais seguras do que as APIs públicas.

• API Privada (Private)

  Este tipo também pode ser chamado de API interna, pois é hospedada na infraestrutura interna de um negócio/empresa, estando disponível apenas aos desenvolvedores envolvidos na aplicação e uso da mesma, mediante as regras de acesso existentes. O nível de segurança e arquitetura adotada dependerão da postura do negócio.

• API Composta (Composite)

  Uma API composta combina sequencialmente solicitações de API em uma única chamada de API. As APIs compostas permitem que os clientes usem o encadeamento de chamadas para fazer várias chamadas de API e receber uma resposta em vez de várias respostas. Geralmente útil para velocidade e eficiência ao fazer chamadas de API complexas entre cliente e servidor.

Tipos/Padrões de Arquitetura

Além de se categorizar por tipos, as APIs distinguem-se quanto ao estilo/arquitetura adotado na sua construção. Tal taxonomia geralmente se baseia no protocolo de comunicação adotado. A seguir falarei dos tipos mais populares, quando se trata de web API (API criada para comunicação web)

REST
1. Segue 6 restrições de arquitetura
2. Pode usar JSON, XML, HTML ou Plain Text
3. Flexível, leve e escalável
4. Formato mais utilizado na web
5. Utiliza HTTP como protocolo

REST é sem dúvida um dos padrões mais populares no desenvolvimento voltado para web. REST significa Representational State Transfer (Transferência de Estado Representacional). As Aplicações que utilizam esse padrão de arquitetura são comumente denominadas RESTful. REST é um conjunto de definições arquitetônicas e, não um protocolo ou padrão, podendo ser implementadas de várias maneiras.
Quando uma solicitação do cliente é feita por meio de uma API RESTful, ela transfere uma representação do estado do recurso para o solicitante ou terminal. Essas informações ou representações são entregues em um dos vários formatos via HTTP: JSON (notação de objeto Javascript), HTML, XLT, Python, PHP ou texto sem formatação. O JSON é o formato de arquivo mais popular para usar, porque, apesar do nome, é um diagnóstico de linguagem e legível por humanos e máquinas.

Outra coisa a ter em mente: os cabeçalhos e parâmetros também são importantes nos métodos HTTP de uma solicitação HTTP da API RESTful, pois contêm informações importantes sobre o identificador dos metadados da solicitação, autorização, identificador uniforme de recursos (URI), cache, cookies e mais. Existem cabeçalhos de solicitação e cabeçalhos de resposta, cada um com suas próprias informações de conexão HTTP e códigos de status.²
Para que uma API possa ser considerada RESTful, deve seguir os seguintes critérios:

• Uma arquitetura cliente-servidor composta por clientes, servidores e recursos, com solicitações gerenciadas por HTTP;
• Comunicação apátrida cliente-servidor, o que significa que nenhuma informação do cliente é armazenada entre as solicitações de obtenção e cada solicitação é separada e desconectada;
• Dados cacheados, que simplificam as interações cliente-servidor;

• Uma interface uniforme entre componentes para que as informações sejam transferidas de forma padrão. Isso requer que:
  - os recursos solicitados são identificáveis e separados das representações enviadas ao cliente.
  - os recursos podem ser manipulados pelo cliente através da representação que recebem, porque a representação contém informações suficientes para fazê-lo.
  - as mensagens auto-descritivas retornadas ao cliente têm informações suficientes para descrever como o cliente deve processá-lo.
  - hipertexto / hipermídia está disponível, o que significa que, após acessar um recurso, o cliente deve poder usar hiperlinks para encontrar todas as outras ações disponíveis no momento que possam executar.

• Um sistema em camadas que organiza cada tipo de servidor (responsável pela segurança, balanceamento de carga etc.).) envolveu a recuperação das informações solicitadas em hierarquias, invisíveis para o cliente.

• Código sob demanda (opcional): a capacidade de enviar código executável do servidor para o cliente quando solicitado, estendendo a funcionalidade do cliente.

• Apesar dos diversos critérios uma API RESTful é simples de ser criada, razão pela qual é o modelo arquitetônico mais popular na web, podendo ser adotado nas mais diversas situações existentes no dia a dia.

SOAP
1. Estrutura de mensagem estritamente definida que depende de XML
2. Protocolo independente
3. Seguro e extensível
4. Utilizado em ambiente empresarial seguro

SOAP é um acrônimo para Simple Object Access Protocol (Protocolo de Acesso a Objeto Simples), sendo um protocolo padrão que foi projetado pela primeira vez para que aplicativos criados com diferentes idiomas e em diferentes plataformas pudessem se comunicar, fazendo com que seja conhecido por sua extensibilidade e independência de estilos de programação. Além disso, este é um protocolo dito neutro. Isto é, pode operar sob diferentes tipos de protocolos, como HTTP, SMTP, TCP e outros.
Por ser um protocolo, impõe regras internas que aumentam sua complexidade e sobrecarga, o que pode levar a tempos de carregamento mais longos da página. No entanto, esses padrões também oferecem conformidade interna (compliance) que podem torná-lo preferível para cenários corporativos. Os padrões de conformidade internos incluem segurança, atomicidade, consistência, isolamento e durabilidade (ACID), que é um conjunto de propriedades para garantir transações confiáveis no banco de dados.
A especificações mais comuns desse protocolo são:

• Segurança de serviços da Web (segurança WS): padroniza como as mensagens são protegidas e transferidas por meio de identificadores exclusivos chamados tokens.
• Serviço web de mensagens confiáveis: padroniza o tratamento de erros entre as mensagens transferidas pela infraestrutura de TI não confiável.
• Endereçamento de serviços da Web (endereço WS): empacotar informações de roteamento como metadados nos cabeçalhos SOAP, em vez de manter essas informações mais profundas na rede.
• Linguagem de descrição de serviços da Web (WSDL): descreve o que um serviço da Web faz e onde esse serviço começa e termina. Quando uma solicitação de dados é enviada para uma API SOAP, ela pode ser tratada através de qualquer um dos protocolos da camada do aplicativo: HTTP (para navegadores da web), SMTP (para email), TCP e outros. No entanto, uma vez recebida uma solicitação, as mensagens SOAP de retorno devem ser retornadas como documentos XML - uma linguagem de marcação legível por humanos e máquinas. Uma solicitação concluída para uma API SOAP não pode ser armazenada em cache por um navegador, portanto não pode ser acessada posteriormente sem reenviar para a API³.

RPC

1. Procedimento baseado em ação, ótimo para sistemas baseados em comando
2. Usa apenas HTTP GET e POST
3. Tem payloads leves que permitem maior performance
4. usados em sistemas distribuídos

RPC significa Remote Procedural Call, em português, Chamada Procedural Remota. Este protcolo permite que uma aplicação chame, remotamente, um procedimento de outra (via internet ou intranet).

Este tipo de API é o mais antigo e básico, sendo uma arquitetura cliente-servidor para construir aplicações distribuídas, que normalmente exigem que os desenvolvedores executem blocos específicos de código em outro sistema.

O RPC é agnóstico em termos de protocolo, o que significa que tem o potencial de ser compatível com muitos protocolos, mas também perde os benefícios de usar recursos nativos de alguns protocolos como armazenamento em cache.

Para oferecer suporte a chamadas de API para serviços em redes externas, o RPC depende de uma linguagem de definição de interface (IDL) que atua como um link de comunicação entre servidores localizados em diferentes redes externas criadas usando diferentes linguagens de programação.

As APIs do tipo RPC podem se comunicar por meio de chamadas com multi parâmetros, que retornam um único resultado nos formatos JSON (JSON-RPC) ou XML (XML*-RPC*)

Há ainda as APIs baseadas em eventos/streamings, que também são chamadas de arquiteturas orientadas à eventos, em tempo real (real time), de streaming, assíncronas ou push. Esse tipo de API não espera que o consumidor chame-a para que possa enviar uma resposta. Em vez disso, uma resposta é disparada pela ocorrência de um evento. Como exemplo, esses serviços expõem eventos nos quais os clientes podem se inscrever para receber atualizações quando os valores no serviço mudam. Há muitas variações para esse estilo, incluindo (entre outros) reativo, publicação e assinatura, notificação de eventos e CQRS.

Numa próxima oportunidade, trataremos de GraphQL que não é um padrão de arquitetura de API, mais sim um tipo de linguagem de consulta que pode ser adotado. Um outro tema muito empolgante, são os formatos de dados que podem trafegar entre APIs.

Spoiler: Não! Não é apenas JSON 🤭

Conclusão

O tipo e arquitetura de uma API pode variar muito, dependendo do tipo de informação que irá entregar, quantidade de consultas simultâneas, velocidade, acesso, etc. E o time de desenvolvimento que deverá levantar os requisitos para eleger o melhor formato/arquitetura para a aplicação em questão.

Aqui quis trazer luz sobre os formatos mais comuns no dia a dia do desenvolvimento. Você já os conhecia? Utiliza outro?

Até a próxima 👋🏾

Fontes:

¹ https://developer.mozilla.org/pt-BR/docs/Learn/JavaScript/Client-side_web_APIs/Introduction

² https://www.redhat.com/en/topics/api/what-is-a-rest-api

³ https://www.redhat.com/en/topics/integration/whats-the-difference-between-soap-rest#soap