Descubra por qué recomendamos integrar mediante GraphQL en lugar de REST.
En Zonos ofrecemos dos tipos principales de API para la integración: GraphQL y REST. Aunque las API REST llevan más tiempo en el mercado y pueden resultar más familiares para muchos, hemos adoptado GraphQL para permitir mayor flexibilidad e innovación más rápida. Aunque ambas siguen siendo 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 potente para satisfacer sus necesidades actuales.
GraphQL es una forma alternativa de comunicarse con las API, muy adecuada para estructuras de datos complejas y para construir interfaces sobre ellas. A diferencia de tratar los datos como piezas separadas e independientes, GraphQL muestra cómo se conectan y relacionan entre sí, lo que facilita solicitar y recibir información.
Piense en GraphQL como un lenguaje de consulta que le permite hablar con la API como si hablara directamente con la base de datos. Usar GraphQL le permite acercarse lo máximo posible a la base de datos, eligiendo qué datos quiere y cómo obtenerlos, lo que supone una enorme ventaja de rendimiento.
GraphQL fue creado por Facebook para resolver el problema de escalar con estructuras de datos complejas. Tras su adopción exitosa, cada vez más empresas han empezado a reconocer los beneficios de usar GraphQL para sus API.
¿Ya conoce REST? GraphQL le resultará familiar.
Las API GraphQL son más fáciles de usar de lo que pueda pensar. Si está acostumbrado a trabajar con API REST, así se traducen los conceptos principales de REST a GraphQL.
Característica↕
REST↕
GraphQL↕
Endpoint
Las solicitudes se realizan a varios endpoints para distintas acciones
Todas las solicitudes se realizan a un único endpoint (p. ej., /graphql)
Recuperación de datos
Use métodos GET en endpoints específicos para recuperar datos
Use consultas para solicitar exactamente los datos necesarios, reduciendo la sobre- o subrecuperación
Modificación de datos/acciones
Use métodos HTTP como POST, PUT, PATCH o DELETE para modificar o procesar datos
Use mutaciones para realizar operaciones (p. ej., crear partes, calcular landed costs)
Formato de respuesta
Los formatos de respuesta fijos devuelven todos los campos predefinidos, aunque no se necesiten
Las respuestas flexibles permiten especificar exactamente los campos a incluir, reduciendo la transferencia innecesaria de datos (si esta flexibilidad le parece complicada, use simplemente los ejemplos de consulta de nuestra documentación para una experiencia similar a REST)
Conexión de datos
A menudo se requieren varias solicitudes para obtener datos relacionados
Las consultas anidadas permiten recuperar datos relacionados en una sola solicitud (p. ej., detalles de partes y artículos del envío juntos). Los usuarios también pueden construir flujos de trabajo para gestionar varias mutaciones en una sola solicitud GraphQL, reduciendo la complejidad y mejorando la eficiencia
Ventajas de GraphQL
Respuestas más rápidas
GraphQL ofrece respuestas más rápidas gracias a la recuperación precisa de datos, el uso de un único endpoint y capacidades mejoradas de agrupación y caché.
Un desafío habitual con REST es la sobre- o subrecuperación de datos: obtener demasiada información innecesaria o no suficiente de lo que se necesita de una vez. GraphQL elimina esto al permitir solicitar exactamente lo necesario, ni más ni menos. Esta especificidad no solo mejora el rendimiento, sino que también simplifica el proceso para quienes interactúan con la API, haciendo el sistema más eficiente y fácil de usar.
Ejemplos de utilidad:
Esto permite a los desarrolladores frontend obtener exactamente los datos que necesitan para sus componentes de interfaz, reduciendo el número de idas y vueltas al servidor y mejorando el rendimiento.
Imagine que quiere obtener una clasificación por código HS, cartonization, valoración del envío y cotización de landed cost de los artículos en un checkout. Si está integrado mediante la API GraphQL, puede hacer una sola llamada con los flujos de trabajo necesarios para obtener todo lo que necesita (y nada de lo que no) en una sola respuesta. En cambio, con las API REST, primero tendría que llamar a la Classify REST API, luego a la Rating REST API por separado y, por último, introducir esa clasificación y valoración del envío en su tercera llamada a la Landed Cost REST API. Todas estas API REST devolverían toda la información de la que disponen, obligándole a analizar la respuesta para encontrar los datos que necesita. Este ahorro de velocidad tiene impacto al devolver un landed cost completo rápidamente, antes de que el comprador se vaya.
Las API GraphQL suelen tener un único endpoint, a diferencia de las API REST, que a menudo tienen varios endpoints para distintos recursos y acciones. Esto simplifica la gestión y comprensión de la API.
La capacidad de GraphQL para agrupar consultas y su soporte de estrategias de caché conducen a mejoras significativas de rendimiento. Estas funciones reducen la carga en redes y servidores, lo que se traduce en interacciones más rápidas y fiables para los usuarios.
Esquemas bien definidos
Las API 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 aporta claridad sobre qué datos están disponibles y cómo acceder a ellos, lo que puede mejorar la productividad de los desarrolladores y reducir errores. Por ejemplo, los equipos frontend pueden explorar el grafo para obtener exactamente lo que necesitan en lugar de esperar un nuevo endpoint REST.
Capacidad de mejorar sin romper clientes existentes
Añadir nuevas funciones o modificar las existentes en GraphQL no interrumpe las integraciones actuales, gracias a su estructura de consulta flexible. Esta capacidad garantiza que se puedan hacer 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 garantiza que toda la información proporcionada a los desarrolladores esté actualizada, reduciendo problemas de integración y tickets de soporte relacionados con documentación obsoleta, un desafío habitual con la documentación de API REST.
Imagine que está en un restaurante con un menú que le permite pedir platos exactamente como los desea, frente a otro restaurante donde solo puede elegir menús fijos. GraphQL es como el primer restaurante:
Obtenga exactamente lo que quiere: Con GraphQL, puede solicitar exactamente los datos que necesita, ni más ni menos. Imagine que solo quiere el nombre y el precio de un plato, no toda la lista de ingredientes. Con las API REST, debe obtener todos los detalles del plato e ignorar las partes que no necesita.
Componga un plato a medida: Nuestra API GraphQL puede combinarse fácilmente para crear soluciones más personalizadas, similar a un restaurante tipo buffet donde puede crear un plato único exactamente como lo necesita, con ingredientes que ya tienen. En cambio, una API REST es como una panadería con productos prefabricados empaquetados en cestas: solo puede pedir lo que ya se ha creado y no puede elegir llevarse solo la pieza que desea.
Menos espera: Como puede obtener toda la información que necesita en una sola solicitud, es como pedir al camarero que traiga el aperitivo, el plato principal y el postre a la vez, en lugar de esperar entre platos. La mayoría de las API REST requieren enviar varias solicitudes para obtener distintas piezas de información.
Fácil de cambiar pedidos: Si cambian las necesidades de datos de su aplicación, GraphQL facilita el ajuste. Solo cambia la consulta de lo que necesita. Con REST, podría 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 sus necesidades cambian o crecen.
Al modernizar nuestra plataforma en los últimos años, Zonos ha optado por construir nueva funcionalidad usando GraphQL para nuestra API en lugar de REST. Lo hicimos porque nuestros datos son complejos e interconectados, muy parecidos a los datos que llevaron a Facebook a crear GraphQL. Esta complejidad dificulta construir API REST escalables porque las formas en que los desarrolladores necesitan obtener y usar los datos varían enormemente entre implementaciones, y REST no es flexible.
GraphQL resuelve este problema al permitir que los desarrolladores que implementan nuestra API elijan exactamente qué datos quieren y cómo obtenerlos. Esto les permite integrarlo en sus flujos de trabajo sin que Zonos tenga que hacer trabajo personalizado (mientras esperan) para cada situación.
El resultado combinado de usar GraphQL y las modernizaciones de nuestra plataforma ha hecho nuestra API más eficiente, ha acelerado la integración de Zonos en sus sistemas y ha permitido a Zonos ofrecer nuevas funciones con mayor rapidez.
Mejores funciones
Zonos desarrolla continuamente nuevas funciones, y GraphQL es el primero (y normalmente el único) en recibir estas actualizaciones. En cambio, nuestras API REST se consideran en fin de vida y no pueden acceder a muchas de nuestras funciones nuevas.
Ejemplos de funciones limitadas a GraphQL:
Inclusive Pricing
Labels API
Nuevo Checkout y Hello
Tamaños de caja en la respuesta de la API
Informes de Dashboard
Capacidad de solicitar una cotización DDP si es posible, pero devolver igualmente una cotización DDU si DDP no está disponible para ese país con ese nivel de servicio
Desglose detallado de aranceles, impuestos y tasas (información a nivel de artículo, tasas específicas): Dashboard funciona con GraphQL y muestra estos datos para todas las tiendas, pero la respuesta de la API REST no incluye este nivel de detalle
Por qué GraphQL
Por qué GraphQL
Descubra por qué recomendamos integrar mediante GraphQL en lugar de REST.
En Zonos ofrecemos dos tipos principales de API para la integración: GraphQL y REST. Aunque las API REST llevan más tiempo en el mercado y pueden resultar más familiares para muchos, hemos adoptado GraphQL para permitir mayor flexibilidad e innovación más rápida. Aunque ambas siguen siendo 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 potente para satisfacer sus necesidades actuales.
¿Qué es GraphQL?
GraphQL es una forma alternativa de comunicarse con las API, muy adecuada para estructuras de datos complejas y para construir interfaces sobre ellas. A diferencia de tratar los datos como piezas separadas e independientes, GraphQL muestra cómo se conectan y relacionan entre sí, lo que facilita solicitar y recibir información.
Piense en GraphQL como un lenguaje de consulta que le permite hablar con la API como si hablara directamente con la base de datos. Usar GraphQL le permite acercarse lo máximo posible a la base de datos, eligiendo qué datos quiere y cómo obtenerlos, lo que supone una enorme ventaja de rendimiento.
GraphQL fue creado por Facebook para resolver el problema de escalar con estructuras de datos complejas. Tras su adopción exitosa, cada vez más empresas han empezado a reconocer los beneficios de usar GraphQL para sus API.
¿Ya conoce REST? GraphQL le resultará familiar.
Las API GraphQL son más fáciles de usar de lo que pueda pensar. Si está acostumbrado a trabajar con API REST, así se traducen los conceptos principales de REST a GraphQL.
Ventajas de GraphQL
Respuestas más rápidas
GraphQL ofrece respuestas más rápidas gracias a la recuperación precisa de datos, el uso de un único endpoint y capacidades mejoradas de agrupación y caché.
Recuperación precisa de datos
Un desafío habitual con REST es la sobre- o subrecuperación de datos: obtener demasiada información innecesaria o no suficiente de lo que se necesita de una vez. GraphQL elimina esto al permitir solicitar exactamente lo necesario, ni más ni menos. Esta especificidad no solo mejora el rendimiento, sino que también simplifica el proceso para quienes interactúan con la API, haciendo el sistema más eficiente y fácil de usar.
Ejemplos de utilidad:
Un único endpoint
Las API GraphQL suelen tener un único endpoint, a diferencia de las API REST, que a menudo tienen varios endpoints para distintos recursos y acciones. Esto simplifica la gestión y comprensión de la API.
Agrupación y caché
La capacidad de GraphQL para agrupar consultas y su soporte de estrategias de caché conducen a mejoras significativas de rendimiento. Estas funciones reducen la carga en redes y servidores, lo que se traduce en interacciones más rápidas y fiables para los usuarios.
Esquemas bien definidos
Las API 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 aporta claridad sobre qué datos están disponibles y cómo acceder a ellos, lo que puede mejorar la productividad de los desarrolladores y reducir errores. Por ejemplo, los equipos frontend pueden explorar el grafo para obtener exactamente lo que necesitan en lugar de esperar un nuevo endpoint REST.
Capacidad de mejorar sin romper clientes existentes
Añadir nuevas funciones o modificar las existentes en GraphQL no interrumpe las integraciones actuales, gracias a su estructura de consulta flexible. Esta capacidad garantiza que se puedan hacer 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 garantiza que toda la información proporcionada a los desarrolladores esté actualizada, reduciendo problemas de integración y tickets de soporte relacionados con documentación obsoleta, un desafío habitual con la documentación de API REST.
Revise nuestra documentación de GraphQL y nuestra documentación de REST para ver la diferencia.
Una analogía
Imagine que está en un restaurante con un menú que le permite pedir platos exactamente como los desea, frente a otro restaurante donde solo puede elegir menús fijos. GraphQL es como el primer restaurante:
GraphQL ofrece más flexibilidad, eficiencia y simplicidad para obtener datos que las API REST, especialmente a medida que sus necesidades cambian o crecen.
Cómo Zonos usa GraphQL
Al modernizar nuestra plataforma en los últimos años, Zonos ha optado por construir nueva funcionalidad usando GraphQL para nuestra API en lugar de REST. Lo hicimos porque nuestros datos son complejos e interconectados, muy parecidos a los datos que llevaron a Facebook a crear GraphQL. Esta complejidad dificulta construir API REST escalables porque las formas en que los desarrolladores necesitan obtener y usar los datos varían enormemente entre implementaciones, y REST no es flexible.
GraphQL resuelve este problema al permitir que los desarrolladores que implementan nuestra API elijan exactamente qué datos quieren y cómo obtenerlos. Esto les permite integrarlo en sus flujos de trabajo sin que Zonos tenga que hacer trabajo personalizado (mientras esperan) para cada situación.
El resultado combinado de usar GraphQL y las modernizaciones de nuestra plataforma ha hecho nuestra API más eficiente, ha acelerado la integración de Zonos en sus sistemas y ha permitido a Zonos ofrecer nuevas funciones con mayor rapidez.
Mejores funciones
Zonos desarrolla continuamente nuevas funciones, y GraphQL es el primero (y normalmente el único) en recibir estas actualizaciones. En cambio, nuestras API REST se consideran en fin de vida y no pueden acceder a muchas de nuestras funciones nuevas.
Ejemplos de funciones limitadas a GraphQL:
¿Fue útil esta página?