O que é GraphQL?
GraphQL é uma forma alternativa de comunicação com o API, muito adequada para estruturas de dados complexas e para construir interfaces sobre elas. Ao contrário de tratar os dados como partes separadas e independentes, o GraphQL mostra como eles 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 conversar com o API como se estivesse conversando diretamente com o banco de dados. Usar o GraphQL permite chegar o mais próximo possível do banco de dados, escolhendo quais dados deseja e como obtê-los, o que é uma enorme vantagem de desempenho.
O GraphQL foi criado no Facebook para resolver o problema de escalonamento com estruturas de dados complexas. Após a sua adoção bem-sucedida, mais e mais empresas começaram a reconhecer os benefícios de usar o GraphQL para o seu API.
Você já conhece REST? GraphQL lhe parecerá familiar.
Os API GraphQL são mais fáceis de usar do que você imagina. Se você está acostumado a trabalhar com API REST, é assim que os principais conceitos de REST são traduzidos para GraphQL.
| Recurso↕ | REST↕ | GraphQL↕ |
|---|---|---|
| Ponto final | As solicitações são feitas a 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 recuperação excessiva ou insuficiente |
| Modificação de dados/ações | Use métodos HTTP como POST, PUT, PATCH ou DELETE para modificar ou processar dados | Use mutações para realizar operações (por exemplo, criar partes, calcular custos no destino) |
| Formato de resposta | Os formatos de resposta fixos retornam todos os campos predefinidos, mesmo que não sejam necessários | Respostas flexíveis permitem especificar exatamente quais campos incluir, reduzindo a transferência desnecessária de dados (se essa flexibilidade parecer complicada, basta usar os exemplos de consulta em nossa documentação para uma experiência semelhante a REST) |
| Conexão de dados | Muitas vezes são necessárias múltiplas solicitações para obter dados relacionados | Consultas aninhadas permitem recuperar dados relacionados em uma única solicitação (por exemplo, detalhes da parte e itens de remessa juntos). Os usuários também podem criar fluxos de trabalho para gerenciar múltiplas mutações em uma única solicitação GraphQL, reduzindo a complexidade e melhorando a eficiência. |
Vantagens do GraphQL
Respostas mais rápidas
GraphQL oferece respostas mais rápidas graças à recuperação precisa de dados, uso de um único endpoint e recursos aprimorados de agrupamento de solicitações e cache.
Recuperação precisa de dados
Um desafio comum com REST é a busca excessiva ou insuficiente de dados: obter muitas ou poucas informações desnecessárias de uma só vez. GraphQL elimina isso, permitindo que você peça exatamente o que precisa, nem mais, nem menos. Esta especificidade não só melhora o desempenho, como também simplifica o processo para quem interage com a API, tornando o sistema mais eficiente e fácil de utilizar.
Exemplos de utilidade:
- Isso permite que os desenvolvedores front-end obtenham exatamente os dados necessários para seus componentes front-end, reduzindo o número de viagens de ida e volta ao servidor e melhorando o desempenho.
- Imagine que você deseja obter uma classificação por código HS, cartonização, avaliação de frete e cotação de custo no destino dos itens no checkout. Se você estiver integrado usando o API GraphQL, você pode fazer uma única chamada com os fluxos de trabalho necessários para obter tudo o que você precisa (e nada que você não precise) em uma única resposta. Em vez disso, com API REST, você primeiro teria que chamar o Classify REST API, depois chamar o Rating REST API separadamente e, por fim, inserir essa classificação e avaliação de frete em sua terceira chamada para o Landed Cost REST API. Todos esses REST API retornariam todas as informações que possuem, forçando você a analisar a resposta para encontrar os dados necessários. Essa economia de velocidade tem impacto no retorno rápido do custo total no destino, antes que o comprador saia.
Um único ponto final
API GraphQL normalmente possui um único endpoint, ao contrário do API REST, que geralmente possui vários endpoints para diferentes recursos e ações. Isto simplifica o gerenciamento e a compreensão do 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 nas redes e servidores, resultando em interações mais rápidas e confiáveis para os usuários.
Esquemas bem definidos
Os API GraphQL são baseados em um esquema fortemente tipado. Este esquema define a estrutura dos dados disponíveis e as operações que podem ser executadas. 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 de front-end 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 os 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. Esse recurso garante que melhorias possam ser feitas sem quebrar a compatibilidade com os clientes existentes.
Documentação atualizada
Graças ao recurso de introspecção do GraphQL, a documentação é gerada e atualizada automaticamente a 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 a documentação desatualizada, um desafio comum com a documentação REST do API.
Confira nossa Documentação GraphQL e nossa Documentação REST para ver a diferença.
Uma analogia
Imagine que você está em um restaurante com um cardápio que permite pedir pratos exatamente como você deseja, em vez de outro restaurante onde você só pode escolher entre menus fixos. GraphQL é como o primeiro restaurante:
- Obtenha exatamente o que deseja: Com o GraphQL, você pode solicitar exatamente os dados que precisa, nem mais, nem menos. Imagine que você queira apenas o nome e o preço de um prato, e não a lista completa de ingredientes. Com o API REST, você precisa obter todos os detalhes do prato e ignorar as partes desnecessárias.
- Componha um prato personalizado: Nosso API GraphQL pode ser facilmente combinado para criar soluções mais personalizadas, semelhantes a um restaurante buffet onde você pode criar um prato único exatamente como você precisa, com ingredientes que eles já possuem. Em contrapartida, uma API REST é como uma padaria com produtos pré-fabricados embalados em cestos: só pode encomendar o que já foi criado e não pode optar por levar apenas a peça que deseja.
- Menos espera: Como você pode obter todas as informações necessárias em uma única solicitação, é como pedir ao garçom que traga seu aperitivo, prato principal e sobremesa de uma só vez, em vez de esperar entre os pratos. A maioria das aplicações REST API requerem o envio de múltiplas solicitações para obter diferentes informações.
- Pedidos fáceis de alterar: Se os dados da sua aplicação precisarem de alteração, o GraphQL facilita o ajuste. Basta alterar a consulta do que você precisa. Com REST, pode ser necessário esperar que a cozinha (backend) crie um novo alimento (endpoint) para o menu, o que leva mais tempo.
O GraphQL oferece mais flexibilidade, eficiência e simplicidade na obtenção de dados do que o API REST, especialmente conforme suas necessidades mudam ou crescem.
Como a Zonos usa o GraphQL
Ao modernizar nossa plataforma nos últimos anos, Zonos optou por construir novas funcionalidades usando GraphQL para nosso API em vez de REST. Fizemos isso porque nossos dados são complexos e interconectados, assim como os dados que levaram o Facebook a criar o GraphQL. Essa complexidade torna difícil construir REST API escalável porque as maneiras pelas quais os desenvolvedores precisam para obter e usar os dados variam muito entre as implementações, e o REST não é flexível.
GraphQL resolve esse problema permitindo que os desenvolvedores que implementam nosso API escolham exatamente quais dados desejam e como obtê-los. Isto permite-lhes integrá-lo nos seus fluxos de trabalho sem que o Zonos tenha que fazer um trabalho personalizado (enquanto esperam) para cada situação.
O resultado combinado do uso do GraphQL e de nossas modernizações de plataforma tornou nosso API mais eficiente, acelerou a integração do Zonos em seus sistemas e permitiu que o Zonos entregasse novos recursos mais rapidamente.
Melhores recursos
Zonos desenvolve continuamente novos recursos e GraphQL é o primeiro (e geralmente o único) a receber essas atualizações. Em contraste, nosso API REST é considerado em fim de vida e não pode acessar muitos de nossos novos recursos.
Exemplos de funções limitadas à GraphQL:
- Inclusive Pricing
- Etiquetas API
- Novos Checkout e Hello
- Tamanhos de caixa na resposta API
- Relatórios Dashboard
- Capacidade de solicitar uma cotação DDP, se possível, mas ainda assim retornar uma cotação DDU se DDP não estiver disponível para aquele país com esse nível de serviço
- Detalhamento detalhado de direitos aduaneiros, impostos e taxas (informações em nível de item, taxas específicas): Dashboard trabalha com GraphQL e exibe esses dados para todas as lojas, mas a resposta REST API não inclui este nível de detalhe
- Modo de teste (em breve)
Por que GraphQL
Descubra por que recomendamos a integração usando GraphQL em vez de REST.
Na Zonos oferecemos dois tipos principais de API para integração: GraphQL e REST. Embora o API REST esteja no mercado há mais tempo e possa ser mais familiar para muitos, adotamos o GraphQL para permitir maior flexibilidade e inovação mais rápida. Embora ambos permaneçam compatíveis, este guia explica porque o GraphQL não é apenas o futuro das nossas integrações, mas também o futuro das integrações em geral e uma ferramenta mais poderosa para atender às suas necessidades atuais.