A folha de referências do design do sistema: estilos de API - REST, GraphQL, WebSocket, Webhook, RPC/gRPC, SOAP

Esta é a continuação de uma série de artigos nos quais abordo brevemente os principais pontos de um tópico específico no projeto de arquitetura de sistemas. O primeiro artigo pode ser lido aqui

A arquitetura da API refere-se ao conjunto de regras, protocolos e ferramentas que determinam como os componentes de software devem interagir. A arquitetura de uma API não visa apenas facilitar a comunicação; trata-se também de garantir que essa comunicação seja eficiente, segura e escalável.

Uma arquitetura de API bem projetada pode melhorar significativamente o desempenho de um sistema, enquanto uma arquitetura mal projetada pode levar a gargalos, vulnerabilidades de segurança e pesadelos de manutenção.

Diferentes estilos de arquitetura de API

Os estilos de design de API mais comuns:

1. REST (Representational State Transfer) é o estilo mais utilizado que utiliza métodos padrão e protocolos HTTP. É baseado em princípios como apatridia, arquitetura cliente-servidor e capacidade de cache. É frequentemente usado entre clientes front-end e serviços back-end.

   
   

2. GraphQL é uma linguagem de consulta para APIs. Ao contrário do REST, que expõe um conjunto fixo de endpoints para cada recurso, o GraphQL permite que os clientes solicitem exatamente os dados de que precisam, reduzindo a busca excessiva.

   
   

3. WebSocket é um protocolo que permite comunicação bidirecional sobre TCP. Os clientes usam web sockets para obter atualizações em tempo real de sistemas back-end.

   
   

4. Webhook é um mecanismo que permite que um sistema notifique outro sistema sobre eventos específicos em tempo real. É um retorno de chamada HTTP definido pelo usuário.

   
   

5. RPC (gRPC) é um protocolo que um serviço pode usar para solicitar um procedimento/método de um serviço localizado em outro computador em uma rede. Normalmente, ele é projetado para comunicação de baixa latência e alta velocidade.

   
   

6. SOAP é um protocolo para troca de informações estruturadas para implementar serviços web. Baseia-se em XML e é conhecido por sua robustez e recursos de segurança, sendo atualmente considerado um protocolo legado.

Vejamos cada protocolo separadamente com todos os seus prós, contras e casos de uso.

DESCANSAR

REST é um estilo de arquitetura que utiliza convenções e protocolos padrão, facilitando a compreensão e a implementação. Sua natureza sem estado e o uso de métodos HTTP padrão tornam-no uma escolha popular para a construção de APIs baseadas na web.

Embora REST tenha sido o padrão de fato para a construção de APIs por muito tempo, outros estilos como GraphQL surgiram, oferecendo diferentes paradigmas para consulta e manipulação de dados.

Formato : XML, JSON, HTML, texto simples

Protocolo de transporte : HTTP/HTTPS

Principais conceitos e características

• Recurso : Em REST, tudo é um recurso. Um recurso é um objeto com um tipo, dados associados, relacionamentos com outros recursos e um conjunto de métodos que operam nele. Os recursos são identificados pelos seus URIs (normalmente um URL).

  
  

• Operações CRUD : os serviços REST geralmente mapeiam diretamente para operações CRUD (Criar, Ler, Atualizar, Excluir) em recursos.

  
  

• Métodos HTTP : os sistemas REST usam métodos HTTP padrão:

  • GET: Recupera um recurso.

  • POST: Crie um novo recurso.

  • PUT/PATCH: Atualize um recurso existente.

  • DELETE: Remove um recurso.

    
    

• Códigos de status : APIs REST usam códigos de status HTTP padrão para indicar o sucesso ou a falha de uma solicitação de API:

  • 2xx - Reconhecimento e Sucesso
    • 200 - OK
    • 201 - Criado
    • 202 - Aceito
  • 3xx - Redirecionamento
    • 301 mudou-se permanentemente
    • 302 - Encontrado
    • 303 - Veja outro
  • 4xx - Erro do cliente
    • 400 - Solicitação incorreta
    • 401 não autorizado
    • 403 - Proibido
    • 404 não encontrado
    • 405 - Método não permitido
  • 5xx - Erro do servidor

    • 500 - Erro interno do servidor

    • 501 - Não implementado

    • 502 Bad Gateway

    • 503 serviço indisponível

    • 504 - Tempo limite do gateway

      
      

