Na área de desenvolvimento de software, a comunicação entre aplicações front-end e serviços back-end é um tema essencial. Tradicionalmente, as APIs REST (Representational State Transfer) têm sido o padrão de mercado para essa interação. No entanto, uma alternativa poderosa tem ganhado cada vez mais destaque: o GraphQL.
Criado pelo Facebook em 2012 e liberado como código aberto em 2015, o GraphQL é uma linguagem de consulta que propõe uma abordagem diferente das APIs REST tradicionais, permitindo que o cliente especifique exatamente quais dados precisa obter, recebendo uma resposta estruturada e de acordo com essa especificação.
Neste artigo vamos conhecer o que é o GraphQL, como surgiu, quais suas principais características, entre outros temas. Vamos começar?
1. O que é GraphQL?
GraphQL é uma linguagem de consulta (query language) para APIs e um conjunto de ferramentas de tempo de execução (runtime) para executar essas consultas com base nos seus dados.
Ao invés de ter múltiplos endpoints REST, onde cada um retorna um conjunto fixo de dados, com o GraphQL você tem um único endpoint que permite ao cliente solicitar exatamente os dados que precisa. Isso simplifica a interação entre cliente e servidor, bem como evita a sobrecarga de rede.
Pense na seguinte analogia: em uma API REST, é como se você fosse a um restaurante e tivesse que pedir um prato “combo” que vem com hambúrguer, batata frita e refrigerante, mesmo que só queira o hambúrguer. Já com o GraphQL, você pode pedir apenas o hambúrguer, e o garçom (o servidor) vai te trazer somente isso. Isso evita o chamado “over-fetching” (buscar mais dados do que o necessário) e o “under-fetching” (buscar dados insuficientes, exigindo múltiplas requisições).
O GraphQL é composto, basicamente, por três partes principais:
- Linguagem de Consulta: define como o cliente busca pelos dados.
- Esquema (Schema): especifica quais tipos de dados estão disponíveis na API e como eles se relacionam.
- Resolução (Resolvers): funções que atendem às consultas, buscando os dados no back-end.
1.1. Como o GraphQL surgiu?
O GraphQL foi desenvolvido pelo Facebook em 2012 e lançado publicamente em 2015. A necessidade surgiu da complexidade crescente de seus aplicativos (web, mobile, dispositivos IoT etc.), os quais precisavam de uma maneira mais eficiente de buscar dados em seus servidores. As APIs REST do Facebook estavam gerando problemas de desempenho e lentidão no desenvolvimento de novos recursos, pois as equipes de front-end e back-end precisavam coordenar cada mudança em vários endpoints.
A solução encontrada foi a criação de uma nova abordagem onde o front-end tivesse mais controle sobre a estrutura dos dados retornados. Isso permitiu que o Facebook criasse uma API unificada que alimentasse tanto seu aplicativo móvel quanto a versão web, reduzindo a necessidade de endpoints específicos para cada plataforma e otimizando a velocidade de desenvolvimento.
2 – Principais características do GraphQL
Para entender como o GraphQL funciona, é crucial conhecer alguns termos-chave:
- Schema: o schema define as operações disponíveis (queries, mutations e subscriptions) e os tipos de dados que podem ser consultados (object types, scalar types, enums, interfaces, etc.). Essencialmente, o schema é um contrato entre o front-end e o back-end, especificando os tipos de dados, os campos disponíveis e as relações entre eles. Os schemas são escritos em uma Linguagem de Definição de Schema (SDL).
- Queries: são operações de leitura de dados que o cliente executa. Nelas, o desenvolvedor define quais campos o cliente pode consultar, aninhando objetos conforme a necessidade daquela operação.
- Mutations: são operações de escrita ou modificação de dados (criação, atualização e exclusão). São semelhantes às queries, porém voltadas para alteração de estado no servidor. Uma observação é que, ao contrário das queries, que podem ser executadas em paralelo, as mutations são executadas em série para garantir a integridade dos dados.
- Resolvers: são funções do lado do servidor que resolvem uma query ou mutation e retornam os dados para cada campo do schema. Podem acessar bancos de dados, serviços externos ou qualquer outra fonte de informação. Importante ressaltar que cada campo no schema possui um resolver correspondente.
- Subscriptions: mecanismo para notificações em tempo real, mantendo uma conexão WebSocket ou similar para enviar atualizações ao cliente.
- Tipos Comuns: o GraphQL é fortemente tipado. Isso significa que todos os campos e tipos de dados no schema têm um tipo definido (como String, Int, Boolean, etc.). Essa tipagem forte garante que a aplicação seja mais robusta e que os erros sejam identificados mais cedo, durante o desenvolvimento.
- Scalars: Int, Float, String, Boolean, ID.
- Object Types: definem objetos com campos específicos.
- Lists e Non-Null: definem coleções e campos obrigatórios, respectivamente.
- Enums, Interfaces e Unions: permitem modelar estruturas mais complexas e polimorfas.
3 – As vantagens e desvantagens do GraphQL
Como toda tecnologia, o GraphQL também tem seus prós e contras, os quais precisam ser avaliados antes da sua adoção.
3.1 – Vantagens:
- Eficiência e Desempenho: permite buscar exatamente o que é necessário, reduzindo a quantidade de dados transferidos e o número de requisições de rede. Dessa forma, o cliente recebe apenas os dados necessários, evitando overfetching e underfetching.
- Desenvolvimento Ágil e Flexível: o front-end se torna mais independente do back-end. A equipe de front-end pode solicitar novos dados sem a necessidade da equipe do back-end criar ou modificar um novo endpoint. Isso acelera o processo de desenvolvimento.
- Documentação e Tipagem Automática: o schema atua como uma documentação viva da API. Ferramentas como o GraphiQL (um ambiente de desenvolvimento para GraphQL) usam o schema para fornecer autocompletar e validação de consultas, facilitando a vida do desenvolvedor.
- Uma única requisição: em muitas situações, o GraphQL permite que o cliente obtenha todos os dados que precisa em uma única requisição, evitando o problema de “cascata de requisições” comum em APIs REST.
3.2 – Desvantagens:
- Complexidade e Curva de Aprendizagem: a curva de aprendizado inicial é maior, especialmente para desenvolvedores acostumados apenas com REST.
- Cache: o cache é mais desafiador de implementar no GraphQL do que em APIs REST. A ausência de endpoints distintos dificulta o cache HTTP tradicional. No entanto, existem soluções e bibliotecas para lidar com isso.
- Upload de Arquivos: o upload de arquivos binários pode ser mais complexo de lidar em GraphQL.
- Monitoramento e Limitação de Taxa (Rate Limiting): a implementação de rate limiting e monitoramento em um único endpoint pode ser mais desafiadora do que em múltiplos endpoints REST. Assim, se faz necessário, criar lógicas de negócio mais sofisticadas para controlar o acesso.
4 – Exemplo prático
A seguir, para fins de um melhor entendimento, vamos ver um exemplo simples de implementação de GraphQL usando Node.js e Apollo Server.
4.1 – Configurando o ambiente
Para começar vamos criar uma pasta chamada graphql-books-api e executar os comandos abaixo via terminal em seu respectivo diretório:
npm init -y
npm pkg set type="module"
npm install apollo-server graphql
npm install --save-dev nodemonApós executar esses comandos, será criada uma pasta chamada node_modules e dois arquivos: package.json e package-lock.json.
Em seu arquivo package.json, você precisará inserir as informações do script de desenvolvimento, no respectivo trecho de “scripts”:
{
"name": "graphql-books-api",
"version": "1.0.0",
"description": "",
"main": "index.js",
"scripts": {
"start": "node index.js",
"dev": "nodemon index.js"
},
"keywords": [],
"author": "",
"license": "ISC",
"type": "module",
"dependencies": {
"apollo-server": "^3.13.0",
"graphql": "^16.11.0"
},
"devDependencies": {
"nodemon": "^3.1.10"
}
}Pronto! Nosso ambiente Node.js já possui uma configuração básica para iniciar o desenvolvimento. Agora, vamos acrescentar duas pastas nessa estrutura (schema e resolvers) e três arquivos (schema.js, resolvers.js e index.js), chegando a esse resultado:
4.2 – Criando nosso serviço GraphQL
Com o ambiente criado e configurado, vamos inserir os códigos JavaScript de cada um desse nossos arquivos e na sequência vamos executar o servidor e testar a API:
import { ApolloServer } from 'apollo-server';
import typeDefs from './schema/schema.js';
import resolvers from './resolvers/resolvers.js';
const server = new ApolloServer({ typeDefs, resolvers });
server.listen({ port: 4000 }).then(({ url }) => {
console.log(`🚀 Server ready at ${url}`);
});
import { gql } from 'apollo-server';
const typeDefs = gql`
type Book {
id: ID!
title: String!
author: String!
}
type Query {
books: [Book!]!
book(id: ID!): Book
}
type Mutation {
addBook(title: String!, author: String!): Book!
}
`;
export default typeDefs;
const books = new Map();
// Dados iniciais (mock realizado para fins de teste)
books.set("1", { id: "1", title: "Clean Code", author: "Robert C. Martin" });
books.set("2", { id: "2", title: "1984", author: "George Orwell" });
const resolvers = {
Query: {
books: () => Array.from(books.values()),
book: (_, { id }) => books.get(id),
},
Mutation: {
addBook: (_, { title, author }) => {
const id = String(books.size + 1);
const newBook = { id, title, author };
books.set(id, newBook);
return newBook;
},
},
};
export default resolvers;
Após inserir os códigos, no terminal execute o comando abaixo para iniciar o servidor Node.js:
npm run devSe tudo estiver certo, você visualizará essa mensagem:
🚀 Server ready at http://localhost:4000/Com o servidor iniciado, vamos testar nossa API. Abra o navegador e acesse http://localhost:4000. Na tela que vai carregar clique em “Query your server” e execute essa query de exemplo:
query {
books {
id
title
author
}
}O resultado dessa query será um arquivo em formato Json com os livros que fizemos mock em nossa API de GraphQL.
Vamos testar também um mutation para adicionarmos um livro:
mutation {
addBook(title: "O Hobbit", author: "J.R.R. Tolkien") {
id
title
author
}
}Você terá um retorno mostrando o registro inserido no seu mock. Se executar a query de consulta novamente, o novo livro registrado aparecerá no seu retorno.
A partir desse exemplo prático veja como é simples dar os seus primeiros passos com GraphQL usando Node.js e Apollo Server. A partir desse ponto, você pode explorar recursos mais avançados, integrar com bancos de dados reais e desenvolver APIs robustas para diferentes tipos de aplicações. E não se esqueça, o GraphQL não é compatível apenas com Node.js, você pode utilizá-lo com outras linguagens de sua preferência como PHP, Python e Java, entre outras.
Conclusão
O GraphQL surge como uma alternativa moderna e eficiente às APIs REST, oferecendo maior flexibilidade e controle sobre as requisições de dados feitas pelo cliente. Ao permitir que o front-end especifique exatamente o que precisa, ele elimina a necessidade de múltiplos endpoints, reduz o tráfego de dados e acelera o desenvolvimento de aplicações mais dinâmicas e escaláveis.
Apesar de exigir uma curva de aprendizado inicial maior e apresentar alguns desafios técnicos — como cache e upload de arquivos —, o GraphQL tem se mostrado uma poderosa ferramenta para quem busca criar APIs mais intuitivas, documentadas e alinhadas com as necessidades reais do cliente.
Seja você um desenvolvedor front-end buscando maior autonomia ou um desenvolvedor back-end em busca de soluções mais eficientes, vale a pena considerar o GraphQL como parte do seu stack de desenvolvimento.
Espero que este conteúdo seja útil em sua trajetória! Se você gostou do conteúdo, compartilhe com seus amigos e aproveite para conhecer mais sobre APIs e outros assuntos de tecnologia da informação aqui!
