Un laboratorio para comparar REST y GraphQL con los mismos datos

󰃭 2026-10-29 · 8 min de lectura

Contenido

En la entrada anterior conté la teoría. Ahora toca verla. Voy a montar una base de datos pequeña, exponer los mismos datos con una API REST y con una API GraphQL, y comparar lo que pide el cliente, lo que recibe y lo que le llega a PostgreSQL por detrás.

Esta entrada es el montaje y la primera comparación, la amable. En la siguiente viene el N+1, que es donde se pone interesante.

El código completo está en Codeberg: https://codeberg.org/igalvan/blog-public-code/src/branch/main/lab-graphql.

Los datos #

Dos tablas: usuarios y pedidos. Nada más, porque con dos tablas ya se ven todos los problemas que quiero enseñar.

-- init.sql
CREATE TABLE usuarios (
  id         serial PRIMARY KEY,
  nombre     text NOT NULL,
  email      text NOT NULL,
  direccion  text,
  telefono   text,
  fecha_alta date NOT NULL
);

CREATE TABLE pedidos (
  id         serial PRIMARY KEY,
  usuario_id int NOT NULL REFERENCES usuarios(id),
  fecha      date NOT NULL,
  total      numeric(10,2) NOT NULL,
  estado     text NOT NULL
);

INSERT INTO usuarios (nombre, email, direccion, telefono, fecha_alta)
SELECT
  'Usuario ' || i,
  'usuario' || i || '@example.org',
  'Calle Mayor, ' || i,
  '600' || lpad(i::text, 6, '0'),
  date '2024-01-01' + i * 3
FROM generate_series(1, 100) AS i;

INSERT INTO pedidos (usuario_id, fecha, total, estado)
SELECT
  1 + (random() * 99)::int,
  date '2025-01-01' + (random() * 600)::int,
  round((5 + random() * 200)::numeric, 2),
  (ARRAY['pendiente', 'enviado', 'entregado'])[1 + (random() * 2)::int]
FROM generate_series(1, 500);

Cien usuarios y quinientos pedidos repartidos al azar. Los usuarios tienen seis columnas a propósito: la gracia del over-fetching es que haya cosas que sobren.

PostgreSQL en Podman #

# compose.yaml
services:
  db:
    image: docker.io/library/postgres:17
    environment:
      POSTGRES_USER: lab
      POSTGRES_PASSWORD: lab
      POSTGRES_DB: tienda
    ports:
      - "5432:5432"
    volumes:
      - ./init.sql:/docker-entrypoint-initdb.d/init.sql:Z
    command: ["postgres", "-c", "log_statement=all"]

Dos detalles. El :Z del volumen es para que SELinux deje al contenedor leer el fichero; si no usas SELinux, no estorba. Y log_statement=all hace que PostgreSQL escriba en su log todas las consultas que recibe. En producción es una barbaridad; aquí es el instrumento de medida de toda la serie.

ignacio@milab:~/lab-graphql$ podman compose up -d
ignacio@milab:~/lab-graphql$ podman compose logs db | tail -n 3
db  | 2026-10-27 18:02:11.431 UTC [1] LOG:  database system is ready to accept connections

Si en algún momento quieres empezar de cero, podman compose down -v borra también el volumen de datos y el init.sql se vuelve a ejecutar al arrancar.

El acceso a datos, compartido #

Las dos APIs van a usar exactamente el mismo módulo para hablar con la base de datos. Si no, la comparación está trucada.

# db.py
import psycopg
from psycopg.rows import dict_row

DSN = "postgresql://lab:lab@localhost:5432/tienda"


def conectar():
    return psycopg.connect(DSN, row_factory=dict_row)

dict_row hace que cada fila venga como un diccionario con el nombre de las columnas, que es lo que FastAPI y Strawberry quieren recibir.

La estructura del repositorio queda así:

lab-graphql/
├── compose.yaml
├── init.sql
├── db.py
├── api_rest/
│   └── main.py
└── api_graphql/
    └── main.py

