Cómo Construir una API GraphQL con Apollo Server: Tutorial Paso a Paso

Introducción

En este tutorial, aprenderás a construir una API GraphQL utilizando Apollo Server y Node.js. Este contenido está pensado para desarrolladores con conocimientos básicos en JavaScript y Node.js que quieren dar un paso adelante y adentrarse en el desarrollo backend moderno con GraphQL. Cubriremos desde la configuración del entorno hasta la integración con una base de datos y pruebas básicas para tu API.

Este GraphQL Node.js tutorial te guiará paso a paso para que comprendas la arquitectura y buenas prácticas al crear tu API. También incluimos bloques de código claros y explicaciones detalladas para facilitar el aprendizaje.

¿Qué es GraphQL y por qué usar Apollo Server?

GraphQL es un lenguaje y runtime para realizar consultas en APIs, que permite obtener exactamente los datos que necesitas, ni más ni menos. A diferencia de REST, GraphQL evita múltiples endpoints y favorece la eficiencia y flexibilidad.

Apollo Server es una de las herramientas más populares para implementar servidores GraphQL en Node.js. Nos brinda un ecosistema sólido y fácil integración con bases de datos, autorización, manejo de errores y otros.

Requisitos previos

Conocimientos básicos en JavaScript y Node.js
Node.js instalado (versión 14+ recomendada)
npm o yarn como gestor de paquetes

1. Configurar el entorno de desarrollo

Primero, crea una carpeta para tu proyecto e inicia npm:

mkdir api-graphql-apollo
cd api-graphql-apollo
npm init -y

mkdir api-graphql-apollo

cd api-graphql-apollo

npm init -y

Luego, instala las dependencias principales:

npm install apollo-server graphql

1 2	npm install apollo-server graphql

apollo-server es el paquete principal para levantar el servidor GraphQL.

graphql contiene las utilidades para definir esquemas y validación.

2. Definir el esquema y tipos GraphQL

El esquema describe las capacidades de tu API: los tipos de datos y las operaciones disponibles (queries y mutations).

Crea el archivo index.js y define un esquema básico de ejemplo para un sistema de gestión de libros:

const { ApolloServer, gql } = require('apollo-server');

// Definimos el esquema GraphQL usando SDL
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
  }