• Stateless : Cada solicitação de um cliente para um servidor deve conter todas as informações necessárias para compreender e processar a solicitação. O servidor não deve armazenar nada sobre o estado do cliente entre as solicitações.

  
  

• Cliente-Servidor : REST é baseado no modelo cliente-servidor. O cliente é responsável pela interface e experiência do usuário, enquanto o servidor é responsável por processar solicitações, manipular a lógica de negócios e armazenar dados.

  
  

• Armazenável em cache : as respostas do servidor podem ser armazenadas em cache pelo cliente. O servidor deve indicar se uma resposta pode ser armazenada em cache ou não.

  
  

• Sistema em camadas : Um cliente normalmente não pode dizer se está conectado diretamente ao servidor final ou a um intermediário. Os servidores intermediários podem melhorar a escalabilidade do sistema, permitindo o balanceamento de carga e fornecendo caches compartilhados.

  
  

• HATEOAS: Hypermedia As The Engine Of Application Stat é um princípio de serviço web REST que permite aos clientes interagir e navegar por um aplicativo web inteiramente baseado na hipermídia fornecida dinamicamente pelo servidor em suas respostas, promovendo acoplamento fraco e capacidade de descoberta.

Casos de uso

• Serviços Web : Muitos serviços Web expõem sua funcionalidade por meio de APIs REST, permitindo que desenvolvedores terceirizados integrem e ampliem seus serviços.

• Aplicativos móveis : os aplicativos móveis geralmente se comunicam com servidores back-end usando APIs REST para buscar e enviar dados.

• Aplicativos de página única (SPAs) : os SPAs usam APIs REST para carregar conteúdo dinamicamente sem exigir uma atualização completa da página.

• Integração entre sistemas: os sistemas dentro de uma organização podem se comunicar e compartilhar dados usando APIs REST.

Exemplo

Solicitar

OBTER “/usuário/42”

Resposta

 { "id": 42, "name": "Alex", "links": { "role": "/user/42/role" } }

GráficoQL

GraphQL oferece uma abordagem mais flexível, robusta e eficiente para a construção de APIs, especialmente em sistemas complexos ou quando o frontend precisa de alta flexibilidade. Ele transfere parte da responsabilidade do servidor para o cliente, permitindo que o cliente especifique seus requisitos de dados.

Embora não substitua o REST em todos os cenários, ele oferece uma alternativa atraente em muitas situações, principalmente à medida que os aplicativos se tornam mais interligados e distribuídos.

Formato : JSON

Protocolo de transporte : HTTP/HTTPS

Principais conceitos e características

• Linguagem de consulta para APIs : permite que os clientes solicitem os dados que necessitam, possibilitando obter todas as informações necessárias em uma única solicitação.

• Sistema de tipos : APIs GraphQL são organizadas em termos de tipos e campos, não de terminais. Ele usa um sistema de tipo forte para definir os recursos de uma API. Todos os tipos expostos em uma API são escritos em um esquema usando a linguagem de definição de esquema GraphQL (SDL).

• Endpoint único : ao contrário do REST, onde você pode ter vários endpoints para recursos diferentes, no GraphQL, você normalmente expõe um único endpoint que expressa o conjunto completo de recursos do serviço.

• Resolvedores : No lado do servidor, os resolvedores reúnem os dados descritos em uma consulta.

• Atualizações em tempo real com assinaturas : além de apenas consultar dados, o GraphQL inclui suporte integrado para atualizações em tempo real usando assinaturas.

• Introspectivo : um servidor GraphQL pode ser consultado quanto aos tipos que suporta. Isso cria um contrato forte entre cliente e servidor, permitindo ferramentas e melhor validação.

Casos de uso

• Frontends flexíveis : para aplicativos (especialmente móveis) com largura de banda crucial, você deseja minimizar os dados obtidos do servidor.

• Agregando microsserviços : uma camada GraphQL pode ser introduzida para agregar os dados desses serviços em uma API unificada se você tiver vários microsserviços.

• Aplicativos em tempo real : com seu sistema de assinatura, o GraphQL pode ser uma excelente opção para aplicativos que precisam de dados em tempo real, como aplicativos de bate-papo, atualizações de esportes ao vivo, etc.