Un aviso que me costó un rato: la carpeta del servidor GraphQL no puede llamarse graphql. Strawberry depende de una librería que se llama exactamente así, y un directorio con ese nombre en el directorio de trabajo la tapa. De ahí el api_graphql.

Dependencias, en un entorno virtual:

ignacio@milab:~/lab-graphql$ python3 -m venv .venv && source .venv/bin/activate
(.venv) ignacio@milab:~/lab-graphql$ pip install fastapi "uvicorn[standard]" "psycopg[binary]" strawberry-graphql

La API REST #

Dos endpoints, los dos de la entrada anterior. FastAPI porque es lo que menos ruido mete.

# api_rest/main.py
from fastapi import FastAPI, HTTPException, Query

from db import conectar

app = FastAPI()


@app.get("/usuarios/{id}")
def usuario(id: int):
    with conectar() as con:
        fila = con.execute(
            "SELECT * FROM usuarios WHERE id = %s", (id,)
        ).fetchone()
    if fila is None:
        raise HTTPException(404, "Usuario no encontrado")
    return fila


@app.get("/usuarios/{id}/pedidos")
def pedidos(id: int, ultimos: int = Query(10, ge=1, le=100)):
    with conectar() as con:
        return con.execute(
            """
            SELECT * FROM pedidos
            WHERE usuario_id = %s
            ORDER BY fecha DESC
            LIMIT %s
            """,
            (id, ultimos),
        ).fetchall()

/usuarios/42 devuelve el usuario entero, con sus seis campos, porque así es como se diseñan los endpoints REST: el servidor decide la forma. /usuarios/42/pedidos?ultimos=3 devuelve los pedidos enteros, cuatro campos cada uno.

(.venv) ignacio@milab:~/lab-graphql$ uvicorn api_rest.main:app --port 8000

La API GraphQL #

Strawberry define el esquema con clases de Python y anotaciones de tipo. Compáralo con el SDL de la entrada anterior: es lo mismo, escrito en otro sitio.

# api_graphql/main.py
import datetime
import decimal

import strawberry
from fastapi import FastAPI
from strawberry.fastapi import GraphQLRouter

from db import conectar


@strawberry.type
class Pedido:
    id: int
    fecha: datetime.date
    total: decimal.Decimal
    estado: str


@strawberry.type
class Usuario:
    id: int
    nombre: str
    email: str
    direccion: str | None
    telefono: str | None
    fecha_alta: datetime.date

    @strawberry.field
    def pedidos(self, ultimos: int = 10) -> list[Pedido]:
        with conectar() as con:
            filas = con.execute(
                """
                SELECT id, fecha, total, estado FROM pedidos
                WHERE usuario_id = %s
                ORDER BY fecha DESC
                LIMIT %s
                """,
                (self.id, ultimos),
            ).fetchall()
        return [Pedido(**f) for f in filas]


@strawberry.type
class Query:
    @strawberry.field
    def usuario(self, id: int) -> Usuario | None:
        with conectar() as con:
            fila = con.execute(
                "SELECT * FROM usuarios WHERE id = %s", (id,)
            ).fetchone()
        return Usuario(**fila) if fila else None


schema = strawberry.Schema(query=Query)

app = FastAPI()
app.include_router(GraphQLRouter(schema), prefix="/graphql")

Fíjate en dónde está cada consulta SQL. Query.usuario es un resolver: va a por el usuario. Usuario.pedidos es otro resolver, que se ejecuta solo si el cliente pide el campo pedidos, y que va a por los pedidos de ese usuario concreto (self.id). Los campos simples (nombre, email…) no tienen resolver: Strawberry los lee directamente del objeto.

Esto es exactamente la estructura que en la entrada anterior llamé “un controlador por campo”. Guárdate la imagen para la siguiente entrada.

Dos cosas de Strawberry que conviene saber: convierte los nombres a camelCase en el esquema, así que fecha_alta se pide como fechaAlta; y los tipos date y Decimal de Python los expone como escalares Date y Decimal sin que haya que hacer nada.

(.venv) ignacio@milab:~/lab-graphql$ uvicorn api_graphql.main:app --port 8001

