Many organizations have valuable APIs that were not designed as GraphQL services. A product may expose OpenAPI-described REST endpoints, another service may publish gRPC, a legacy system may expose SOAP, and a newer team may already run GraphQL. GraphQL Mesh is a gateway pattern for making those heterogeneous sources available through a unified GraphQL schema without rewriting every backend first.
The core technique is runtime schema translation. Source handlers load remote or local service descriptions, convert them into GraphQL types and fields, and then a composition layer applies transforms, type merging, schema extensions, caching, authorization, and gateway policies. The resulting API can be executed locally in-process or served as a network gateway in front of existing services.
This is different from ordinary OpenAPI code generation. Codegen produces SDKs or server stubs for one API contract. A mesh gateway builds an executable GraphQL facade across several contracts, preserving the original systems while giving clients GraphQL selection sets, typed composition, and one endpoint for cross-service queries.
A source handler knows how to load one kind of upstream system. GraphQL Mesh documents handlers for OpenAPI, GraphQL, gRPC/Protobuf, JSON Schema, SOAP, OData, Thrift, and several database-shaped sources. Each handler turns its source into a GraphQL subgraph that can participate in the combined schema.
Generated GraphQL schemas often need cleanup before they are useful. Transforms can rename fields, prefix names, filter generated fields, hoist nested fields, prune unused schema parts, or apply federation-related metadata. These transforms are the adaptation layer between backend-shaped contracts and client-friendly GraphQL.
When two services describe related entities, the mesh can connect them by key fields or by custom schema extensions. Type merging links separate query fields into one object graph, while additional type definitions and resolvers add fields that do not exist directly in any one source.
The mesh should protect clients from backend inconsistency without pretending the inconsistency disappeared. Keep translation, naming repair, authentication forwarding, and cross-source joins in the gateway layer so upstream services can evolve on their own schedules.
The OpenAPI handler can load a local or remote OpenAPI/Swagger schema. Mesh maps operations into GraphQL fields, uses operation names where possible, and classifies GET operations as queries while non-GET operations normally become mutations. Explicit configuration can override that classification when the HTTP method does not match the semantic operation.
import { defineConfig } from "@graphql-mesh/compose-cli";
import { loadOpenAPISubgraph } from "@omnigraph/openapi";
export const composeConfig = defineConfig({
subgraphs: [
{
sourceHandler: loadOpenAPISubgraph("Catalog", {
source: "https://example.com/openapi.yaml",
selectQueryOrMutationField: [
{
fieldName: "preview_invoice",
type: "Query"
}
]
})
}
]
});OpenAPI operation IDs, paths, and schema names do not always satisfy GraphQL naming rules. Mesh adjusts invalid characters, prefixes names that begin with digits, and derives path-based names for unnamed shapes. Teams should still treat source naming as an API design concern because generated field names become part of the client-facing contract.
After handlers produce subgraphs, the gateway composes them into one executable schema. Requests arrive as GraphQL documents, the executor resolves selected fields through the relevant upstream handlers, and transforms or custom resolvers adapt request and response shapes at the boundary.
A team can expose existing REST or gRPC services through GraphQL before committing to a rewrite. Clients get GraphQL selection sets and typed composition, while backend teams keep their current contracts. This is useful when frontend needs span several legacy APIs but the organization cannot stop feature work for a wholesale migration.
Platform teams often need to combine vendor APIs, internal REST services, and GraphQL-native domains. A mesh gateway can hide protocol differences, enforce consistent authentication forwarding, and expose one shape to application developers while keeping ownership of each upstream service intact.
The OpenAPI handler can represent OpenAPI callbacks as GraphQL subscriptions when a webhook endpoint and PubSub topic are configured. This gives event-driven REST integrations a GraphQL subscription surface without forcing the upstream provider to implement GraphQL transport.
Define each upstream source with a stable name, source location, authentication behavior, and only the transforms it needs. Avoid global transforms that accidentally rewrite unrelated services; source-level transforms make ownership and debugging much clearer.
export const composeConfig = defineConfig({
subgraphs: [
{
sourceHandler: loadOpenAPISubgraph("Billing", {
source: "./schemas/billing.openapi.yaml"
}),
transforms: [
createRenameTransform({
renames: [
{
from: { type: "Query", field: "get_invoice_by_id" },
to: { type: "Query", field: "invoice" }
}
]
})
]
}
]
});When two sources describe the same entity, merge on stable identifiers rather than display names or mutable fields. For example, an account object from a billing API and an account object from a CRM API should join on an immutable account ID. The gateway can batch key lookups so nested GraphQL selections do not become one upstream request per object.
Schema extensions are powerful because they can attach custom resolvers to generated types, but they also create gateway-owned business logic. Use them for cross-source joins, calculated fields, and compatibility adapters. Keep domain decisions that belong to one service inside that service.