• APIs sem versão : com REST, muitas vezes você precisa versionar suas APIs assim que as alterações são introduzidas. Com o GraphQL, os clientes solicitam apenas os dados necessários, portanto, adicionar novos campos ou tipos não cria alterações significativas.

Exemplo

Solicitar

GET “/graphql?query=user(id:42){nome role { id name } }”

Resposta

 { "data": { "user": { "id": 42, "name": "Alex", "role": { "id": 1, "name": "admin" } } } }

WebSocket

WebSockets fornecem um canal de comunicação full-duplex em uma conexão única e de longa duração, permitindo a troca de dados em tempo real entre um cliente e um servidor. Isso o torna ideal para aplicações web interativas e de alto desempenho.

Formato : Binário

Protocolo de transporte : TCP

Principais conceitos e características

• Conexão persistente : Ao contrário do modelo tradicional de solicitação-resposta, os WebSockets fornecem um canal de comunicação full-duplex que permanece aberto, permitindo a troca de dados em tempo real.

• Upgrade Handshake : WebSockets iniciam como uma solicitação HTTP, que é então atualizada para uma conexão WebSocket se o servidor suportar. Isso é feito através do cabeçalho `Upgrade`.

• Quadros : Uma vez estabelecida a conexão, os dados são transmitidos como quadros. Tanto texto quanto dados binários podem ser enviados por meio desses quadros.

• Baixa Latência : WebSockets permitem a comunicação direta entre o cliente e o servidor sem a sobrecarga de abrir uma nova conexão para cada troca. Isso resulta em uma troca de dados mais rápida.

• Bidirecional : tanto o cliente quanto o servidor podem enviar mensagens entre si de forma independente.

• Menos sobrecarga : após a conexão inicial, os quadros de dados exigem menos bytes para serem enviados, resultando em menos sobrecarga e melhor desempenho do que o estabelecimento repetido de conexões HTTP.

• Protocolos e extensões : WebSockets suportam subprotocolos e extensões, permitindo protocolos padronizados e personalizados sobre o protocolo WebSocket base.

Casos de uso

• Jogos Online : Jogos multijogador em tempo real onde as ações dos jogadores devem ser imediatamente refletidas para outros jogadores.

• Ferramentas colaborativas : aplicativos como o Google Docs, onde vários usuários podem editar um documento simultaneamente e ver as alterações uns dos outros em tempo real.

• Aplicações Financeiras : Plataformas de negociação de ações onde os preços das ações precisam ser atualizados em tempo real.

• Notificações : qualquer aplicativo onde os usuários precisam receber notificações em tempo real, como plataformas de mídia social ou aplicativos de mensagens.

• Feeds ao vivo : sites de notícias ou plataformas de mídia social onde novas postagens ou atualizações são transmitidas ao vivo para os usuários.

Exemplo

Solicitar

OBTER “ws://site:8181”

Resposta

Protocolos de comutação HTTP/1.1 101

Webhook

Webhook é um retorno de chamada HTTP definido pelo usuário, acionado por eventos específicos de aplicativos da web, permitindo atualizações de dados em tempo real e integrações entre diferentes sistemas.

Formato : XML, JSON, texto simples

Protocolo de transporte : HTTP/HTTPS

Principais conceitos e características

• Orientado a eventos : Webhooks normalmente são usados para indicar que um evento ocorreu. Em vez de solicitar dados em intervalos regulares, os webhooks fornecem dados conforme eles acontecem, virando de cabeça para baixo o modelo tradicional de solicitação-resposta.

• Mecanismo de retorno de chamada : Webhooks são essencialmente um mecanismo de retorno de chamada definido pelo usuário. Quando ocorre um evento específico, o site de origem faz um retorno de chamada HTTP para o URI fornecido pelo site de destino, que então executará uma ação específica.

• Carga útil : quando o webhook é acionado, o site de origem enviará dados (carga útil) para o site de destino. Esses dados normalmente estão na forma de JSON ou XML.

• Tempo real : os webhooks permitem que os aplicativos obtenham dados em tempo real, tornando-os altamente responsivos.

• Personalizável : os usuários ou desenvolvedores normalmente podem definir sobre quais eventos específicos desejam ser notificados.

• Segurança : como os webhooks envolvem retornos de chamada para terminais HTTP definidos pelo usuário, eles podem representar desafios de segurança. É crucial garantir que o endpoint seja seguro, que os dados sejam validados e possivelmente criptografados.