Con el servidor levantado, http://localhost:8001/graphql en el navegador abre GraphiQL, una consola para escribir consultas con autocompletado contra el esquema. Es lo que en REST sería el Swagger UI de FastAPI (http://localhost:8000/docs), con la diferencia de que aquí el autocompletado sale del esquema real, no de una descripción paralela.

Primera pantalla: la ficha de un usuario #

El caso de uso: una pantalla que muestra el nombre de un usuario y la fecha e importe de sus tres últimos pedidos. Nada más.

En REST #

Dos peticiones, porque son dos recursos:

ignacio@milab:~$ curl -s localhost:8000/usuarios/42 | jq
{
  "id": 42,
  "nombre": "Usuario 42",
  "email": "usuario42@example.org",
  "direccion": "Calle Mayor, 42",
  "telefono": "600000042",
  "fecha_alta": "2024-05-06"
}
ignacio@milab:~$ curl -s 'localhost:8000/usuarios/42/pedidos?ultimos=3' | jq
[
  {
    "id": 317,
    "usuario_id": 42,
    "fecha": "2026-07-14",
    "total": 118.4,
    "estado": "entregado"
  },
  ...
]

De los seis campos del usuario, la pantalla usa uno. De los cinco de cada pedido, dos. Y el usuario_id de cada pedido es información que el cliente ya tenía: lo puso él en la URL.

En GraphQL #

Una petición, y el cliente escribe la forma de la respuesta:

ignacio@milab:~$ curl -s localhost:8001/graphql \
  -H 'Content-Type: application/json' \
  -d '{"query": "{ usuario(id: 42) { nombre pedidos(ultimos: 3) { fecha total } } }"}' | jq
{
  "data": {
    "usuario": {
      "nombre": "Usuario 42",
      "pedidos": [
        { "fecha": "2026-07-14", "total": "118.40" },
        ...
      ]
    }
  }
}

Ni un campo de más. Si mañana la pantalla necesita también el estado, el cliente lo añade a la consulta y ya está; nadie toca el servidor.

Si quieres medir el tamaño, es un wc -c al final de cada curl. Los números exactos dependen de los datos que haya generado el random(), pero la proporción es la que esperas: la respuesta GraphQL ocupa bastante menos de la mitad que las dos respuestas REST juntas.

Lo que ve PostgreSQL #

Aquí es donde el log_statement=all empieza a pagar el alquiler. Deja el log abierto en otra terminal:

ignacio@milab:~/lab-graphql$ podman compose logs -f db

Lanza las dos peticiones REST:

LOG:  statement: SELECT * FROM usuarios WHERE id = 42
LOG:  statement: SELECT * FROM pedidos WHERE usuario_id = 42 ORDER BY fecha DESC LIMIT 3

Y ahora la de GraphQL:

LOG:  statement: SELECT * FROM usuarios WHERE id = 42
LOG:  statement: SELECT id, fecha, total, estado FROM pedidos WHERE usuario_id = 42 ORDER BY fecha DESC LIMIT 3

Dos consultas en los dos casos. Para esta pantalla, lo único que cambia entre REST y GraphQL es la capa HTTP: una petición en vez de dos, y una respuesta a medida en vez de dos respuestas genéricas. La base de datos trabaja lo mismo.

(Si en el log ves execute <unnamed> en lugar de statement, es porque psycopg puede usar sentencias preparadas del lado del servidor; da igual para lo que estamos midiendo.)

Dónde estamos #

Hasta aquí GraphQL parece ganar sin despeinarse: menos peticiones, menos bytes, el cliente manda. Y para esta pantalla es verdad.

El problema es que la pantalla era de un usuario. En la tercera entrada pido cien usuarios con sus pedidos, con el mismo log abierto, y el resultado es bastante menos elegante.


¿Comentarios? Esta entrada tiene un hilo en Mastodon: responde allí y la conversación se queda en el fediverso.

Cargando comentarios desde mastodon.social…

Ingrese la dirección de su instancia


Más posts como este