PHP Academy · Lección

GraphQL frente a REST

Comprenda cuándo GraphQL supera a REST y por qué

GraphQL frente a REST es una lección gratuita de PHP Academy en CoddyKit. Esta es la lección 1 de 4. Puedes leer la lección completa abajo gratuitamente — luego la practicas en el navegador con un editor de código integrado y un tutor de IA 24/7. Forma parte de la ruta de aprendizaje de PHP Academy, y tu progreso se sincroniza en la web y la app de CoddyKit. El curso de PHP Academy incluye 4 lecciones en total.

¿Por qué GraphQL?

Ya sabe cómo crear API REST en PHP. GraphQL no sustituye a HTTP ni es una solución mágica: es un lenguaje de consulta y un sistema de tipos que permite al cliente describir exactamente lo que necesita y recibir exactamente eso, en una sola ida y vuelta.

En esta lección se comparan ambos enfoques con honestidad: cuándo GraphQL ofrece una ventaja real, cuándo REST sigue siendo la opción adecuada y qué costes operativos implica GraphQL.

Over-fetching y under-fetching

Los problemas clásicos de REST:

Over-fetching: GET /users/1 devuelve 40 campos cuando la interfaz necesita 3.
Under-fetching: para mostrar las publicaciones de un usuario y el recuento de comentarios de cada publicación, se llama a /users/1, después a /users/1/posts y, a continuación, a N endpoints de comentarios.

GraphQL reduce todo esto a una única solicitud declarativa.

query {
  user(id: 1) {
    name
    posts {
      title
      commentCount
    }
  }
}

Un endpoint, un esquema tipado

REST expone muchas URL; GraphQL expone un único endpoint (normalmente POST /graphql) respaldado por un esquema fuertemente tipado. El esquema es el contrato: se puede introspeccionar, por lo que las herramientas (autocompletado, documentación y generación de código) vienen incluidas.

A continuación se muestra un esquema mínimo en SDL. La estructura de todas las respuestas posibles se conoce de antemano.

type User {
  id: ID!
  name: String!
  posts: [Post!]!
}

type Post {
  id: ID!
  title: String!
  commentCount: Int!
}

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

La respuesta refleja la consulta

Una propiedad clave es que la estructura de la respuesta JSON es predecible a partir de la consulta. Los clientes nunca tienen que adivinar los nombres de los campos. Esto elimina toda una clase de problemas de versionado: puede añadir campos sin romper los clientes antiguos y marcar campos como obsoletos con @deprecated en lugar de crear URL /v2.

{
  "data": {
    "user": {
      "name": "Ada",
      "posts": [
        { "title": "On Engines", "commentCount": 12 }
      ]
    }
  }
}

Dónde GraphQL supera a REST

GraphQL es la opción más adecuada cuando:

Atiende a muchos clientes heterogéneos (web, iOS y Android) con necesidades de datos diferentes.
Los datos forman un grafo con relaciones profundas que los clientes recorren dinámicamente.
Quiere agregar varios backends detrás de una única puerta de enlace tipada.
La iteración rápida del frontend es importante y quiere evitar cambios interminables en los endpoints del backend.

Dónde REST sigue siendo superior

No recurra a GraphQL por reflejo. REST es más sencillo y, a menudo, mejor cuando:

Necesita caché HTTP: las cachés de CDN/borde se basan en las URL y los verbos; un único POST /graphql les resulta opaco.
La API está orientada a recursos y es estable (CRUD sobre unas pocas entidades).
Depende de cargas/descargas de archivos o de streaming, donde multipart y los rangos de bytes son conceptos de primera clase en REST.
Sus consumidores son terceros que esperan la semántica convencional de REST.

Una comparación rápida en PHP

Aquí están los mismos datos ensamblados según el enfoque REST en PHP; observe que el cliente seguiría necesitando varias llamadas o que usted tendría que crear manualmente un parámetro embed. GraphQL traslada esa lógica de selección al cliente.

<?php
// REST: server decides the payload shape
function userResource(int $id): array {
    return [
        'id' => $id,
        'name' => 'Ada',
        'email' => 'ada@example.com',   // over-fetched by mobile
        'createdAt' => '1815-12-10',
        'posts' => [                       // pre-embedded, all-or-nothing
            ['title' => 'On Engines', 'commentCount' => 12],
        ],
    ];
}

header('Content-Type: application/json');
echo json_encode(userResource(1), JSON_PRETTY_PRINT);

Los costes que añade GraphQL

GraphQL traslada la complejidad al servidor. Ahora debe hacerse cargo de nuevas cuestiones:

