O que é GraphQL?
GraphQL é uma forma alternativa de se comunicar com APIs que é altamente adequada para estruturas de dados complexas e para a construção de interfaces sobre elas. Ao contrário de tratar os dados como peças separadas e independentes, o GraphQL mostra como as peças de dados se conectam e se relacionam, facilitando a solicitação e o recebimento de informações.
Pense no GraphQL como uma linguagem de consulta que permite que você converse com a API como se estivesse falando diretamente com o banco de dados. Usar GraphQL permite que você chegue o mais perto possível do banco de dados, permitindo que você escolha quais dados deseja e como os obtém, proporcionando um enorme benefício de desempenho.
O GraphQL foi criado pelo Facebook para resolver o problema de escalabilidade com estruturas de dados complexas. Como resultado de sua adoção bem-sucedida, cada vez mais empresas começaram a perceber os benefícios de usar o GraphQL para suas APIs.
Principais diferenças em relação ao REST
As APIs GraphQL são mais fáceis de trabalhar do que você pode pensar. Se você está acostumado a trabalhar com APIs REST, aqui estão as diferenças fundamentais a serem lembradas:
| Recurso | REST | GraphQL |
|---|---|---|
| Endpoint | As solicitações são feitas para vários endpoints para diferentes ações | Todas as solicitações são feitas para um único endpoint (por exemplo, /graphql) |
| Recuperação de dados | Use métodos GET em endpoints específicos para recuperar dados | Use consultas para solicitar exatamente os dados necessários, reduzindo a sobrecarga ou a subcarga |
| Modificação de dados/ações | Use métodos HTTP como POST, PUT, PATCH ou DELETE para modificar ou processar dados. | Use mutations para realizar operações (por exemplo, criar partes, calcular custos de importação) |
| Formato de resposta | Formatos de resposta fixos retornam todos os campos predefinidos, independentemente de serem necessários | Respostas flexíveis permitem especificar exatamente os campos a serem incluídos, reduzindo a transferência de dados desnecessários |
| Conexão de dados | Múltiplas solicitações são frequentemente necessárias para buscar dados relacionados | Consultas aninhadas permitem recuperar dados relacionados em uma única solicitação (por exemplo, detalhes da parte e itens de envio juntos). Os usuários também podem construir fluxos de trabalho para gerenciar múltiplas mutações dentro de uma única solicitação GraphQL, reduzindo a complexidade e melhorando a eficiência |
Vantagens do GraphQL
Respostas mais rápidas
O GraphQL fornece respostas mais rápidas por meio da recuperação precisa de dados, uso de um único endpoint e capacidades aprimoradas de agrupamento e cache.
Recuperação precisa de dados
Um desafio comum com o REST é a sobrecarga ou subcarga de dados—ou seja, obter muita informação desnecessária ou não o suficiente do que é necessário de uma só vez. O GraphQL elimina isso permitindo solicitações exatamente do que é necessário—nada mais, nada menos. Essa especificidade não apenas melhora o desempenho, mas também simplifica o processo para aqueles que interagem com a API, tornando o sistema mais eficiente e amigável.
Exemplos de como isso é útil:
- Isso permite que os desenvolvedores frontend busquem exatamente os dados de que precisam para seus componentes de UI, reduzindo o número de idas e vindas ao servidor e melhorando o desempenho.
- Imagine que você deseja obter uma classificação de código HS, cartonagem, avaliação de envio e uma cotação de landed cost sobre itens em um checkout. Se você estiver integrado via API GraphQL, pode fazer uma única chamada com os fluxos de trabalho necessários para obter tudo o que precisa (e nada do que não precisa) em uma única resposta. Em contraste, com APIs REST, você precisaria primeiro chamar a API REST Classify, depois chamar a API REST de Avaliação separadamente e, finalmente, inserir essa classificação e avaliação de envio em sua terceira chamada para a API REST Landed Cost. Todas essas APIs REST retornariam cada pedaço de informação que podem, fazendo com que você tenha que analisar a resposta para os dados de que precisa. Essa economia de velocidade impacta na devolução rápida de um landed cost, antes que o comprador saia.
Único endpoint
As APIs GraphQL normalmente têm um único endpoint, ao contrário das APIs REST que frequentemente têm múltiplos endpoints para diferentes recursos e ações. Isso torna mais simples gerenciar e entender a API.
Agrupamento e cache
A capacidade do GraphQL de agrupar consultas e seu suporte a estratégias de cache levam a melhorias significativas de desempenho. Esses recursos reduzem a carga em redes e servidores, traduzindo-se em interações mais rápidas e confiáveis para os usuários.
Esquemas bem definidos
As APIs GraphQL são baseadas em um esquema fortemente tipado. Esse esquema define a estrutura dos dados disponíveis e as operações que podem ser realizadas. Isso proporciona clareza sobre quais dados estão disponíveis e como acessá-los, o que pode melhorar a produtividade do desenvolvedor e reduzir erros. Por exemplo, as equipes frontend podem explorar o gráfico para obter exatamente o que precisam em vez de esperar por um novo endpoint REST.
Capacidade de melhorar sem quebrar clientes existentes
Adicionar novos recursos ou modificar os existentes no GraphQL não interrompe as integrações atuais, graças à sua estrutura de consulta flexível. Essa capacidade garante que melhorias possam ser feitas sem quebrar a compatibilidade com clientes existentes.
Documentação atualizada
Graças ao recurso de introspecção do GraphQL, a documentação é gerada e atualizada automaticamente com cada alteração. Isso garante que todas as informações fornecidas aos desenvolvedores estejam atualizadas, reduzindo problemas de integração e tickets de suporte relacionados à documentação desatualizada—um desafio comumente enfrentado com a documentação de APIs REST.
Revise nossa documentação do GraphQL e nossa documentação do REST para ver a diferença.
Uma analogia
Imagine que você está em um restaurante com um menu que permite que você peça pratos exatamente como você gosta, em comparação com outro restaurante onde você só pode escolher entre refeições definidas. GraphQL é como o primeiro restaurante:
- Obtenha exatamente o que você quer: Com GraphQL, você pode pedir exatamente os dados de que precisa, nem mais, nem menos. Imagine que você só quer o nome e o preço de um prato, não a lista completa de ingredientes. Com APIs REST, você tem que obter todos os detalhes do prato e ignorar as partes que não precisa.
- Monte um prato personalizado: Nossas APIs GraphQL podem ser facilmente combinadas para criar soluções mais personalizadas, semelhante a um restaurante estilo buffet onde você pode criar um prato único exatamente como precisa, usando ingredientes que eles já têm. Em contraste, uma API REST é como uma padaria com produtos pré-fabricados embalados em cestas—você só pode pedir o que já foi criado e não pode escolher levar para casa apenas a parte que deseja.
- Menos espera: Como você pode obter todas as informações de que precisa em uma única solicitação, é como pedir ao seu garçom para trazer seu aperitivo, prato principal e sobremesa tudo de uma vez, em vez de esperar entre os pratos. A maioria das APIs REST exige que você envie várias solicitações para obter diferentes partes de informação.
- Fácil de mudar pedidos: Se as necessidades de dados do seu aplicativo mudarem, o GraphQL facilita o ajuste. Você apenas altera a consulta para o que precisa. Com REST, você pode precisar esperar que a cozinha (backend) crie uma nova refeição (endpoint) para o menu, o que leva mais tempo.
GraphQL oferece mais flexibilidade, eficiência e simplicidade para buscar dados do que as APIs REST, especialmente à medida que suas necessidades mudam ou crescem.
Como Zonos usa GraphQL
Enquanto modernizávamos nossa plataforma nos últimos anos, Zonos decidiu construir novas funcionalidades usando GraphQL para nossa API em vez de REST. Decidimos fazer isso porque nossos dados são complexos e interconectados, muito parecido com os dados que levaram o Facebook a criar o GraphQL. Essa complexidade torna desafiador construir APIs REST escaláveis, pois as maneiras que os desenvolvedores precisam buscar e usar os dados variam dramaticamente entre implementações, e o REST não é flexível.
O GraphQL resolve esse problema de forma elegante, permitindo que os desenvolvedores que implementam nossa API escolham exatamente quais dados desejam e como obtê-los. Isso permite que eles se encaixem em seus fluxos de trabalho sem que Zonos precise fazer trabalho personalizado (enquanto eles esperam) para cada situação.
O resultado combinado do uso do GraphQL e das modernizações em nossa plataforma tornou nossa API mais performática, tornou a integração do Zonos em seus sistemas mais rápida e possibilitou que Zonos entregasse novas funcionalidades mais rapidamente.
Melhores funcionalidades
Zonos desenvolve continuamente novas funcionalidades, e o GraphQL é o primeiro (e geralmente o único) a receber essas atualizações. Em contraste, nossas APIs REST são consideradas obsoletas e não podem acessar muitas de nossas novas funcionalidades.
Exemplos de funcionalidades limitadas ao GraphQL:
- Inclusive pricing
- API de rótulos
- Novo Checkout e Hello
- Tamanhos de caixas na resposta da API
- Relatórios do painel
- Capacidade de solicitar uma cotação DDP, se possível, mas ainda retornar uma cotação DDU se DDP não estiver disponível para aquele país com aquele nível de serviço
- Detalhamento detalhado de impostos, taxas e encargos (informações por item, taxas específicas)—o painel é alimentado pelo GraphQL e mostra esses dados para todas as lojas, mas a resposta da API REST não inclui esse nível de detalhe
- Modo de teste (em breve)
Por que GraphQL
Descubra por que recomendamos a integração via GraphQL em vez de REST.
Na Zonos, oferecemos dois tipos principais de APIs para integração: GraphQL e REST. Embora as APIs REST existam há mais tempo e possam ser mais familiares para muitos, nós migramos para o GraphQL para permitir mais flexibilidade e inovação mais rápida. Embora ambos ainda sejam suportados, este guia explica por que o GraphQL não é apenas o futuro de nossas integrações, mas também o futuro das integrações em geral e uma ferramenta mais poderosa para atender às suas necessidades hoje.