¿Qué es GraphQL?
GraphQL es una forma alternativa de comunicarse con APIs que es altamente adecuada para estructuras de datos complejas y la construcción de interfaces sobre ellas. A diferencia de tratar los datos como piezas separadas y autónomas, GraphQL muestra cómo las piezas de datos se conectan y se relacionan entre sí, facilitando la solicitud y recepción de información.
Piensa en GraphQL como un lenguaje de consulta que te permite hablar con la API como si estuvieras hablando directamente con la base de datos. Usar GraphQL te permite acercarte lo más posible a la base de datos, permitiéndote elegir qué datos deseas y cómo los obtienes, proporcionando un enorme beneficio en rendimiento.
GraphQL fue creado por Facebook para resolver el problema de escalar con estructuras de datos complejas. Como resultado de su exitosa adopción, cada vez más empresas han comenzado a darse cuenta de los beneficios de usar GraphQL para sus APIs.
¿Ya conoces REST? GraphQL te resultará familiar.
Las APIs de GraphQL son más fáciles de trabajar de lo que piensas. Si estás acostumbrado a trabajar con APIs REST, aquí te mostramos cómo los conceptos básicos de REST se traducen en GraphQL.
| Característica | REST | GraphQL |
|---|---|---|
| Endpoint | Las solicitudes se realizan a múltiples endpoints para diferentes acciones | Todas las solicitudes se realizan a un solo endpoint (por ejemplo, /graphql) |
| Recuperación de datos | Usa métodos GET en endpoints específicos para recuperar datos | Usa consultas para solicitar exactamente los datos necesarios, reduciendo la sobrecarga o la subcarga de datos |
| Modificación de datos/acciones | Usa métodos HTTP como POST, PUT, PATCH o DELETE para modificar o procesar datos. | Usa mutaciones para realizar operaciones (por ejemplo, crear partes, calcular costos de importación) |
| Formato de respuesta | Los formatos de respuesta fijos devuelven todos los campos predefinidos, independientemente de si son necesarios | Las respuestas flexibles permiten especificar exactamente los campos a incluir, reduciendo la transferencia de datos innecesaria (Si esta flexibilidad te parece complicada, simplemente usa los ejemplos de consultas preescritas en nuestra documentación para una experiencia similar a REST) |
| Conexión de datos | A menudo se requieren múltiples solicitudes para obtener datos relacionados | Las consultas anidadas permiten recuperar datos relacionados en una sola solicitud (por ejemplo, detalles de la parte y artículos de envío juntos). Los usuarios también pueden construir flujos de trabajo para gestionar múltiples mutaciones dentro de una sola solicitud de GraphQL, reduciendo la complejidad y mejorando la eficiencia |
Ventajas de GraphQL
Respuestas más rápidas
GraphQL proporciona respuestas más rápidas a través de la recuperación precisa de datos, el uso de un solo endpoint y capacidades mejoradas para el agrupamiento y la caché.
Recuperación precisa de datos
Un desafío común con REST es la sobrecarga o la subcarga de datos: obtener demasiada información innecesaria o no suficiente de lo que se necesita de una sola vez. GraphQL elimina esto al permitir solicitudes de exactamente lo que se necesita, ni más ni menos. Esta especificidad no solo mejora el rendimiento, sino que también simplifica el proceso para aquellos que interactúan con la API, haciendo que el sistema sea más eficiente y fácil de usar.
Ejemplos de cómo esto es útil:
- Esto permite a los desarrolladores frontend obtener exactamente los datos que necesitan para sus componentes de UI, reduciendo el número de viajes al servidor y mejorando el rendimiento.
- Imagina que deseas obtener una clasificación de código HS, cartonización, calificación de envío y una cotización de landed cost sobre artículos en un checkout. Si estás integrado a través de la API de GraphQL, puedes hacer una sola llamada con los flujos de trabajo necesarios para obtener todo lo que necesitas (y nada de lo que no necesitas) en una sola respuesta. En contraste, con las APIs REST, tendrías que llamar primero a la Classify REST API, luego llamar a la Rating REST API por separado después, y finalmente conectar esa clasificación y calificación de envío en tu tercera llamada a la Landed Cost REST API. Todas estas APIs REST devolverían cada pieza de información que pueden, lo que te obligaría a analizar la respuesta para encontrar los datos que necesitas. Este ahorro en velocidad tiene un impacto en la devolución rápida de un landed cost, antes de que el comprador se vaya.
Un solo endpoint
Las APIs de GraphQL suelen tener un solo endpoint, a diferencia de las APIs REST que a menudo tienen múltiples endpoints para diferentes recursos y acciones. Esto hace que sea más simple gestionar y entender la API.
Agrupamiento y caché
La capacidad de GraphQL para agrupar consultas y su soporte para estrategias de caché conducen a mejoras significativas en el rendimiento. Estas características reducen la carga en redes y servidores, lo que se traduce en interacciones más rápidas y confiables para los usuarios.
Esquemas bien definidos
Las APIs de GraphQL se basan en un esquema fuertemente tipado. Este esquema define la estructura de los datos disponibles y las operaciones que se pueden realizar. Esto proporciona claridad sobre qué datos están disponibles y cómo acceder a ellos, lo que puede mejorar la productividad del desarrollador y reducir errores. Por ejemplo, los equipos frontend pueden explorar el gráfico para obtener exactamente lo que necesitan en lugar de esperar un nuevo endpoint REST.
Capacidad de mejorar sin romper clientes existentes
Agregar nuevas características o modificar las existentes en GraphQL no interrumpe las integraciones actuales, gracias a su estructura de consulta flexible. Esta capacidad asegura que se puedan realizar mejoras sin romper la compatibilidad con los clientes existentes.
Documentación actualizada
Gracias a la función de introspección de GraphQL, la documentación se genera y actualiza automáticamente con cada cambio. Esto asegura que toda la información proporcionada a los desarrolladores esté actualizada, reduciendo problemas de integración y tickets de soporte relacionados con documentación desactualizada, un desafío comúnmente enfrentado con la documentación de APIs REST.
Revisa nuestra documentación de GraphQL y nuestra documentación de REST para ver la diferencia.
Una analogía
Imagina que estás en un restaurante con un menú que te permite pedir platos exactamente como te gustan, en comparación con otro restaurante donde solo puedes elegir entre comidas preestablecidas. GraphQL es como el primer restaurante:
- Obtén exactamente lo que quieres: Con GraphQL, puedes pedir exactamente los datos que necesitas, ni más ni menos. Imagina que solo quieres el nombre y el precio de un plato, no toda la lista de ingredientes. Con las API REST, tienes que obtener todos los detalles del plato y ignorar las partes que no necesitas.
- Compón un plato personalizado: Nuestras API de GraphQL se pueden combinar fácilmente para crear soluciones más personalizadas, similar a un restaurante estilo buffet donde puedes crear un plato único exactamente como lo necesitas, utilizando ingredientes que ya tienen. En contraste, una API REST es como una panadería con productos prehechos empaquetados en cestas: solo puedes pedir lo que ya ha sido creado y no puedes elegir llevar a casa solo la pieza que deseas.
- Menos espera: Dado que puedes obtener toda la información que necesitas en una sola solicitud, es como pedirle a tu camarero que traiga tu aperitivo, plato principal y postre todo a la vez, en lugar de esperar entre los platos. La mayoría de las API REST requieren que envíes múltiples solicitudes para obtener diferentes piezas de información.
- Fácil de cambiar pedidos: Si las necesidades de datos de tu aplicación cambian, GraphQL facilita el ajuste. Solo cambias la consulta por lo que necesitas. Con REST, podrías tener que esperar a que la cocina (backend) cree una nueva comida (endpoint) para el menú, lo que lleva más tiempo.
GraphQL ofrece más flexibilidad, eficiencia y simplicidad para obtener datos que las API REST, especialmente a medida que tus necesidades cambian o crecen.
Cómo Zonos utiliza GraphQL
Mientras modernizábamos nuestra plataforma en los últimos años, Zonos ha tomado la decisión de construir nuevas funcionalidades utilizando GraphQL para nuestra API en lugar de REST. Decidimos hacer esto porque nuestros datos son complejos e interconectados, muy parecido a los datos que llevaron a Facebook a crear GraphQL. Esta complejidad hace que sea un desafío construir API REST escalables porque las formas en que los desarrolladores necesitan obtener y usar los datos varían drásticamente entre implementaciones, y REST no es flexible.
GraphQL resuelve este problema de manera ordenada al permitir que los desarrolladores que implementan nuestra API elijan exactamente qué datos quieren y cómo los obtienen. Esto les permite integrarlo en sus flujos de trabajo sin que Zonos necesite hacer trabajo personalizado (mientras esperan) para cada situación.
El resultado combinado de usar GraphQL y las modernizaciones en nuestra plataforma ha hecho que nuestra API sea más eficiente, ha acelerado la integración de Zonos en tus sistemas y ha hecho posible que Zonos entregue nuevas características más rápidamente.
Mejores características
Zonos desarrolla continuamente nuevas características, y GraphQL es el primero (y generalmente el único) en recibir estas actualizaciones. En contraste, nuestras API REST se consideran obsoletas y no pueden acceder a muchas de nuestras nuevas características.
Ejemplos de características limitadas a GraphQL:
- Inclusive pricing
- API de etiquetas
- Nuevos Checkout y Hello
- Tamaños de cajas en la respuesta de la API
- Informes del panel de control
- Capacidad para solicitar una cotización DDP si es posible, pero aún devolver una cotización DDU si DDP no está disponible para ese país con ese nivel de servicio
- Desglose detallado de derechos, impuestos y tarifas (información a nivel de artículo, tarifas específicas): el panel de control está impulsado por GraphQL y muestra estos datos para todas las tiendas, pero la respuesta de la API REST no incluye este nivel de detalle
- Modo de prueba (próximamente)
Por qué GraphQL
Descubre por qué recomendamos integrar a través de GraphQL en lugar de REST.
En Zonos, ofrecemos dos tipos principales de APIs para integración: GraphQL y REST. Aunque las APIs REST han existido por más tiempo y pueden ser más familiares para muchos, hemos migrado a GraphQL para permitir más flexibilidad e innovación más rápida. Aunque ambos aún son compatibles, esta guía explica por qué GraphQL no solo es el futuro de nuestras integraciones, sino también el futuro de las integraciones en general y una herramienta más poderosa para satisfacer tus necesidades hoy.