Consultas N+1: los resolvers anidados ejecutan una consulta a la base de datos por nodo, a menos que agrupe las consultas (DataLoader).
Coste de consulta / limitación de profundidad: una consulta maliciosa con anidamiento profundo puede provocarle un DoS.
La caché es más difícil; normalmente se aplica en la capa de resolver/datos, no en HTTP.
La gestión de errores es diferente: un 200 OK puede incluir aun así un array errors.

Errores: 200 con un array errors

A diferencia de los códigos de estado de REST, GraphQL normalmente devuelve HTTP 200 e informa de los fallos parciales dentro del cuerpo. data puede estar parcialmente completo mientras errors enumera lo que falló. Sus clientes deben inspeccionar ambos.

{
  "data": { "user": null },
  "errors": [
    {
      "message": "User not found",
      "path": ["user"],
      "extensions": { "code": "NOT_FOUND" }
    }
  ]
}

Criterio práctico de decisión

Una regla práctica:

APIs públicas, con mucho uso de caché y CRUD orientado a recursos → REST.
APIs internas o de producto que alimentan clientes diversos y sofisticados sobre datos conectados → GraphQL.
Muchos backends que unificar tras un único contrato tipado → GraphQL gateway.

Es habitual y saludable utilizar ambos: REST para webhooks/cargas de archivos y GraphQL para el grafo de lectura de la aplicación.

Servir GraphQL mediante HTTP en PHP

Operativamente, un endpoint GraphQL en PHP es una única ruta que lee el cuerpo JSON, extrae query y variables, los ejecuta contra el esquema y devuelve { data, errors }. En comparación con las numerosas rutas de REST, el transporte es uniforme: toda la variación reside en la cadena de consulta que envía el cliente.

<?php
// Minimal GraphQL-over-HTTP entry point
$input = json_decode(file_get_contents('php://input'), true) ?? [];
$query = $input['query'] ?? '';
$variables = $input['variables'] ?? null;

// $result = GraphQL::executeQuery($schema, $query, null, $ctx, $variables);
// header('Content-Type: application/json');
// echo json_encode($result->toArray());
var_dump(['query' => $query, 'variables' => $variables]);

Comprobación rápida

¿Cuándo conserva REST una ventaja clara frente a GraphQL?

Resumen

Ha comparado GraphQL y REST en aspectos fundamentales:

GraphQL resuelve el overfetching y el underfetching con un único endpoint tipado y una selección controlada por el cliente.
Destaca cuando hay muchos clientes, datos con forma de grafo y agregación en el backend.
REST sigue siendo sólido para APIs públicas que se pueden almacenar en caché, CRUD sencillo, cargas de archivos y consumidores convencionales.
GraphQL traslada el coste al servidor: N+1, límites de coste de consulta, caché y semántica de respuestas 200 con errores.

Siguiente paso: crear realmente un esquema con webonyx/graphql-php.

Preguntas frecuentes

¿La lección «GraphQL frente a REST» es gratis?

Sí — el texto completo de «GraphQL frente a REST» es gratis para leer aquí en la web. Para practicarla de forma interactiva (editor de código integrado y tutor de IA 24/7) y desbloquear el resto del curso de PHP Academy, actualiza a CoddyKit PRO. El curso de PHP Academy incluye 4 lecciones en total.

¿Qué aprenderé en «GraphQL frente a REST»?

Comprenda cuándo GraphQL supera a REST y por qué Practicas PHP Academy con código real que ejecutas directamente en el navegador, y un tutor de IA 24/7 responde tus preguntas mientras trabajas en la lección.

¿Necesito experiencia previa para empezar PHP Academy?

No se requiere experiencia previa. PHP Academy en CoddyKit está estructurado para principiantes hasta estudiantes avanzados, así que puedes empezar aquí o desde el inicio y avanzar a tu ritmo. Esta es la lección 1 de 4.

¿Cuánto tiempo toma la lección «GraphQL frente a REST»?

La mayoría de las lecciones de CoddyKit toman alrededor de 5–10 minutos. Cada una es compacta e interactiva, así que avanzas constantemente y retomas exactamente por donde dejaste en la web y la app.

¿Puedo escribir y ejecutar código en esta lección de PHP Academy?

Sí. Cada lección de PHP Academy incluye un editor de código integrado, así que escribes y ejecutas código real directamente en tu navegador y obtienes retroalimentación instantánea de IA — sin configuración local necesaria.

Todas las lecciones de este curso

← Volver a PHP Academy