Casos de uso

• Integração e implantação contínuas (CI/CD) : aciona compilações e implantações quando o código é enviado por push ou uma solicitação pull é mesclada.

• Sistemas de gerenciamento de conteúdo (CMS) : notificam os sistemas downstream quando o conteúdo é atualizado, publicado ou excluído.

• Gateways de pagamento : informam as plataformas de comércio eletrônico sobre os resultados das transações, como pagamentos bem-sucedidos, transações com falha ou reembolsos.

• Integrações de mídia social : recebimento de notificações sobre novas postagens, menções ou outros eventos relevantes em plataformas de mídia social.

• IoT (Internet das Coisas) : dispositivos ou sensores podem acionar webhooks para notificar outros sistemas ou serviços sobre eventos específicos ou leituras de dados.

Exemplo

Solicitar

OBTER “ https://external-site/webhooks?url=http://site/service-h/api&name=name ”

Resposta

 { "webhook_id": 12 }

RPC e gRPC

RPC (Remote Procedure Call) é um protocolo que permite a um programa executar um procedimento ou sub-rotina em outro espaço de endereço, permitindo comunicação e troca de dados contínuas entre sistemas distribuídos.

gRPC (Google RPC) é uma estrutura moderna e de código aberto construída sobre RPC que usa HTTP/2 para transporte e buffers de protocolo como linguagem de descrição de interface, fornecendo recursos como autenticação, balanceamento de carga e muito mais para facilitar uma comunicação eficiente e robusta entre microsserviços.

RPC

Formato : JSON, XML, Protobuf, Thrift, FlatBuffers

Protocolo de transporte : Vários

Principais conceitos e características

• Definição : RPC permite que um programa faça com que um procedimento (sub-rotina) seja executado em outro espaço de endereço (geralmente em outro computador em uma rede compartilhada). É como chamar uma função executada em uma máquina diferente da do chamador.

• Stubs : No contexto do RPC, stubs são pedaços de código gerados por ferramentas que permitem que chamadas de procedimentos locais e remotos tenham a mesma aparência. O cliente possui um stub que se parece com o procedimento remoto e o servidor possui um stub que descompacta os argumentos, chama o procedimento real e, em seguida, compacta os resultados para enviar de volta.

• Síncrono por padrão : as chamadas RPC tradicionais são bloqueadas, o que significa que o cliente envia uma solicitação ao servidor e fica bloqueado aguardando uma resposta do servidor.

• Linguagem neutra : muitos sistemas RPC permitem que diferentes implementações de cliente e servidor se comuniquem, independentemente da linguagem em que foram escritas.

• Acoplamento rígido : o RPC geralmente exige que o cliente e o servidor conheçam o procedimento que está sendo chamado, seus parâmetros e seu tipo de retorno.

Casos de uso

• Sistemas Distribuídos : RPC é comumente usado em sistemas distribuídos onde partes de um sistema estão espalhadas por diferentes máquinas ou redes, mas precisam se comunicar como se fossem locais.

• Sistemas de arquivos de rede : NFS (Network File System) é um exemplo de RPCs que executam operações de arquivos remotamente.

Exemplo

Solicitar

 { "method": "addUser", "params": [ "Alex" ] }

Resposta

 { "id": 42, "name": "Alex", "error": null }

gRPC

Formato : Protobuf

Protocolo de transporte : HTTP/2

Principais conceitos e características

• Definição : gRPC é uma estrutura RPC de código aberto desenvolvida pelo Google. Ele usa HTTP/2 para transporte, buffers de protocolo (Protobuf) como linguagem de descrição de interface e fornece autenticação, recursos de balanceamento de carga e muito mais.

• Buffers de protocolo : este é um mecanismo extensível, neutro em termos de linguagem e plataforma, para serializar dados estruturados. Com gRPC, você define métodos de serviço e tipos de mensagens usando Protobuf.

• Desempenho : o gRPC foi projetado para comunicação de baixa latência e alto rendimento. HTTP/2 permite multiplexar várias chamadas em uma única conexão e reduz a sobrecarga.

• Streaming : gRPC oferece suporte a solicitações e respostas de streaming, permitindo casos de uso mais complexos, como conexões de longa duração, atualizações em tempo real, etc.

