openapi handlers

The openapi handler allows you to connect to an OpenAPI-compliant REST service endpoint or static Swagger schema using a .json or .yaml file.

data-variant=info

data-slots=text
When using a Swagger schema, API Mesh can only access application/json content from the Swagger API definition.
data-variant=warning

data-slots=text
API Mesh does not accept a wildcard (*/*) as a content type.
{
  "meshConfig": {
    "sources": [
      {
        "name": "CommerceREST",
        "handler": {
          "openapi": {
            "source": "https://venia.magento.com/rest/"
          }
        },
      }
    ]
  },
}

To import a remote or local schema using .json or .yaml, use a local source, see Reference local file handlers for more information.

data-variant=info

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

Naming conventions

The OpenAPI handler uses the following naming conventions:

Type naming

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

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

The following example demonstrates how to include authentication headers in the context of your mesh.

...
      "handler": {
        "openapi": {
          "source": "./my-schema.json",
          "operationHeaders": {
            "Authorization": "Bearer {context.headers['x-my-api-token']}"
          }
        }
      }
...

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"
  ]
}

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 }

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="
          }
        }
      }
    }
  ]
}

Config API reference