Tutorial Completo para Crear una API GraphQL con Node.js y Apollo Server

Este tutorial está diseñado para desarrolladores con conocimientos intermedios en JavaScript que desean crear una API GraphQL utilizando Node.js y Apollo Server. A lo largo de este artículo, te guiaremos en la configuración del entorno, definición del esquema, creación de resolvers, conexión con MongoDB, pruebas y despliegue básico.

¿Qué es GraphQL y por qué usarlo?

GraphQL es un lenguaje de consultas para APIs que ofrece una forma eficiente y poderosa para que el cliente solicite exactamente los datos que necesita, ni más ni menos. A diferencia de REST, GraphQL permite una sola petición que puede incluir múltiples recursos relacionados, optimizando la comunicación y reduciendo la sobrecarga.

Apollo Server es una biblioteca que facilita la creación de un servidor GraphQL en Node.js, ofreciendo una integración sencilla, excelente rendimiento y funcionalidades avanzadas.

Configuración del entorno

Para empezar con el tutorial GraphQL Node.js, asegurémonos de contar con las herramientas básicas:

Node.js (v14 o superior recomendado)
npm o yarn
MongoDB (local o en la nube, por ejemplo, MongoDB Atlas)

Paso 1: Crear un nuevo proyecto

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

mkdir graphql-node-api

cd graphql-node-api

npm init -y

Paso 2: Instalar dependencias

npm install apollo-server graphql mongoose dotenv

1 2	npm install apollo-server graphql mongoose dotenv

Dependencias:

apollo-server: Servidor GraphQL para Node.js

graphql: Implementación del lenguaje GraphQL

mongoose: ODM para conectar con MongoDB

dotenv: Manejo de variables de entorno

Paso 3: Configurar la estructura del proyecto

Una estructura simple podría ser:

/graphql-node-api
  |-- index.js
  |-- schema.js
  |-- resolvers.js
  |-- models/
        |-- User.js
  |-- .env

/graphql-node-api

|-- index.js

|-- schema.js

|-- resolvers.js

|-- models/

|-- User.js

|-- .env

Definición del esquema GraphQL

El esquema GraphQL define los tipos de datos, consultas (queries) y mutaciones (modificaciones) disponibles.

Paso 4: Crear el esquema `schema.js`

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

const typeDefs = gql`
  type User {
    id: ID!
    name: String!
    email: String!
  }

  type Query {
    users: [User!]!
    user(id: ID!): User
  }

  input CreateUserInput {
    name: String!
    email: String!
  }

  type Mutation {
    createUser(input: CreateUserInput!): User!
    deleteUser(id: ID!): Boolean!
  }
`;

module.exports = typeDefs;

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