`;

const { ApolloServer, gql } = require('apollo-server');

// Definimos el esquema GraphQL usando SDL

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

}

Explicación:

Book: tipo personalizado con campos id, title y author.
Query: define dos consultas, books para obtener todos los libros y book para obtener uno por id.
Mutation: permite agregar un libro.

3. Crear los resolvers

Los resolvers contienen la lógica para responder las consultas y mutaciones del esquema.

Añade el siguiente código en index.js debajo de typeDefs:

// Datos de ejemplo en memoria
const books = [
  { id: '1', title: '1984', author: 'George Orwell' },
  { id: '2', title: 'El Quijote', author: 'Miguel de Cervantes' },
];

// Definimos los resolvers
const resolvers = {
  Query: {
    books: () => books,
    book: (_, { id }) => books.find(book => book.id === id),
  },
  Mutation: {
    addBook: (_, { title, author }) => {
      const newBook = {
        id: String(books.length + 1),
        title,
        author,
      };
      books.push(newBook);
      return newBook;
    },
  },
};

// Datos de ejemplo en memoria

const books = [

{ id: '1', title: '1984', author: 'George Orwell' },

{ id: '2', title: 'El Quijote', author: 'Miguel de Cervantes' },

];

// Definimos los resolvers

const resolvers = {

Query: {

books: () => books,

book: (_, { id }) => books.find(book => book.id === id),

Mutation: {

addBook: (_, { title, author }) => {

const newBook = {

id: String(books.length + 1),

title,

author,

};

books.push(newBook);

return newBook;

};

Este código:

Simula una base de datos con un array books.
Resuelve consultas y mutaciones manipulando este array.

4. Inicializar Apollo Server y levantar el servidor

El siguiente paso es crear la instancia de Apollo Server y que comience a escuchar las peticiones.

Al final del archivo index.js añade:

const server = new ApolloServer({ typeDefs, resolvers });

server.listen().then(({ url }) => {
  console.log(`🚀 Servidor listo en ${url}`);
});

const server = new ApolloServer({ typeDefs, resolvers });

server.listen().then(({ url }) => {

console.log(`🚀 Servidor listo en ${url}`);

});

Para ejecutar el servidor:

node index.js

1 2	node index.js

Al abrir el navegador en la URL que aparezca (usualmente http://localhost:4000/) verás Apollo Sandbox, una interfaz para interactuar con tu API.

5. Integración con base de datos

Usar una base de datos real es fundamental para desarrollo backend.

Ejemplo con SQLite y Prisma

Instalemos un ORM para facilitar operaciones con bases de datos. Aquí usaré Prisma y SQLite para simplicidad.

npm install prisma @prisma/client
npx prisma init

npm install prisma @prisma/client

npx prisma init

Configura prisma/schema.prisma para SQLite:

datasource db {
  provider = "sqlite"
  url      = "file:./dev.db"
}

generator client {
  provider = "prisma-client-js"
}

type Book {
  id     Int     @id @default(autoincrement())
  title  String
  author String
}

datasource db {

provider = "sqlite"

url = "file:./dev.db"

}

generator client {

provider = "prisma-client-js"

}

type Book {

id Int @id @default(autoincrement())

title String

author String

}

Crea la base de datos y aplica migrations:

npx prisma migrate dev --name init

1 2	npx prisma migrate dev --name init

Luego, adapta el servidor para usar Prisma.

Modifica index.js para incluir:

const { PrismaClient } = require('@prisma/client');
const prisma = new PrismaClient();

const resolvers = {
  Query: {
    books: () => prisma.book.findMany(),
    book: (_, { id }) => prisma.book.findUnique({ where: { id: Number(id) } }),
  },
  Mutation: {
    addBook: (_, { title, author }) =>
      prisma.book.create({ data: { title, author } }),
  },
};

const { PrismaClient } = require('@prisma/client');

const prisma = new PrismaClient();

const resolvers = {

Query: {

books: () => prisma.book.findMany(),

book: (_, { id }) => prisma.book.findUnique({ where: { id: Number(id) } }),

Mutation: {

addBook: (_, { title, author }) =>

prisma.book.create({ data: { title, author } }),

};

Finalmente, ejecuta nuevamente:

node index.js

1 2	node index.js

Con esto tu API GraphQL ya está conectada con una base de datos real.

6. Probar tu API GraphQL

Desde Apollo Sandbox o cualquier cliente GraphQL como Insomnia o Postman, puedes probar:

Consulta para obtener todos los libros:

query {
  books {
    id
    title
    author
  }
}

query {

books {

title

author

}

Mutación para agregar un libro:

mutation {
  addBook(title: "El Principito", author: "Antoine de Saint-Exupéry") {
    id
    title
    author
  }
}

mutation {

addBook(title: "El Principito", author: "Antoine de Saint-Exupéry") {

title

author

}

Consulta para un libro por id:

query {
  book(id: "1") {
    id
    title
    author
  }
}

query {

book(id: "1") {

title

author

}

Buenas prácticas en desarrollo backend GraphQL

Validar y sanitizar entradas: evita inyección y errores inesperados.
Manejar errores en resolvers: responde con mensajes claros y códigos apropiados.
Limitar tamaño y complejidad de consultas: para evitar abuso (query complexity).
Documentar el esquema: facilita a consumidores entender la API.
Usar autenticación y autorización: proteger mutaciones y datos sensibles.

Conclusión

En este tutorial has aprendido cómo construir una API GraphQL con Apollo Server usando Node.js, desde lo más básico hasta integrar una base de datos real con Prisma y SQLite. Este enfoque es ideal para desarrollo backend moderno, donde las APIs deben ser flexibles, eficientes y fáciles de mantener.

Ahora te invito a que pruebes, extiendas y personalices tu API. Explora conceptos avanzados como suscripciones, federación y optimización de consultas para profundizar aún más.

¡Empieza a crear APIs potentes con GraphQL y Node.js hoy!

Recursos adicionales

¡Manos a la obra y buen desarrollo!