OpenAPI handlers

This handler allows you to load remote or local OpenAPI (2/3) 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 it using remote/local .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"
        }
      }
    }
  ]
}

This handler is based on the JSON Schema handler, so its configurations also apply to the openapi handler.

Naming convention

We use the operationId for names, and aim to keep it as close as possible to the origin.

Type naming

We adjust the operationId only when necessary according to the GraphQL spec:

- Characters, such as white space, `.`, `/`, `:` and `-`, are replaced with an underscore (`_`).
- Other characters which are not digits or Latin letters are replaced with their character codes.
- If the first character of a name is a digit, we prefix it with an underscore (`_`), because GraphQL does not allow initial digits.
Copied to your clipboard
- Characters, such as white space, `.`, `/`, `:` and `-`, are replaced with an underscore (`_`).
- Other characters which are not digits or Latin letters are replaced with their character codes.
- If the first character of a name is a digit, we prefix it with an underscore (`_`), because GraphQL does not allow initial digits.

Unnamed types

We use path-based naming. So names 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, for security reasons, cookies are often used for authentication. Mobile applications on the other end, tend to use an HTTP header.

Of course, being able to use your mesh as a Gateway for both the mobile application and web application is nice, but there's one thing missing: the setting of the cookie for the web application.

For that, we need to access the HTTP response that is sent back to the client. Luckily, we can do so in additionalResolvers. So we need to create two new resolvers, one for login and one for logout, and manage the cookie in their code.

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 OAS Callbacks as GraphQL Subscriptions. It uses your PubSub implementation to consume the data. But you have to define webhooks for individual callbacks to make it work.

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) - A pointer to your API source - could be a local file, remote file, or url endpoint
sourceFormat (type: String (json | yaml)) - Format of the source file
operationHeaders (type: JSON) - JSON object representing the Headers to add to the runtime of the API calls
schemaHeaders (type: JSON) - If you are using a remote URL endpoint to fetch your schema, you can set headers for the HTTP request to fetch your schema.
baseUrl (type: String) - Specifies the URL that all paths will be based on. Overrides the server object in the OAS.
qs (type: JSON) - JSON object representing the query search parameters to add to the API calls
includeHttpDetails (type: Boolean) - Include HTTP Response details to the result object