GraphQL o REST: cómo decidir para una nueva API

Qué es

GraphQL (introducción citada) es un lenguaje de consulta más un runtime del lado del servidor que ejecuta consultas contra un sistema de tipos definido por quien lo implementa; el cliente envía una consulta con la forma de los datos que desea y recibe exactamente esos datos en una sola solicitud, y la API evoluciona añadiendo campos y marcando los antiguos como @deprecated en lugar de mediante versionado. La guía de GraphQL sobre HTTP (citada) describe la forma operativa: un único endpoint, típicamente /graphql; POST para consultas y mutaciones, opcionalmente GET para consultas; y un código de estado 2xx incluso cuando la respuesta contiene errores, porque HTTP no tiene un código de estado para el éxito parcial. Una API de estilo REST, en cambio, expone recursos en URL, usa métodos y códigos de estado para la semántica, y se apoya en la maquinaria de HTTP para la caché y los errores.

Por qué importa

La elección es arquitectónica y difícil de revertir. Cambia cómo funciona la caché, cómo se informan los errores, cómo se calculan los límites de tasa y qué herramientas necesitan los clientes.

Cómo aplicarlo

• Elegir GraphQL cuando muchos clientes distintos (web, móvil, aplicaciones de socios) necesitan porciones diferentes de un grafo de datos conectado, cuando el sobre-consulta (over-fetching) o la ramificación de solicitudes es un problema medido, y cuando se tiene suficiente control sobre los clientes como para distribuir una biblioteca cliente de GraphQL.
• Elegir REST cuando la API está orientada a recursos y es pública, cuando importa la caché HTTP por URL, cuando los integradores son scripts, webhooks y agentes que hablan HTTP simple, o cuando las herramientas de operaciones están construidas alrededor de códigos de estado y rutas.
• Si se elige GraphQL, planificar los controles que describe la guía de seguridad de GraphQL (citada): límites de profundidad, límites de amplitud y de alias, y análisis de complejidad de consultas con presupuestos por cliente; la especificación en sí no los define. Planificar el agrupamiento de resolvers (batching) para el problema N+1.
• Si se elige REST, planificar la selección de campos, el filtrado y los endpoints compuestos para que los clientes no se vean obligados a hacer muchas idas y vueltas.
• Considerar ambos: REST para la superficie pública y las integraciones, GraphQL como backend-for-frontend para las interfaces de usuario propias.

Trampas

Adoptar GraphQL para evitar el diseño de la API; el esquema necesita el mismo cuidado que el diseño de recursos. Exponer GraphQL a llamantes no confiables sin límites de costo. Hacer crecer los parámetros de inclusión anidada de una API REST hasta convertirlos en un lenguaje de consulta sin restricciones y sin la validación de GraphQL. Esperar caché de CDN de GraphQL sobre POST; las consultas GET pueden almacenarse en caché pero chocan con los límites de longitud de URL.