Como Construir um Servidor de API GraphQL com Apollo Server

Já se perguntou como criar uma API poderosa que permite aos clientes pedir exatamente o que precisam? Essa é a mágica do GraphQL, e com o Apollo Server, construir uma é mais simples do que você imagina! Se você está cansado dos endpoints rígidos do REST, o GraphQL oferece flexibilidade, e o Apollo Server é a ferramenta ideal para fazer isso acontecer. Neste tutorial conversacional, vamos guiar você na configuração de um servidor GraphQL usando o Apollo Server, desde a inicialização do projeto até o teste de queries e mutations. Seja você usando JavaScript ou TypeScript, terá um servidor funcionando em pouco tempo. Vamos mergulhar e construir algo incrível com GraphQL e Apollo Server!

💡

Quer uma ótima ferramenta de Teste de API que gera documentação de API bonita?

Quer uma plataforma integrada e All-in-One para sua Equipe de Desenvolvedores trabalharem juntos com produtividade máxima?

Apidog entrega todas as suas demandas e substitui o Postman por um preço muito mais acessível!

button

Por que escolher GraphQL e Apollo Server?

Antes de arregaçarmos as mangas, vamos conversar sobre por que o GraphQL e o Apollo Server formam uma dupla tão dinâmica. O GraphQL, desenvolvido pelo Facebook em 2012 e de código aberto em 2015, é uma linguagem de consulta para APIs que permite aos clientes solicitar dados específicos, reduzindo o over-fetching (excesso de dados) e o under-fetching (falta de dados) comuns em APIs REST. Em vez de múltiplos endpoints, você tem um endpoint inteligente que serve respostas personalizadas. É eficiente, flexível e perfeito para aplicativos modernos com necessidades de dados complexas.

Apresentamos o Apollo Server, um servidor GraphQL de código aberto e impulsionado pela comunidade, da Apollo GraphQL. Ele está pronto para produção, suporta Node.js e se integra perfeitamente com bancos de dados como MongoDB ou PostgreSQL. Com recursos como schema stitching, caching e subscriptions em tempo real, é uma solução completa para construir APIs escaláveis. Além disso, é amigável para iniciantes, mas poderoso para profissionais. Comparado a alternativas como Express-GraphQL, o Apollo Server oferece melhor monitoramento de desempenho e configuração mais fácil. Se você está construindo um blog, um site de e-commerce ou um backend móvel, essa combinação economizará tempo e dores de cabeça. Animado? Vamos configurar nosso projeto!

Configurando seu Projeto em JavaScript ou TypeScript

Vamos começar criando a base. Vamos configurar um projeto Node.js e instalar os pacotes necessários. Você pode escolher JavaScript para simplicidade ou TypeScript para segurança de tipo – ambos funcionam muito bem com o Apollo Server.

Passo 1: Inicialize o Projeto

Crie uma Nova Pasta:

Abra seu terminal e crie um diretório de projeto:

mkdir graphql-apollo-server
cd graphql-apollo-server

Inicialize o Node.js:

Execute os seguintes comandos:

npm init -y
npm pkg set type="module"

Isso cria um arquivo package.json para gerenciar dependências e configura um projeto usando Módulos ES.

Passo 2: Instale as Dependências

O Apollo Server requer dois pacotes principais: @apollo/server para o servidor e graphql para a biblioteca central do GraphQL. Para TypeScript, adicionaremos tipos e uma etapa de build.

Instale as dependências:

npm install @apollo/server graphql

Para JavaScript:

Basta substituir a entrada scripts padrão em seu arquivo package.json por estas entradas type e scripts:

{
	// ...etc.
	"type": "module",
    "scripts": {
    	"start": "node index.js"
    }
    // other dependencies
}

Para TypeScript (Recomendado):

1. Inicialize o TypeScript:

npm install --save-dev typescript @types/node

Crie um arquivo tsconfig.json em seu diretório raiz e edite-o para incluir:

{
  "compilerOptions": {
    "rootDirs": ["src"],
    "outDir": "dist",
    "lib": ["es2023"],
    "target": "es2023",
    "module": "esnext",
    "moduleResolution": "node",
    "esModuleInterop": true,
    "types": ["node"]
  }
}

2. Finalmente, substitua a entrada scripts em seu arquivo package.json pelas seguintes entradas type e scripts:

