Lección 282: Conceptos básicos de GraphQL

Hoy nos meteremos de lleno en los conceptos clave de GraphQL. Hablaremos de esquemas, queries, mutations y subscriptions — los cuatro pilares sobre los que se sostiene GraphQL. También veremos cómo estas ideas ayudan a diseñar APIs más flexibles y cómodas de usar.

¿Qué son los esquemas y los tipos en GraphQL?

El esquema (Schema) —es el conjunto de reglas que define cómo el cliente puede interactuar con el servidor. Sirve para tipar estrictamente tu API. Podríamos decir que el esquema es un pacto entre servidor y cliente: "¡Así es como puedes hablar conmigo!"

Ejemplo de esquema en GraphQL:

type Query {
    hello: String
    user(id: ID!): User
}

type User {
    id: ID!
    name: String!
    email: String!
}

En este ejemplo:

• Tenemos el tipo Query, que define qué datos se pueden pedir:
  • El campo hello devuelve una cadena.
  • El campo user devuelve un objeto del tipo User, aceptando un parámetro obligatorio id (ID!).

• Se ha definido el tipo User, que describe el objeto usuario:
  • Los campos id, name y email están fuertemente tipados.

Tipos principales de GraphQL

GraphQL ofrece varios tipos escalares estándar (Scalar Types):

• String — cadena.
• Int — número entero.
• Float — número de punto flotante.
• Boolean — valor lógico.
• ID — identificador único (en esencia, una cadena).

Ejemplo usando estos tipos:

type Product {
    id: ID!
    name: String!
    price: Float!
    inStock: Boolean
}

Aquí Product describe un producto:

• El campo price —es un número de punto flotante (por ejemplo, 1299.99).
• El campo inStock es opcional (Boolean sin !), así que puede ser null.

Tipos avanzados

GraphQL también soporta:

• Enum (enumeraciones): un conjunto fijo de valores.

    enum Role {
  ADMIN
  USER
  GUEST
  }
  

• Input (tipos de objeto de entrada): se usan para pasar datos complejos.

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

• Union e Interface: para describir jerarquías de tipos más flexibles.

Queries: Cómo pedir datos

Los queries en GraphQL son la forma de obtener datos del servidor. La idea es que el cliente decide exactamente qué quiere. Es como pedir una hamburguesa en un restaurante —puedes pedir sólo la carne o el combo completo con todos los toppings.

Ejemplo de query:

query {
    user(id: "123") {
        name
        email
    }
}

Respuesta del servidor:

{
  "data": {
    "user": {
      "name": "John Smith",
      "email": "john@example.com"
    }
  }
}

La idea clave: el cliente pide sólo los datos necesarios (name y email) y nada más.

Argumentos en los queries

El query user(id: "123") lleva el argumento id. Los argumentos permiten precisar qué datos quieres. Por ejemplo:

query {
    product(id: "456") {
        name
        price
    }
}

Respuesta del servidor:

{
  "data": {
    "product": {
      "name": "Guitarra",
      "price": 1299.99
    }
  }
}

Los argumentos pueden ser escalares, arrays o incluso objetos.

Mutations: Cómo modificar datos

Las mutations son acciones que cambian datos en el servidor. Son el equivalente a POST/PUT/PATCH/DELETE en REST. Por ejemplo, para crear un usuario nuevo, podrías usar esta mutation:

mutation {
    createUser(input: {
        name: "Jane Doe",
        email: "jane@example.com",
        password: "secret"
    }) {
        id
        name
    }
}

Respuesta del servidor:

{
  "data": {
    "createUser": {
      "id": "789",
      "name": "Jane Doe"
    }
  }
}

Aquí:

• La clave createUser indica la mutation que crea un usuario nuevo.
• El argumento input pasa los datos para la creación.
• La respuesta incluye los datos creados: id y name.

Diferencias entre mutations y queries

Las mutations siempre tienen efectos secundarios (side effects), es decir, cambian el estado de los datos. Por ejemplo, añaden un registro a la base de datos o actualizan uno existente. Los queries, en cambio, son seguros y sólo devuelven datos.

Subscriptions: tiempo real

Las subscriptions son el mecanismo de GraphQL que permite a los clientes recibir actualizaciones en tiempo real cuando los datos cambian. Por ejemplo, para un chat puedes configurar una subscription para nuevos mensajes:

subscription {
    newMessage {
        id
        content
        sender {
            name
        }
    }
}

Cuando un usuario envía un mensaje nuevo, el servidor notifica automáticamente a todos los suscriptores.

La respuesta que recibe el cliente podría verse así:

{
  "data": {
    "newMessage": {
      "id": "1001",
      "content": "¡Hola!",
      "sender": {
        "name": "Iván"
      }
    }
  }
}

Uso en proyectos reales

Las subscriptions encajan perfecto en escenarios de tiempo real:

• Apps de chat.
• Notificaciones sobre el estado de pedidos.
• Métricas en tiempo real en sistemas de monitorización.

¿Cómo funciona todo junto?

GraphQL permite combinar queries, mutations y subscriptions en una sola interfaz. Por ejemplo, puedes:

1. Solicitar la lista de usuarios (queries).
2. Crear usuarios nuevos (mutations).
3. Recibir notificaciones automáticas cuando se añaden usuarios nuevos (subscriptions).

¿Por qué GraphQL gana frente a REST?

Flexibilidad

En REST hay una correspondencia rígida entre URI y recursos. Por ejemplo:

• GET /users/123 — devuelve todos los datos del usuario.
• Pero, ¿qué hacer si el cliente sólo quiere el nombre?

GraphQL resuelve ese problema permitiendo pedir exactamente lo que hace falta.

Universalidad

GraphQL unifica endpoints dispersos de REST en un único punto de entrada. En vez de hacer tres llamadas REST distintas para juntar datos de usuario, pedidos y productos, GraphQL te deja hacerlo en una sola petición.

Ejemplo:

query {
    user(id: "123") {
        name
        orders {
            id
            products {
                name
            }
        }
    }
}

Ahora ya sabes cómo funcionan los conceptos clave de GraphQL: esquemas, queries, mutations y subscriptions. La buena noticia: no nos quedamos en la teoría —en las siguientes lecciones lo implementaremos en práctica. ¡Prepárate para codificar!