OpenAPI handlers

This handler allows you to load remote or local OpenAPI (2.0-3.0) and Swagger schemas.

When using a Swagger schema, API Mesh can only access application/json content from the Swagger API definition. API Mesh does not accept a wildcard (*/*) as a content type.

You can import a remote or local schema .json or .yaml. To use a local source with an API handler, see Reference local file handlers for more information.

If your source handler's schema is modified, you must update your mesh to allow API Mesh to cache any changes.

To get started, use the handler in your Mesh config file:

{
  "sources": [
    {
      "name": "MyOpenapiApi",
      "handler": {
        "openapi": {
          "source": "./monolith-open-api-schema.json"
        }
      }
    }
  ]
}
Copied to your clipboard
{
  "sources": [
    {
      "name": "MyOpenapiApi",
      "handler": {
        "openapi": {
          "source": "./monolith-open-api-schema.json"
        }
      }
    }
  ]
}

Since the OpenAPI handler is based on the JSON Schema handler, JSON Schema handler configurations also apply to the OpenAPI handler.

Naming conventions

The OpenAPI handler uses the following naming conventions:

Type naming

The operationId is only modified when necessary according to the GraphQL spec:

The following characters are replaced with an underscore (_): white space, ., /, : and -.
Characters that are not digits or Latin letters are replaced with their character codes.
If the first character of a name is a digit, it is prefixed with an underscore (_), because GraphQL does not allow initial digits.

Unnamed types

Unnamed types use path-based naming. This means a type in your schema could be structured like query_getUsers_items_firstName.

Headers from context

{
  "sources": [
    {
      "name": "MyGraphQLApi",
      "handler": {
        "openapi": {
          "source": "./my-schema.json",
          "operationHeaders": {
            "Authorization": "Bearer {context.headers['x-my-api-token']}"
          }
        }
      }
    }
  ]
}
Copied to your clipboard
{
  "sources": [
    {
      "name": "MyGraphQLApi",
      "handler": {
        "openapi": {
          "source": "./my-schema.json",
          "operationHeaders": {
            "Authorization": "Bearer {context.headers['x-my-api-token']}"
          }
        }
      }
    }
  ]
}

Advanced cookies handling

When building a web application cookies are often used for secure authentication. Conversely, mobile applications tend to use an HTTP header.

Setting and Unsetting cookies

To set the cookie for the web application, we need to access the HTTP response that is sent back to the client by using additionalResolvers. To do this, we need to create two new resolvers, one for login and one for logout.

The first step is to edit the mesh.json file, and add the following at the end:

{
  "additionalTypeDefs": "extend type Mutation {\n  login(credentials: Credentials!): String\n  logout: Boolean\n}\n",
  "additionalResolvers": [
    "./src/additional-resolvers.js"
  ]
}
Copied to your clipboard
{
  "additionalTypeDefs": "extend type Mutation {\n  login(credentials: Credentials!): String\n  logout: Boolean\n}\n",
  "additionalResolvers": [
    "./src/additional-resolvers.js"
  ]
}

Then manage the cookie in the new resolvers:

// lifespan of our cookie
const oneYear = 365 * 24 * 3600

const resolvers = {
  Mutation: {
    async login(root, args, context, info) {
      // Call the Rest API's login operation
      const result = await context.Rest.Mutation.accountLogin({
        root,
        args: {
          credentials: args.credentials
        },
        context,
        info
      })
      // if `result` contains a JWT token, you could instead decode it and set `Expires`
      // to the JWT token's expiration date
      res.set('Set-Cookie', `accessToken=${result}; Path=/; Secure; HttpOnly; Max-Age=${oneYear};`)

      return result
    },
    logout(root, args, { res }) {
      // use old date to unset cookie
      res.set('Set-Cookie', `accessToken=logout; Path=/; Secure; HttpOnly; Expires=Thu, 1 Jan 1970 00:00:00 GMT;`)

      return true
    },
  },
}

module.exports = { resolvers }
Copied to your clipboard
// lifespan of our cookie
const oneYear = 365 * 24 * 3600

const resolvers = {
  Mutation: {
    async login(root, args, context, info) {
      // Call the Rest API's login operation
      const result = await context.Rest.Mutation.accountLogin({
        root,
        args: {
          credentials: args.credentials
        },
        context,
        info
      })
      // if `result` contains a JWT token, you could instead decode it and set `Expires`
      // to the JWT token's expiration date
      res.set('Set-Cookie', `accessToken=${result}; Path=/; Secure; HttpOnly; Max-Age=${oneYear};`)

      return result
    },
    logout(root, args, { res }) {
      // use old date to unset cookie
      res.set('Set-Cookie', `accessToken=logout; Path=/; Secure; HttpOnly; Expires=Thu, 1 Jan 1970 00:00:00 GMT;`)

      return true
    },
  },
}

module.exports = { resolvers }

Callbacks as Subscriptions

The OpenAPI handler can process OpenAPI Spec Callbacks as GraphQL Subscriptions, by using your Publish-subscribe pattern PubSub implementation to consume the data. However, you need to define webhooks for callbacks individually.

Loading source from a CDN

API Mesh supports loading sources from a CDN or schema registry by using the source property.

{
  "sources": [
    {
      "name": "MyApi",
      "handler": {
        "openapi": {
          "source": "https://cdn.<your cdn>.graphql",
          "schemaHeaders": {
            "X-CDN-Key": "abc123+d4/5e="
          }
        }
      }
    }
  ]
}
Copied to your clipboard
{
  "sources": [
    {
      "name": "MyApi",
      "handler": {
        "openapi": {
          "source": "https://cdn.<your cdn>.graphql",
          "schemaHeaders": {
            "X-CDN-Key": "abc123+d4/5e="
          }
        }
      }
    }
  ]
}

Config API reference

source (type: Any, required) - Reference to your API source, such as a local file, a remote file, or a URL endpoint
sourceFormat (type: String (json | yaml)) - Format of the source file
schemaHeaders (type: JSON) - JSON object for adding headers to API calls for runtime schema introspection
- If you are using a remote URL endpoint, you can set headers for the HTTP request to fetch your schema.
operationHeaders (type: JSON) - JSON object for adding headers to API calls for runtime operation execution
baseUrl (type: String) - URL that all paths are based on
- The baseURL overrides the server object in the OpenAPI Spec.
qs (type: JSON) - JSON object for the query search parameters to add to the API call
includeHttpDetails (type: Boolean) - Flag for including HTTP Response details in the result object