¿Cómo puedo usar OpenAPI con GraphQL? #

Las API (Application Programming Interfaces, interfaces de programación de aplicaciones) son fundamentales para el desarrollo de software moderno, ya que permiten que distintas aplicaciones interactúen entre sí. OpenAPI y GraphQL son dos especificaciones populares para construir API. OpenAPI se utiliza tradicionalmente para API RESTful, mientras que GraphQL es un lenguaje de consultas para API. Integrarlos puede aportar numerosos beneficios, como mayor flexibilidad, mejor documentación y capacidades de consulta más eficientes. Este artículo explora cómo puedes usar OpenAPI con GraphQL.

Comprender OpenAPI y GraphQL #

Antes de profundizar en cómo integrar OpenAPI con GraphQL, veamos qué aporta cada una de estas tecnologías.

OpenAPI #

La OpenAPI Specification (OAS) es un estándar para definir API RESTful. OpenAPI utiliza un formato YAML o JSON para describir los endpoints de la API, los parámetros de las solicitudes, las respuestas y otros metadatos. Es una herramienta potente para:

• Documentación: la documentación detallada de la API se genera automáticamente a partir del archivo OpenAPI.
• Validación: las herramientas pueden validar automáticamente solicitudes y respuestas.
• Generación de código: los stubs de cliente y de servidor pueden generarse automáticamente en distintos lenguajes.

GraphQL #

GraphQL es un lenguaje de consultas y un entorno de ejecución para ejecutar consultas contra tu API. Desarrollado por Facebook, GraphQL ofrece una forma más flexible y eficiente de interactuar con las API al:

• Permitir que los clientes especifiquen sus necesidades de datos: los clientes pueden solicitar campos concretos, lo que reduce la obtención excesiva o insuficiente de datos.
• Usar un único endpoint: a diferencia de REST, que tiene varios endpoints para distintos recursos, una API GraphQL atiende las solicitudes a través de un único endpoint.
• Ofrecer introspección: GraphQL incluye capacidades de introspección integradas que permiten a los clientes consultar el esquema para conocer los tipos y campos disponibles.

Beneficios de combinar OpenAPI con GraphQL #

Combinar OpenAPI y GraphQL permite aprovechar las fortalezas de ambos y mitigar sus debilidades. Estos son algunos de los beneficios:

• Documentación completa y tipado fuerte: OpenAPI ofrece documentación exhaustiva que puede complementar el esquema autodocumentado de GraphQL.
• Mayor flexibilidad: la capacidad de GraphQL para obtener únicamente los datos necesarios puede ayudar a optimizar el rendimiento.
• Reutilización de código: pueden desarrollarse herramientas que conviertan especificaciones OpenAPI en esquemas GraphQL, lo que fomenta la reutilización de código y facilita el mantenimiento.

Métodos para integrar OpenAPI con GraphQL #

Existen varios métodos para integrar OpenAPI con GraphQL, cada uno con sus propias ventajas y casos de uso.

1. Uso de un GraphQL API Gateway #

Un GraphQL API Gateway puede actuar como una fachada que agrega varios servicios RESTful detrás de un único endpoint GraphQL. Herramientas como Apollo Gateway, Hasura y Prisma te ayudan a unir servicios definidos con OpenAPI.

Pasos:

1. Crear la especificación OpenAPI: comienza creando una especificación OpenAPI para tu API RESTful.
2. Generar el esquema GraphQL: usa herramientas como Apollo Gateway o swagger-to-graphql para convertir la especificación OpenAPI en un esquema GraphQL.
3. Configurar los resolvers: configura el servidor GraphQL para que resuelva las consultas GraphQL hacia los endpoints OpenAPI correspondientes.
4. Desplegar el gateway: despliega tu GraphQL API Gateway.

Código de ejemplo (Apollo Gateway):

const { ApolloServer } = require('apollo-server');
const { ApolloGateway } = require('@apollo/gateway');

const gateway = new ApolloGateway({
  serviceList: [
    { name: 'service1', url: 'http://service1/graphql' },
    { name: 'service2', url: 'http://service2/graphql' },
  ],
});

const server = new ApolloServer({ gateway });

