¿Qué es GraphQL?
GraphQL es un lenguaje de consulta para APIs creado en Facebook y abierto en 2015. La
diferencia con REST es estructural: en lugar de múltiples endpoints (uno por recurso), hay
un solo endpoint /graphql que recibe queries y devuelve exactamente los campos
pedidos. El cliente decide qué necesita; el servidor expone qué es posible.
Anatomía de una query
Una query empieza con la palabra query (opcional para queries simples), un
nombre, variables tipadas ($id: ID!) y el cuerpo: campos del tipo raíz, sus
sub-campos y argumentos. Los corchetes { } definen qué campos traer; sin
ellos no se traen.
Mutations: cuando algo cambia
Las mutations modifican estado. Sintaxis casi igual a queries pero con la palabra
mutation. Convención: nombres en imperativo (createUser,
deleteOrder) y devolver el objeto modificado para que el cliente actualice
cache sin un refetch.
Subscriptions: tiempo real
Las subscriptions usan WebSockets. Útiles para feeds en vivo, notificaciones, presencia.
El cliente abre una conexión y recibe eventos cuando el servidor publica. Hoy lo más usado
es el protocolo graphql-ws.
Variables
Hardcodear valores en la query rompe el cache y abre la puerta a inyecciones. Lo correcto
es declarar variables: query Get($id: ID!) { user(id: $id) { ... } } y mandar
variables en el JSON del request. El servidor las parsea por separado.
Fragments
Si los mismos campos aparecen en varias queries, definí un fragment:
fragment UserFields on User { id name email } y usalo con
...UserFields. Apollo y Relay aprovechan fragments para colocar los campos
cerca del componente que los usa.
Aliases y directivas
Si pedís el mismo campo dos veces con argumentos distintos, usá un alias:
active: users(status: ACTIVE) { id }. Las directivas
@include(if: $cond) y @skip(if: $cond) permiten condicionar
campos según variables.
El problema N+1
Si en una lista pedís un sub-campo (autor de cada post), un resolver naive hace una query por post. Con DataLoader (de Facebook) agrupás todos los IDs en una sola query y devolvés un array. Es la herramienta clave para que GraphQL no destruya tu base de datos en producción.