• Prazos/tempos limite : o gRPC permite que os clientes especifiquem quanto tempo aguardarão a conclusão de um RPC. O servidor pode verificar isso e decidir se deseja concluir a operação ou abortá-la, caso ela demore muito.

• Plugável : o gRPC foi projetado para suportar autenticação conectável, balanceamento de carga, novas tentativas, etc.

• Neutro em termos de linguagem : assim como o RPC, o gRPC é independente do idioma. No entanto, com o Protobuf e as ferramentas gRPC, é fácil gerar código de cliente e servidor em vários idiomas.

Casos de uso

• Microsserviços : gRPC é comumente usado em arquiteturas de microsserviços devido às suas características de desempenho e capacidade de definir facilmente contratos de serviço.

• Aplicativos em tempo real : devido ao seu suporte para streaming, o gRPC é adequado para aplicativos em tempo real, onde os servidores enviam dados aos clientes em tempo real.

• Clientes móveis : os benefícios de desempenho e os recursos de streaming do gRPC o tornam uma boa opção para clientes móveis que se comunicam com serviços de back-end.

Exemplo

 message User { int id = 1 string name = 2 } service UserService { rpc AddUser(User) returns (User); }

SABÃO

SOAP , que significa Simple Object Access Protocol, é um protocolo de troca de informações estruturadas para implementação de serviços web em redes de computadores. É um protocolo baseado em XML que permite que programas executados em sistemas operacionais diferentes se comuniquem entre si.

Formato : XML

Protocolo de transporte : HTTP/HTTPS, JMS, SMTP e mais

Principais conceitos e características

• Baseado em XML : as mensagens SOAP são formatadas em XML e contêm os seguintes elementos:

  • Envelope : O elemento raiz de uma mensagem SOAP que define o documento XML como uma mensagem SOAP.

  
  

  • Cabeçalho : contém quaisquer atributos opcionais da mensagem usados no processamento da mensagem, seja em um ponto intermediário ou no ponto final.

  
  

  • Corpo : Contém os dados XML que compõem a mensagem que está sendo enviada.

  
  

  • Fault : um elemento opcional Fault que fornece informações sobre erros durante o processamento da mensagem.

    
    

• Neutralidade : SOAP pode ser usado com qualquer modelo de programação e não está vinculado a nenhum específico.

• Independência : Pode ser executado em qualquer sistema operacional e em qualquer idioma.

• Stateless : Cada solicitação de um cliente para um servidor deve conter todas as informações necessárias para compreender e processar a solicitação.

• Tratamento de erros integrado : o elemento Fault em uma mensagem SOAP é usado para relatórios de erros.

• Padronizado : Opera com base em padrões bem definidos, incluindo a própria especificação SOAP, bem como padrões relacionados como WS-ReliableMessaging para garantir a entrega de mensagens, WS-Security para segurança de mensagens e muito mais.

Casos de uso

• Aplicativos empresariais : SOAP é frequentemente usado em ambientes corporativos devido à sua robustez, extensibilidade e capacidade de atravessar firewalls e proxies.

• Serviços Web : Muitos serviços Web, especialmente os mais antigos, usam SOAP. Isso inclui serviços oferecidos por grandes empresas como Microsoft e IBM.

• Transações financeiras : A segurança e a extensibilidade integradas do SOAP fazem dele uma boa escolha para transações financeiras, onde a integridade e a segurança dos dados são fundamentais.

• Telecomunicações : As empresas de telecomunicações podem usar SOAP para processos como faturamento, onde diferentes sistemas devem se comunicar de forma confiável.

Exemplo

Solicitar

 <?xml version="1.0"?> <soap:Envelope> <soap:Body> <m:AddUserRequest> <m:Name>Alex</m:Name> </m:AddUserRequest> </soap:Body> </soap:Envelope>

Resposta

 <?xml version="1.0"?> <soap:Envelope> <soap:Body> <m:AddUserResponse> <m:Id>42</m:Id> <m:Name>Alex</m:Name> </m:AddUserResponse> </soap:Body> </soap:Envelope>

Conclusão

O panorama dos estilos de arquitetura de API é diversificado, oferecendo diversas abordagens como REST, SOAP, RPC e muito mais, cada uma com pontos fortes e casos de uso exclusivos, permitindo que os desenvolvedores escolham o paradigma mais adequado para construir integrações escalonáveis, eficientes e robustas entre diferentes softwares. componentes e sistemas.