server.listen().then(({ url }) => {
  console.log(`🚀 Server ready at ${url}`);
});

2. Middleware para la traducción de API #

Otro enfoque consiste en usar un middleware que traduzca entre OpenAPI y GraphQL. Este middleware puede interceptar las consultas GraphQL entrantes y traducirlas a las solicitudes OpenAPI correspondientes.

Pasos:

1. Preparar la especificación OpenAPI: define tu API con OpenAPI.
2. Elegir una herramienta de middleware: usa un middleware como graphql-mesh.
3. Configurar el middleware: configura el middleware para convertir las solicitudes y las respuestas.

Código de ejemplo (GraphQL Mesh):

// mesh.config.yaml
sources:
  - name: ExampleAPI
    handler:
      openapi:
        source: ./path-to-your-openapi-spec.yaml

const { getMesh } = require('@graphql-mesh/runtime');
const { findAndParseConfig } = require('@graphql-mesh/config');

async function main() {
  const config = await findAndParseConfig();
  const { schema, contextBuilder } = await getMesh(config);

  const server = new ApolloServer({ schema, contextBuilder });

  server.listen().then(({ url }) => {
    console.log(`🚀 GraphQL Mesh ready at ${url}`);
  });
}

main();

3. Definición manual del esquema y configuración de los resolvers #

En algunos casos, puede que prefieras el control que ofrece escribir manualmente tu esquema GraphQL y tus resolvers, usando la documentación OpenAPI existente como referencia.

Pasos:

1. Consultar la especificación OpenAPI: usa la especificación OpenAPI para definir el esquema GraphQL.
2. Escribir el esquema: define tu esquema GraphQL manualmente.
3. Implementar los resolvers: implementa los resolvers para gestionar las consultas y las mutaciones.

Código de ejemplo:

# schema.graphql
type Query {
  getUser(id: ID!): User
}

type User {
  id: ID!
  name: String
  email: String
}

// resolvers.js
const fetch = require('node-fetch');

const resolvers = {
  Query: {
    getUser: async (_, { id }) => {
      const response = await fetch(`http://openapi-service/users/${id}`);
      return response.json();
    },
  },
};

module.exports = resolvers;

// server.js
const { ApolloServer, gql } = require('apollo-server');
const resolvers = require('./resolvers');
const fs = require('fs');

const schema = fs.readFileSync('./schema.graphql', 'utf8');

const server = new ApolloServer({
  typeDefs: gql(schema),
  resolvers,
});

server.listen().then(({ url }) => {
  console.log(`🚀 Server ready at ${url}`);
});

Herramientas y recursos #

Estas son algunas herramientas y recursos que te ayudarán a empezar a combinar OpenAPI y GraphQL:

1. Apollo Federation y Apollo Gateway: para configurar un gateway GraphQL que pueda agregar varios servicios.
2. Hasura: ofrece API GraphQL instantáneas sobre endpoints REST existentes.
3. graphql-mesh: admite una gran variedad de fuentes de datos, incluida OpenAPI, y las unifica en un único endpoint GraphQL.
4. swagger-to-graphql: convierte una especificación OpenAPI/Swagger en un esquema GraphQL.

Conclusión #

Usar OpenAPI con GraphQL es una estrategia flexible que combina las fortalezas de ambas tecnologías. Ya sea que utilices un GraphQL API Gateway, un middleware para la traducción de API o definas manualmente tus esquemas y resolvers, la integración puede mejorar significativamente las capacidades de tu infraestructura de API.

Al aprovechar herramientas como Apollo Gateway, Hasura y graphql-mesh, puedes tender un puente eficiente entre los servicios RESTful de OpenAPI y las potentes capacidades de consulta de GraphQL. Esto no solo mejora la flexibilidad y la eficiencia de tus interacciones con la API, sino que también agiliza el proceso de desarrollo y mantenimiento. Si quieres empezar, hay numerosas bibliotecas y frameworks disponibles para ayudarte a integrar OpenAPI con GraphQL sin complicaciones.

Para obtener más información sobre estos enfoques, puedes consultar la documentación de Apollo Federation, la guía de Hasura sobre cómo conectar endpoints REST y la documentación de graphql-mesh.

Última actualización: 21 de mayo de 2024.