API GraphQL com JavaScript: tutorial prático passo a passo

Introdução ao GraphQL e suas vantagens

GraphQL é uma linguagem de consulta e ambiente de execução para APIs, desenvolvido pelo Facebook. Diferente do REST, onde você obtém estruturas de dados fixas, o GraphQL permite que o cliente solicite apenas o que precisa. Isso torna as APIs mais flexíveis e eficientes.

Neste tutorial passo a passo, criaremos uma API GraphQL completa em JavaScript usando Node.js. Você aprenderá a configurar o servidor, definir schemas, processar consultas e mutações. Ao final do artigo, você terá uma API funcional, pronta para integração em qualquer projeto.

1. Configuração do projeto e instalação de dependências

Para começar, vamos criar um novo projeto Node.js e instalar os pacotes necessários. Usaremos apollo-server — uma biblioteca popular para criar servidores GraphQL.

Passo 1: Inicialização do projeto

mkdir graphql-tutorial\ncd graphql-tutorial\nnpm init -y

Passo 2: Instalação do Apollo Server e GraphQL

npm install apollo-server graphql

Após a instalação, criaremos o arquivo principal index.js, onde nosso servidor estará localizado.

2. Criação de um servidor GraphQL básico

Agora escreveremos um servidor mínimo que aceitará consultas e retornará respostas. Para isso, definiremos o schema e os resolvers.

Passo 1: Definição do tipo de dado

Criaremos um tipo simples Book com os campos id, title e author.

const { ApolloServer, gql } = require('apollo-server');\n\n// Schema GraphQL\nconst typeDefs = gql`\n  type Book {\n    id: ID!\n    title: String!\n    author: String!\n  }\n\n  type Query {\n    books: [Book]\n    book(id: ID!): Book\n  }\n`;\n\n// Dados de exemplo (em um projeto real — banco de dados)\nconst books = [\n  { id: '1', title: 'Guerra e Paz', author: 'Liev Tolstói' },\n  { id: '2', title: 'Crime e Castigo', author: 'Fiódor Dostoiévski' },\n  { id: '3', title: 'O Mestre e a Margarida', author: 'Mikhail Bulgákov' }\n];\n\n// Resolvers — funções que retornam dados\nconst resolvers = {\n  Query: {\n    books: () => books,\n    book: (parent, args) => books.find(book => book.id === args.id)\n  }\n};\n\n// Criação do servidor\nconst server = new ApolloServer({ typeDefs, resolvers });\n\n// Inicialização do servidor\nserver.listen().then(({ url }) => {\n  console.log(`🚀  Servidor pronto em: ${url}`);\n});

Passo 2: Inicialização e teste

Execute o comando node index.js e abra http://localhost:4000 no navegador. Você verá o GraphQL Playground — uma ferramenta para testar consultas.

Tente executar uma consulta simples:

{\n  books {\n    title\n    author\n  }\n}

A resposta deve conter a lista de livros com os campos especificados.

3. Adicionando mutações e expandindo o schema

Agora adicionaremos a capacidade de modificar dados por meio de mutações. Isso permitirá criar, atualizar e excluir registros.

Passo 1: Definição de mutações no schema

const typeDefs = gql`\n  type Book {\n    id: ID!\n    title: String!\n    author: String!\n  }\n\n  input BookInput {\n    title: String!\n    author: String!\n  }\n\n  type Query {\n    books: [Book]\n    book(id: ID!): Book\n  }\n\n  type Mutation {\n    addBook(input: BookInput!): Book\n    deleteBook(id: ID!): Book\n  }\n`;

Passo 2: Implementação dos resolvers para mutações

const resolvers = {\n  Query: {\n    books: () => books,\n    book: (parent, args) => books.find(book => book.id === args.id)\n  },\n  Mutation: {\n    addBook: (parent, args) => {\n      const newBook = {\n        id: String(books.length + 1),\n        title: args.input.title,\n        author: args.input.author\n      };\n      books.push(newBook);\n      return newBook;\n    },\n    deleteBook: (parent, args) => {\n      const index = books.findIndex(book => book.id