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: (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. REST é 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. GraphQL é 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. WebSocket é 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. Webhook é 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. RPC (gRPC) é 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. SOAP Vejamos cada protocolo separadamente com todos os seus prós, contras e casos de uso. DESCANSAR é 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. REST 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. : XML, JSON, HTML, texto simples Formato : HTTP/HTTPS Protocolo de transporte Principais conceitos e características : 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). Recurso : os serviços REST geralmente mapeiam diretamente para operações CRUD (Criar, Ler, Atualizar, Excluir) em recursos. Operações CRUD : os sistemas REST usam métodos HTTP padrão: Métodos HTTP GET: Recupera um recurso. POST: Crie um novo recurso. PUT/PATCH: Atualize um recurso existente. DELETE: Remove um recurso. : APIs REST usam códigos de status HTTP padrão para indicar o sucesso ou a falha de uma solicitação de API: Códigos de status 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 : 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. Stateless : 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. Cliente-Servidor : 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. Armazenável em cache : 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. Sistema em camadas 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. HATEOAS: Casos de uso : Muitos serviços Web expõem sua funcionalidade por meio de APIs REST, permitindo que desenvolvedores terceirizados integrem e ampliem seus serviços. Serviços Web : os aplicativos móveis geralmente se comunicam com servidores back-end usando APIs REST para buscar e enviar dados. Aplicativos móveis : os SPAs usam APIs REST para carregar conteúdo dinamicamente sem exigir uma atualização completa da página. Aplicativos de página única (SPAs) os sistemas dentro de uma organização podem se comunicar e compartilhar dados usando APIs REST. Integração entre sistemas: Exemplo Solicitar OBTER “/usuário/42” Resposta { "id": 42, "name": "Alex", "links": { "role": "/user/42/role" } } GráficoQL 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. GraphQL 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. : JSON Formato : HTTP/HTTPS Protocolo de transporte Principais conceitos e características : permite que os clientes solicitem os dados que necessitam, possibilitando obter todas as informações necessárias em uma única solicitação. Linguagem de consulta para APIs : 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). Sistema de tipos : 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. Endpoint único : No lado do servidor, os resolvedores reúnem os dados descritos em uma consulta. Resolvedores : além de apenas consultar dados, o GraphQL inclui suporte integrado para atualizações em tempo real usando assinaturas. Atualizações em tempo real com assinaturas : 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. Introspectivo Casos de uso : para aplicativos (especialmente móveis) com largura de banda crucial, você deseja minimizar os dados obtidos do servidor. Frontends flexíveis : uma camada GraphQL pode ser introduzida para agregar os dados desses serviços em uma API unificada se você tiver vários microsserviços. Agregando microsserviços : 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. Aplicativos em tempo real : 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. APIs sem versão 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 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. WebSockets : Binário Formato : TCP Protocolo de transporte Principais conceitos e características : 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. Conexão persistente : 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`. Upgrade Handshake : 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. Quadros : 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. Baixa Latência : tanto o cliente quanto o servidor podem enviar mensagens entre si de forma independente. Bidirecional : 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. Menos sobrecarga : WebSockets suportam subprotocolos e extensões, permitindo protocolos padronizados e personalizados sobre o protocolo WebSocket base. Protocolos e extensões Casos de uso : Jogos multijogador em tempo real onde as ações dos jogadores devem ser imediatamente refletidas para outros jogadores. Jogos Online : 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. Ferramentas colaborativas : Plataformas de negociação de ações onde os preços das ações precisam ser atualizados em tempo real. Aplicações Financeiras : qualquer aplicativo onde os usuários precisam receber notificações em tempo real, como plataformas de mídia social ou aplicativos de mensagens. Notificações : 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. Feeds ao vivo Exemplo Solicitar OBTER “ws://site:8181” Resposta Protocolos de comutação HTTP/1.1 101 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. Webhook : XML, JSON, texto simples Formato : HTTP/HTTPS Protocolo de transporte Principais conceitos e características : 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. Orientado a eventos : 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. Mecanismo de retorno de chamada : 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. Carga útil : os webhooks permitem que os aplicativos obtenham dados em tempo real, tornando-os altamente responsivos. Tempo real : os usuários ou desenvolvedores normalmente podem definir sobre quais eventos específicos desejam ser notificados. Personalizável : 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. Segurança Casos de uso : aciona compilações e implantações quando o código é enviado por push ou uma solicitação pull é mesclada. Integração e implantação contínuas (CI/CD) : notificam os sistemas downstream quando o conteúdo é atualizado, publicado ou excluído. Sistemas de gerenciamento de conteúdo (CMS) : informam as plataformas de comércio eletrônico sobre os resultados das transações, como pagamentos bem-sucedidos, transações com falha ou reembolsos. Gateways de pagamento : recebimento de notificações sobre novas postagens, menções ou outros eventos relevantes em plataformas de mídia social. Integrações de mídia social : dispositivos ou sensores podem acionar webhooks para notificar outros sistemas ou serviços sobre eventos específicos ou leituras de dados. IoT (Internet das Coisas) Exemplo Solicitar OBTER “ ” https://external-site/webhooks?url=http://site/service-h/api&name=name Resposta { "webhook_id": 12 } RPC e gRPC (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. RPC (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. gRPC RPC : JSON, XML, Protobuf, Thrift, FlatBuffers Formato : Vários Protocolo de transporte Principais conceitos e características : 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. Definição : 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. Stubs : 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. Síncrono por padrão : muitos sistemas RPC permitem que diferentes implementações de cliente e servidor se comuniquem, independentemente da linguagem em que foram escritas. Linguagem neutra : 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. Acoplamento rígido Casos de uso : 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 Distribuídos : NFS (Network File System) é um exemplo de RPCs que executam operações de arquivos remotamente. Sistemas de arquivos de rede Exemplo Solicitar { "method": "addUser", "params": [ "Alex" ] } Resposta { "id": 42, "name": "Alex", "error": null } gRPC : Protobuf Formato : HTTP/2 Protocolo de transporte Principais conceitos e características : 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. Definição : 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. Buffers de protocolo : 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. Desempenho : 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. Streaming : 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. Prazos/tempos limite : o gRPC foi projetado para suportar autenticação conectável, balanceamento de carga, novas tentativas, etc. Plugável : 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. Neutro em termos de linguagem Casos de uso : gRPC é comumente usado em arquiteturas de microsserviços devido às suas características de desempenho e capacidade de definir facilmente contratos de serviço. Microsserviços : devido ao seu suporte para streaming, o gRPC é adequado para aplicativos em tempo real, onde os servidores enviam dados aos clientes em tempo real. Aplicativos em tempo real : 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. Clientes móveis Exemplo message User { int id = 1 string name = 2 } service UserService { rpc AddUser(User) returns (User); } SABÃO , 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. SOAP : XML Formato : HTTP/HTTPS, JMS, SMTP e mais Protocolo de transporte Principais conceitos e características : as mensagens SOAP são formatadas em XML e contêm os seguintes elementos: Baseado em XML : O elemento raiz de uma mensagem SOAP que define o documento XML como uma mensagem SOAP. Envelope : contém quaisquer atributos opcionais da mensagem usados no processamento da mensagem, seja em um ponto intermediário ou no ponto final. Cabeçalho : Contém os dados XML que compõem a mensagem que está sendo enviada. Corpo : um elemento opcional Fault que fornece informações sobre erros durante o processamento da mensagem. Fault : SOAP pode ser usado com qualquer modelo de programação e não está vinculado a nenhum específico. Neutralidade : Pode ser executado em qualquer sistema operacional e em qualquer idioma. Independência : Cada solicitação de um cliente para um servidor deve conter todas as informações necessárias para compreender e processar a solicitação. Stateless : o elemento Fault em uma mensagem SOAP é usado para relatórios de erros. Tratamento de erros integrado : 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. Padronizado Casos de uso : SOAP é frequentemente usado em ambientes corporativos devido à sua robustez, extensibilidade e capacidade de atravessar firewalls e proxies. Aplicativos empresariais : Muitos serviços Web, especialmente os mais antigos, usam SOAP. Isso inclui serviços oferecidos por grandes empresas como Microsoft e IBM. Serviços Web : 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. Transações financeiras : As empresas de telecomunicações podem usar SOAP para processos como faturamento, onde diferentes sistemas devem se comunicar de forma confiável. Telecomunicações Exemplo Solicitar Alex Resposta 42 Alex 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.