{
	// ...etc.
    "type": "module",
    "scripts": {
    	"compile": "tsc",
    	"start": "npm run compile && node ./dist/index.js"
    }
	// other dependencies
}

Dica Profissional: Se você é novo no TypeScript, ele adiciona segurança de tipo ao seu schema e resolvers, capturando erros precocemente. JavaScript é mais rápido para protótipos — escolha com base na escala do seu projeto.

Passo 3: Crie o Arquivo do Servidor

Crie uma pasta src na raiz do seu projeto e adicione um arquivo index.ts (ou index.js para JavaScript) na nova pasta. É aqui que definiremos o schema e os resolvers.

Testando uma Query Simples

Vamos construir nossa primeira query — uma mensagem simples de "olá". Isso introduz as definições de tipo (schema) e os resolvers (funções que buscam dados) do GraphQL.

Defina o Schema GraphQL

O schema é o projeto da sua API. Use a tag gql do graphql-tag (incluído com @apollo/server) para defini-lo.

Em index.ts (ou index.js):

import { ApolloServer } from '@apollo/server';
import { startStandaloneServer } from '@apollo/server/standalone';


// Define GraphQL schema
const typeDefs = `
  type Query {
    hello: String
  }
`;

// Define resolvers
const resolvers = {
  Query: {
    hello: () => "Hello! Welcome to my server",
  },
};

// Create and start the server
const server = new ApolloServer({ typeDefs, resolvers });

const { url } = await startStandaloneServer(server, {
  listen: { port: 4000 },
});

console.log(`🚀  Server ready at: ${url}`);

Para JavaScript, importe os tipos:

const { ApolloServer } = '@apollo/server';
const { startStandaloneServer } = '@apollo/server/standalone';

// Rest is the same

Execute o Servidor

Inicie seu servidor:

node index.js  # For JavaScript
npm start  # For TypeScript

Visite http://localhost:4000 em seu navegador. Você verá o GraphQL Playground — um IDE baseado na web para testar queries.

Teste a Query

No Playground, execute esta query no painel esquerdo:

query {
  hello
}

Clique em "Execute." À direita, você verá:

{
  "data": {
    "hello": "Hello! Welcome to my server"
  }
}

Sucesso! Esta query simples demonstra os fundamentos do GraphQL: um tipo Query com um campo hello que retorna uma string. Os Resolvers são os "cérebros" que fornecem os dados — neste caso, uma mensagem estática. É um ótimo ponto de partida para verificar sua configuração.

Testando uma Query com um Tipo Complexo

Agora, vamos adicionar um pouco mais de profundidade com um tipo personalizado. Criaremos um tipo Book e uma query para buscar uma lista de livros. Isso mostra como o GraphQL lida com dados estruturados.

Atualize o Schema

Modifique typeDefs para incluir um tipo Book:

const typeDefs = gql`
  type Book {
    title: String
    author: String
  }

  type Query {
    books: [Book]
  }
`;

Adicione Dados de Exemplo

Abaixo de typeDefs, adicione os seguintes dados de exemplo para o nosso novo tipo Book:

// Sample data
const books = [
  {
    title: 'The Awakening',
    author: 'Kate Chopin',
  },
  {
    title: 'City of Glass',
    author: 'Paul Auster',
  },
];

Atualize os Resolvers

Substitua o conteúdo do resolver pelo seguinte para o tipo books:

const resolvers = {
  Query: {
    books: () => books
  }
};

Reinicie o servidor e volte ao Playground.

Teste a Query

Execute:

query GetBooks {
  books {
    title
    author
  }
}

Resultado:

{
  "data": {
    "books": [
      {
        "title": "The Awakening",
        "author": "Kate Chopin"
      },
      {
        "title": "City of Glass",
        "author": "Paul Auster"
      }
    ]
  }
}

Legal, né? Esta query busca um array de objetos Book. O GraphQL permite que os clientes especifiquem exatamente quais campos eles querem — nem mais, nem menos. Se você omitir author, ele retornará apenas os títulos. Essa flexibilidade é o motivo pelo qual o GraphQL supera o REST para aplicativos com muitos dados.

Testando uma Mutation para Adicionar Dados

Queries são para leitura, mas mutations são para escrita. Vamos adicionar uma mutation para criar um novo livro, demonstrando como o GraphQL lida com a criação de dados.

