GraphQL Mesh

Omnigraph is a set of libraries and tools designed to generate local GraphQLSchema instances from various non-GraphQL API specifications, including JSON Schema, MySQL, SOAP, OpenAPI, and RAML.

The generated GraphQLSchema can be consumed by standard tools in the GraphQL ecosystem, such as:

• GraphQL Config
• GraphQL Code Generator
• GraphQL ESLint

You can also bind the generated schema to GraphQL servers like Envelop, Express-GraphQL, GraphQL Helix, Apollo Server, or GraphQL Yoga.

GraphQL Mesh is a framework for building GraphQL gateways and APIs by aggregating data from various sources. It acts as a proxy that allows you to use GraphQL queries and mutations to interact with non-GraphQL services like REST, gRPC, OpenAPI/Swagger, OData, SOAP/WSDL, Apache Thrift, Mongoose, and databases such as MongoDB, MySQL, PostgreSQL, and Neo4j.

Key capabilities include:

• Schema Modification: Modify output schemas, link types across schemas, and merge schema types.
• Customization: Add custom GraphQL types and resolvers.
• Data Fetching Control: Control how data is fetched to overcome backend implementation issues or legacy API limitations.
• Deployment Options: Run as a local GraphQL schema (using GraphQL execute) or deploy as a gateway layer for internal services.

Type merging allows you to define partial definitions of a type across multiple subschemas. These partial definitions are merged into a single unified type in the gateway schema.

When a query is made for a merged type, the gateway intelligently delegates portions of the request to the relevant subschemas in the correct dependency order and combines the results. This is the preferred method for combining subgraphs (similar to Apollo Federation) and replaces the older schema extensions method.

GraphQL Mesh operates using four primary concepts to create a unified gateway:

1. Sources: Sub-services such as GraphQL APIs or REST APIs.
2. Handlers: Components that translate a Source into a GraphQL Schema (e.g., translating a Swagger definition into a schema).
3. Unified Schema: The final, merged GraphQL schema resulting from combining all Sources' schemas.
4. Transforms: Optional transformations applied to the Unified Schema to modify its structure or behavior.

In a typical workflow, Mesh fetches definitions from Sources, uses Handlers to convert them to GraphQL, merges them into a Unified Schema, and optionally applies Transforms.

GraphQL Mesh supports several caching strategies to boost performance. You can choose from the following storage options depending on your environment and requirements:

• File Cache: Stores cached data in files.
• LocalForage: Uses LocalForage for storage (typically useful in browser-based or specific runtime environments).
• CloudFlare Workers KV: Leverages CloudFlare Workers Key-Value storage.
• Redis Cache: Uses a Redis instance for distributed caching.

When running mesh dev or mesh start, you can use dynamic values in your header configuration by accessing the GraphQL Context (which represents the incoming HTTP request). Expressions must follow JavaScript syntax.

• Accessing Headers: Use {context.headers['header-name']} to retrieve a specific header value. Important: Do not use capital letters when accessing header names (e.g., use x-my-api-token instead of X-My-Api-Token).
• Accessing Cookies: Use {context.cookies.cookieName} to access cookie values.

sources:
  - name: Example
    handler:
      <handler-name>:
        operationHeaders:
          # Accessing a header value
          Authorization: Bearer {context.headers['x-my-api-token']}
          # Accessing a cookie value
          Authorization: Bearer {context.cookies.myApiToken}

You can use any environment variable in your Mesh configuration by using the {env.VARIABLE_NAME} syntax. This is useful for setting dynamic endpoints or credentials.

Example: Using an environment variable for a base URL in a GraphQL handler.

sources:
  - name: MyGraphQLApi
    handler:
      graphql:
        endpoint: '{env.BASE_URL}/graphql'

To create subgraphs from regular sources that lack federation annotations, install the @graphql-mesh/transform-federation package.

npm i @graphql-mesh/transform-federation

To ensure certain data is only cached when a user session is present, use the scope: PRIVATE argument with the @cacheControl directive.

Any query that contains a type or a field marked with scope: PRIVATE will only be cached if a session is present.

type Query {
  me: User @cacheControl(scope: PRIVATE)
}

type User @cacheControl(scope: PRIVATE) {
  #...
}

Install the maxTokensPlugin using npm or yarn:

npm i @escape.tech/graphql-armor-max-tokens