{"canonical_url":"https://engineer.company/es/glossary/graphql/","content_markdown":"# GraphQL\n\n## Qué es\n\nGraphQL es un lenguaje de consultas para API junto con el entorno de ejecución que las resuelve en el servidor. El cliente envía un documento que nombra los campos exactos que quiere y el servidor responde con datos de esa misma forma. La especificación lo describe como lenguaje y motor de ejecución para aplicaciones cliente-servidor. Registra su creación en 2012, el comienzo del trabajo como estándar abierto en 2015 y su condición, desde 2019, de producto del GraphQL Specification Project bajo la Joint Development Foundation. La última versión es la edición de septiembre de 2025.\n\nTodo parte del esquema publicado por el servicio: tipos con campos con nombre, cada campo con su propio tipo. Los escalares integrados son `Int`, `Float`, `String`, `Boolean` e `ID`; el servicio puede añadir otros, como uno para UUID. Todos los tipos admiten null salvo que se marquen con `!`: `String!` nunca puede ser null. Las listas se escriben entre corchetes: `[LineItem!]!` siempre está presente y nunca contiene null. También se puede consultar el esquema. Los campos de introspección `__schema` y `__type` permiten preguntar al servicio qué ofrece, y sobre ello se construyen herramientas de desarrollo y bibliotecas cliente.\n\nHay tres clases de operación. Una consulta es, en palabras de la especificación, «una recuperación de solo lectura»; una mutación es una escritura seguida de una recuperación; y una suscripción es una petición de larga duración que entrega datos ante una secuencia de sucesos a lo largo del tiempo. En el servidor, una función, normalmente llamada resolver, produce el valor de cada campo. El servicio valida primero la operación frente al esquema y solo después llama a los resolvers de los campos seleccionados. Los campos de nivel superior de una mutación se ejecutan uno tras otro, no en paralelo: dos escrituras de la misma petición no pueden entrar en una condición de carrera entre sí.\n\nLa especificación no impone transporte ni formato de serialización. HTTP es lo más habitual: la API se sirve en una sola URL, normalmente acabada en `/graphql`, y responde en JSON, el formato más común. El cliente envía un POST cuyo cuerpo JSON contiene el texto de la consulta en `query` y, cuando hacen falta, sus `variables`. El servidor también puede aceptar GET para consultas, pero una mutación siempre debe ser POST. La respuesta contiene el resultado en `data` y los problemas en `errors`. Las indicaciones de la GraphQL Foundation siguen una especificación GraphQL-over-HTTP que aún es un borrador.\n\n## Por qué importa\n\nEn la mayoría de las API HTTP, el servidor decide qué devuelve cada punto de acceso. Una pantalla que necesita el estado de un pedido y el nombre de su cliente recibe el pedido y el cliente completos, más de lo solicitado, o debe hacer una petición por recurso y unir las respuestas. La especificación llama a esos problemas over-fetching y under-fetching. GraphQL invierte la relación: el cliente pide campos individuales y recibe exactamente esos, ninguno más. Una petición también puede seguir relaciones, del pedido a sus líneas y al cliente, porque tiene la forma de los datos que recibirá.\n\nEl sistema de tipos aporta dos ventajas. Cada operación se valida frente al esquema antes de ejecutar ningún resolver: un campo mal escrito o un argumento de tipo incorrecto provoca el rechazo de toda la operación antes de ejecutar nada. Las herramientas pueden detectar esos mismos errores mientras se escribe el código. Además, como el cliente solo recibe los campos que eligió, añadir un campo no exige cambios en los clientes existentes. Así resulta práctico evolucionar una API sin números de versión: aparece un campo nuevo junto al antiguo, se marca este con `@deprecated` y un motivo, sigue siendo válido para no romper clientes y se elimina cuando ya no lo usa ninguno.\n\nLos costes son reales y proceden sobre todo de salir de los mecanismos propios de HTTP. Las entidades ya no se identifican mediante URL y todo va a una dirección, normalmente por POST, mientras que son las peticiones GET las que suelen considerarse cacheables de forma predeterminada. Hay que reconstruir deliberadamente la caché que una API REST obtiene de los intermediarios sin esfuerzo. El código de estado ya no cuenta toda la historia: una respuesta con datos y errores sigue siendo un éxito en HTTP. El cliente compone peticiones que el servidor nunca ha visto; una sola puede exigir mucho trabajo y es el servicio quien debe protegerse, no GraphQL quien lo hace por él. Los resolvers por campo son fáciles de escribir, pero una implementación ingenua hace demasiadas llamadas a la base subyacente.\n\n## Cómo se aplica en la práctica\n\nUna pequeña parte de un esquema de pedidos, cada uno con líneas y cliente:\n\n```graphql\ntype Query {\n  order(id: ID!): Order\n}\n\ntype Order {\n  id: ID!\n  status: String!\n  items: [LineItem!]!\n  customer: Customer\n}\n\ntype LineItem {\n  name: String!\n  quantity: Int!\n}\n\ntype Customer {\n  name: String!\n}\n```\n\nUna pantalla que muestra el estado, las líneas y el nombre del cliente envía esta operación a `/graphql` en el cuerpo de un POST, con `{\"id\": \"7421\"}` como variables:\n\n```graphql\nquery OrderSummary($id: ID!) {\n  order(id: $id) {\n    status\n    items {\n      name\n      quantity\n    }\n    customer {\n      name\n    }\n  }\n}\n```\n\nSupongamos que se resuelven el pedido y sus líneas, pero el servicio de `customer` está caído. La respuesta aún contiene todo lo que se pudo producir. El campo fallido vuelve como null y una entrada de `errors` explica qué falló, dónde ocurrió en el documento —la línea 8, columna 5 es `customer`— y qué ruta de la respuesta afecta:\n\n```json\n{\n  \"data\": {\n    \"order\": {\n      \"status\": \"open\",\n      \"items\": [{ \"name\": \"notebook\", \"quantity\": 2 }],\n      \"customer\": null\n    }\n  },\n  \"errors\": [\n    {\n      \"message\": \"Customer service unavailable\",\n      \"locations\": [{ \"line\": 8, \"column\": 5 }],\n      \"path\": [\"order\", \"customer\"]\n    }\n  ]\n}\n```\n\nComo `customer` admite null, el daño se limita a ese campo. Si fuera `Customer!`, el error se propagaría al padre y todo el pedido volvería como null. Además, como `data` no es null, el servidor responde con un estado 2xx pese al error: HTTP no tiene código para el éxito parcial. Un cliente que solo mire el código tratará esa respuesta como completa.\n\nEl diseño contrario, donde el servidor decide la forma de cada respuesta, es el que construyó un proyecto del portfolio de este sitio. En su [paso directo de JSON de Postgres a la API](/es/portfolio/designed-a-json-passthrough-from-postgres-to-api/), las funciones PostgreSQL ensamblan la respuesta completa como JSON y el manejador Go la reenvía intacta. Cambiar lo que devuelve una función cambia lo que recibe el cliente sin editar una línea del manejador. Allí el frontend depende directamente de la forma que le da la base. En GraphQL el cliente nombra los campos y el servidor debe poder resolver cualquier combinación permitida por el esquema.\n\n## Dónde surgen los problemas\n\n**Un campo, mil llamadas a la base.** Los resolvers son funciones pequeñas, una por campo, y un servicio ingenuo los llama objeto a objeto. Una lista de pedidos con el cliente de cada uno cuesta una llamada a la base para la lista y otra por pedido. La GraphQL Foundation lo llama problema N+1 y señala el procesamiento por lotes: se reúnen las peticiones de datos realizadas en un intervalo corto y se envían a la base como una sola petición, con una herramienta como DataLoader de Facebook.\n\n**Una petición lo pide todo.** Como el cliente escribe la operación, un documento puede anidar amigos de amigos a muchos niveles, repetir un campo costoso bajo cien alias o agrupar muchas operaciones en una petición. Todos son válidos en GraphQL y pueden mantener ocupado el servidor. Las defensas corresponden al servicio: paginar campos de lista, rechazar antes de ejecutar las operaciones que excedan una profundidad o amplitud máxima, limitar alias y tamaño de lote y, para afinar más, asignar pesos a los campos y rechazar operaciones cuyo coste estimado supere el presupuesto. Es el análisis de complejidad de consultas, para el que la propia especificación no da reglas. Una API que solo atiende a sus propios clientes puede ir más lejos con documentos de confianza: únicamente se permiten las operaciones almacenadas de antemano y buscadas por hash.\n\n**200 OK oculta el fallo.** Una respuesta con errores puede seguir siendo 2xx, como en el ejemplo. Con el tipo de medio antiguo `application/json`, las indicaciones van más allá: se recomienda 2xx incluso si una petición válida no puede ejecutarse, y algunos servidores antiguos devuelven 2xx también ante errores de validación. El cliente y su monitorización deben leer `errors`, no solo el estado. El tipo más reciente `application/graphql-response+json` vuelve a dar significado al estado: una petición válida que no puede ejecutarse recibe entonces 4xx o 5xx. Los clientes deberían pedirlo en la cabecera `Accept`.\n\n**La caché deja de funcionar.** Cada operación es un POST a la misma URL: las cachés entre cliente y servidor, incluida una CDN, ven una dirección y un método cuyas respuestas no almacenan de forma predeterminada. Enviar consultas mediante GET ayuda, pero un documento largo puede exceder la longitud de URL admitida por navegadores y CDN. Las consultas persistidas resuelven ambos problemas: el cliente envía un hash y el servidor busca el documento completo antes de validarlo y ejecutarlo. Cuando se almacenan respuestas en caché HTTP, las sensibles deben guardarse en una caché privada o no guardarse en caché.\n\n**Desaparece un campo.** Los clientes eligen campos individualmente: eliminar o renombrar uno rompe todos los que aún lo seleccionan, y de forma brusca. Una operación que nombra un campo desconocido se rechaza por completo durante la validación, sin devolver datos. La especificación mantiene válidos los campos obsoletos precisamente para no romper clientes existentes. Añada primero el sustituto, marque el antiguo con `@deprecated` y un motivo que apunte al nuevo y elimínelo solo cuando ya nada lo seleccione.\n\n## Lecturas adicionales\n\n- [Versiones de la especificación GraphQL](https://spec.graphql.org/) — Todas las ediciones, desde julio de 2015 a septiembre de 2025, y el borrador de trabajo: lenguaje, tipos, validación, ejecución y errores.\n- [Servicio mediante HTTP](https://graphql.org/learn/serving-over-http/) — El punto de acceso único, POST y GET, los dos tipos de medio de respuesta y las reglas de estado de cada uno.\n- [Rendimiento](https://graphql.org/learn/performance/) — GET para consultas, consultas persistidas, problema N+1 y procesamiento por lotes.\n- [Seguridad](https://graphql.org/learn/security/) — Documentos de confianza, límites de profundidad, amplitud y lotes, análisis de complejidad, introspección y nivel de detalle de los errores en producción.\n\n\u003chttps://engineer.company/es/glossary/graphql/\u003e\n","date_modified":"2026-11-09T21:50:25Z","description":"Cómo GraphQL deja elegir campos al cliente, qué implica una sola URL para la caché y los códigos de estado, y cinco fallos habituales de estas API.","formats":{"gemtext":"https://engineer.company/es/glossary/graphql/index.gmi","gopher":"https://engineer.company/es/glossary/graphql/gophermap","html":"https://engineer.company/es/glossary/graphql/","json":"https://engineer.company/es/glossary/graphql/index.json","markdown":"https://engineer.company/es/glossary/graphql/index.md","pdf":"https://engineer.company/es/glossary/graphql/index.pdf"},"kind":"page","language":"es","title":"¿Qué es GraphQL?","url":"https://engineer.company/es/glossary/graphql/","version":1}