Atualize o Schema

Adicione um tipo Mutation:

const typeDefs = `
  type Book {
    title: String
    author: String
  }

  type Query {
    books: [Book]
  }

  type Mutation {
    createBook(title: String!, author: String!): Book
  }
`;

O ! significa campos obrigatórios.

Atualize os Resolvers

const resolvers = {
  Query: {
    books: () => books,
  },
  Mutation: {
    createBook: (_: any, { title, author }: { title: string; author: string }) => {
      const newBook = { title, author };
      books.push(newBook);
      return newBook;
    }
  }  
};

Teste a Mutation

No Playground, execute:

mutation CreateBook{
  createBook(title: "Harry Potter", author: "J.K Rowling") {
    author
    title
  }
}

Resultado:

{
  "data": {
    "createBook": {
      "title": "Harry Potter",
      "author": "J.K Rowling"
    }
  }
}

Para confirmar, execute novamente a query GetBooks:

query GetBooks {
  books {
    title
    author
  }
}

Resultado:

{
  "data": {
    "books": [
      {
        "title": "The Awakening",
        "author": "Kate Chopin"
      },
      {
        "title": "City of Glass",
        "author": "Paul Auster"
      },
      {
        "title": "Harry Potter",
        "author": "J.K Rowling"
      }
    ]
  }
}

O novo livro foi adicionado! As mutations retornam os dados criados, permitindo que os clientes obtenham feedback imediato. Em produção, conecte-se a um DB como o MongoDB para persistência.

JavaScript vs TypeScript: Qual Escolher? Para protótipos rápidos, JavaScript é bom — menos código repetitivo. Mas para projetos maiores, TypeScript se destaca com segurança de tipo para schemas e resolvers. TS captura erros precocemente, tornando seu servidor GraphQL mais robusto.

Adicionando Mais Complexidade: IDs e Queries com Argumentos

Para torná-lo real, adicione IDs aos livros e uma query para buscar por título.

Atualize o schema:

const typeDefs = `
    type Book {
      id: ID!
      title: String
      author: String
    }

    type Query {
      books: [Book]
      book(title: String!): Book
    }

    type Mutation {
      createBook(title: String!, author: String!): Book
    }
`;

Atualize os dados e resolvers:

// Sample data
const books = [
  {
    id: 1,
    title: 'The Awakening',
    author: 'Kate Chopin',
  },
  {
    id: 2,
    title: 'City of Glass',
    author: 'Paul Auster',
  },
];

// Resolvers 
const resolvers = {
  Query: {
    books: () => books,
    book: (_: any, { title }: { title: string }) => books.find(book => book.title === title),
  },
  Mutation: {
    createBook: (_: any, { title, author }: { title: string; author: string }) => {
      const newBook = { id: books.length + 1, title, author };
      books.push(newBook);
      return newBook;
    }
  }  
};

Teste a query:

query GetBook {
  book(title: "The Awakening") {
    id
    title
    author
  }
}

Resultado:

{
  "data": {
    "book": {
      "id": "1",
      "title": "The Awakening",
      "author": "Kate Chopin"
    }
  }
}

Isso mostra argumentos em queries, permitindo que os clientes filtrem dados de forma eficiente.

Melhores Práticas para GraphQL com Apollo Server

Design do Schema: Mantenha-o modular com múltiplos arquivos.
Tratamento de Erros: Use ApolloError para erros personalizados.
Desempenho: Habilite o caching com @apollo/cache-control.
Subscriptions: Adicione recursos em tempo real com apollo-server-express.
Monitoramento: Use o Apollo Studio para métricas.

Solução de Problemas Comuns

Servidor Não Iniciando? Verifique a versão do Node (14+) e as dependências.
Erros de Query? Verifique a correspondência entre schema/resolver.
Problemas de CORS? Adicione { cors: { origin: '*' } } às opções do servidor.
Erros de TS? Instale @types/graphql e @types/node.

Conclusão

Construímos um servidor GraphQL robusto com Apollo Server, desde queries simples até mutations. Seja em JS ou TS, você está pronto para criar APIs flexíveis. Experimente, adicione subscriptions e faça deploy para o Heroku. GraphQL e Apollo Server são seu bilhete para APIs eficientes!

O Apidog também suporta testes com GraphQL, então não deixe de conferir, é totalmente GRÁTIS!

button