const typeDefs = gql`

type User {

id: ID!

email: String!

}

type Query {

users: [User!]!

user(id: ID!): User

}

input CreateUserInput {

email: String!

}

type Mutation {

createUser(input: CreateUserInput!): User!

deleteUser(id: ID!): Boolean!

}

module.exports = typeDefs;

Explicación:

Definimos un tipo User con id, name y email.
Query ofrece métodos para obtener todos los usuarios o uno específico.
Mutation permite crear y eliminar usuarios.

Creación de resolvers

Los resolvers son funciones que se ejecutan para responder cada campo definido en el esquema.

Paso 5: Crear el archivo `resolvers.js`

const User = require('./models/User');

const resolvers = {
  Query: {
    users: async () => await User.find(),
    user: async (_, { id }) => await User.findById(id),
  },

  Mutation: {
    createUser: async (_, { input }) => {
      const user = new User(input);
      await user.save();
      return user;
    },
    deleteUser: async (_, { id }) => {
      const result = await User.findByIdAndDelete(id);
      return result ? true : false;
    },
  },
};

module.exports = resolvers;

const User = require('./models/User');

const resolvers = {

Query: {

users: async () => await User.find(),

user: async (_, { id }) => await User.findById(id),

Mutation: {

createUser: async (_, { input }) => {

const user = new User(input);

await user.save();

return user;

deleteUser: async (_, { id }) => {

const result = await User.findByIdAndDelete(id);

return result ? true : false;

};

module.exports = resolvers;

Conexión con MongoDB

Utilizaremos Mongoose para la conexión y modelado de la base de datos.

Paso 6: Crear modelo `User` en `/models/User.js`

const mongoose = require('mongoose');

const userSchema = new mongoose.Schema({
  name: { type: String, required: true },
  email: { type: String, required: true, unique: true },
});

module.exports = mongoose.model('User', userSchema);

const mongoose = require('mongoose');

const userSchema = new mongoose.Schema({

email: { type: String, required: true, unique: true },

});

module.exports = mongoose.model('User', userSchema);

Paso 7: Configurar variables de entorno

Crea un archivo .env con la conexión a MongoDB:

MONGODB_URI=mongodb+srv://usuario:contraseña@cluster0.mongodb.net/mydatabase?retryWrites=true&w=majority
PORT=4000

MONGODB_URI=mongodb+srv://usuario:contraseña@cluster0.mongodb.net/mydatabase?retryWrites=true&w=majority

PORT=4000

Puedes usar MongoDB Atlas para una base de datos en la nube gratuita.

Paso 8: Configurar `index.js`

require('dotenv').config();
const { ApolloServer } = require('apollo-server');
const mongoose = require('mongoose');

const typeDefs = require('./schema');
const resolvers = require('./resolvers');

async function startServer() {
  // Conexión a MongoDB
  try {
    await mongoose.connect(process.env.MONGODB_URI, {
      useNewUrlParser: true,
      useUnifiedTopology: true,
    });
    console.log('✅ Conectado a MongoDB');
  } catch (error) {
    console.error('❌ Error conectando a MongoDB:', error);
    process.exit(1);
  }

  // Crear servidor Apollo
  const server = new ApolloServer({ typeDefs, resolvers });

  // Lanzar servidor
  server.listen({ port: process.env.PORT || 4000 }).then(({ url }) => {
    console.log(`🚀 Servidor listo en ${url}`);
  });
}

startServer();

require('dotenv').config();

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

const mongoose = require('mongoose');

const typeDefs = require('./schema');

const resolvers = require('./resolvers');

async function startServer() {

// Conexión a MongoDB

try {

await mongoose.connect(process.env.MONGODB_URI, {

useNewUrlParser: true,

useUnifiedTopology: true,

});

console.log('✅ Conectado a MongoDB');

} catch (error) {

console.error('❌ Error conectando a MongoDB:', error);

process.exit(1);

}

// Crear servidor Apollo

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

// Lanzar servidor

server.listen({ port: process.env.PORT || 4000 }).then(({ url }) => {

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

});

}

startServer();

Pruebas de consultas y mutaciones

Apollo Server incluye una interfaz llamada Apollo Sandbox (reemplazo moderno de GraphQL Playground), accesible en el navegador desde la URL del servidor, ideal para probar.

Paso 9: Ejecuta el servidor

node index.js

1 2	node index.js

Paso 10: Probar la mutación para crear usuario

En la interfaz web, ejecuta:

mutation {
  createUser(input: { name: "Juan Perez", email: "juan@example.com" }) {
    id
    name
    email
  }
}

mutation {

createUser(input: { name: "Juan Perez", email: "juan@example.com" }) {

name

}

Paso 11: Probar la consulta para obtener usuarios

query {
  users {
    id
    name
    email
  }
}

query {

users {

name

}

Paso 12: Probar eliminación de usuario

mutation {
  deleteUser(id: "ID_DEL_USUARIO")
}

mutation {

deleteUser(id: "ID_DEL_USUARIO")

}

Reemplaza ID_DEL_USUARIO por el valor real obtenido de la creación o consulta.

Despliegue básico

Para un despliegue básico puedes usar Heroku, Vercel o similar. Aquí te mostramos una guía rápida para Heroku.

Paso 13: Preparar proyecto para despliegue

Añade un archivo Procfile con el contenido:

web: node index.js

1 2	web: node index.js

Asegúrate de que todas las variables de entorno estén configuradas en Heroku.

Paso 14: Desplegar en Heroku

heroku login
heroku create nombre-de-tu-app
heroku config:set MONGODB_URI='tu_uri_de_mongodb'

git init
heroku git:remote -a nombre-de-tu-app

git add .
git commit -m "Deploy GraphQL API"

git push heroku master

heroku login

heroku create nombre-de-tu-app

heroku config:set MONGODB_URI='tu_uri_de_mongodb'

git init

heroku git:remote -a nombre-de-tu-app

git add .

git commit -m "Deploy GraphQL API"

git push heroku master

Al finalizar, Heroku desplegará tu aplicación y te entregará una URL que podrás abrir y usar para probar la API en producción.

Conclusión y buenas prácticas

En este tutorial hemos creado una API GraphQL con Node.js utilizando Apollo Server desde cero, conectándonos a una base de datos MongoDB para almacenar y manipular usuarios. También te mostramos cómo hacer consultas, mutaciones y un despliegue básico.

Buenas prácticas recomendadas:

Validación y manejo de errores: Añade validaciones para inputs y maneja errores adecuadamente en resolvers.
Autenticación y autorización: Implementa mecanismos de seguridad como JWT para proteger mutaciones y consultas.
Modulariza tu código: Conforme crezca tu API, divide los resolvers y esquemas en módulos por entidad.
Documenta tu API: Aprovecha herramientas como GraphQL Playground para generar documentación interactiva.
Testing: Incluye pruebas automatizadas para resolver funciones y consultas.

Te invitamos a seguir profundizando en el mundo de GraphQL y el desarrollo backend Node.js para construir APIs escalables y modernas.

¿Quieres más tutoriales y recursos prácticos? Suscríbete y comparte este artículo con otros desarrolladores.