JSON Schema handlers

This handler allows you to load any remote REST service and describe its request and response. JSON Schema handlers allow you to customize and control the GraphQL schema.

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

For more information on creating JSON schemas, refer to this JSON schema tutorial.

The JSON Schema handler uses the following format:

Copy
{
  "sources": [
    {
      "name": "MyApi",
      "handler": {
        "JsonSchema": {
          "baseUrl": "https://your-service-url/endpoint/",
          "operations": [
            {
              "type": "Query",
              "field": "users",
              "path": "/users",
              "method": "GET",
              "responseSchema": "https://json-schema/schema.json"
            }
          ]
        }
      }
    }
  ]
}
Copied to your clipboard
{
  "sources": [
    {
      "name": "MyApi",
      "handler": {
        "JsonSchema": {
          "baseUrl": "https://your-service-url/endpoint/",
          "operations": [
            {
              "type": "Query",
              "field": "users",
              "path": "/users",
              "method": "GET",
              "responseSchema": "https://json-schema/schema.json"
            }
          ]
        }
      }
    }
  ]
}

JSON Schema handlers can also use local sources, see Reference local file handlers for more information.

The following example returns your header values, so you can confirm your headers are functioning properly.

Copy
{
  "meshConfig": {
    "sources": [
      {
        "name": "headersData",
        "handler": {
          "JsonSchema": {
            "baseUrl": "<your baseUrl>",
            "operationHeaders": {
              "sample-operation-header": "sample operation value"
            },
            "schemaHeaders": {
              "sample-schema-header": "sample schema value"
            },
            "operations": [
              {
                "type": "Query",
                "field": "data",
                "path": "/getHeadersData",
                "method": "GET",
                "responseSchema": "./getHeadersSchema.json"
              }
            ],
            "ignoreErrorResponses": false
          }
        }
      }
    ],
    "files": [
      {
        "path": "./getHeadersSchema.json",
        "content": "{\"$schema\":\"http://json-schema.org/draft-07/schema#\",\"type\":\"object\",\"required\":[\"headerKeys\",\"headerValues\",\"headers\"],\"properties\":{\"headerKeys\":{\"type\":\"array\",\"items\":{\"type\":\"string\"}},\"headerValues\":{\"type\":\"array\",\"items\":{\"type\":\"string\"}},\"headers\":{\"type\":\"object\"}}}"
      }
    ]
  }
}
Copied to your clipboard
{
  "meshConfig": {
    "sources": [
      {
        "name": "headersData",
        "handler": {
          "JsonSchema": {
            "baseUrl": "<your baseUrl>",
            "operationHeaders": {
              "sample-operation-header": "sample operation value"
            },
            "schemaHeaders": {
              "sample-schema-header": "sample schema value"
            },
            "operations": [
              {
                "type": "Query",
                "field": "data",
                "path": "/getHeadersData",
                "method": "GET",
                "responseSchema": "./getHeadersSchema.json"
              }
            ],
            "ignoreErrorResponses": false
          }
        }
      }
    ],
    "files": [
      {
        "path": "./getHeadersSchema.json",
        "content": "{\"$schema\":\"http://json-schema.org/draft-07/schema#\",\"type\":\"object\",\"required\":[\"headerKeys\",\"headerValues\",\"headers\"],\"properties\":{\"headerKeys\":{\"type\":\"array\",\"items\":{\"type\":\"string\"}},\"headerValues\":{\"type\":\"array\",\"items\":{\"type\":\"string\"}},\"headers\":{\"type\":\"object\"}}}"
      }
    ]
  }
}

Headers from context

Copy
{
  "sources": [
    {
      "name": "MyGraphQLApi",
      "handler": {
        "JsonSchema": {
          "baseUrl": "https://some-service-url/endpoint-path/",
          "operationHeaders": {
            "Authorization": "Bearer {context.headers['x-my-api-token']}"
          }
        }
      }
    }
  ]
}
Copied to your clipboard
{
  "sources": [
    {
      "name": "MyGraphQLApi",
      "handler": {
        "JsonSchema": {
          "baseUrl": "https://some-service-url/endpoint-path/",
          "operationHeaders": {
            "Authorization": "Bearer {context.headers['x-my-api-token']}"
          }
        }
      }
    }
  ]
}

Query Parameters

There are multiple methods for defining query parameters. Select the method that fits your needs, or combine multiple methods:

Automatically declare query parameters

API Mesh automatically generates arguments for operations (if needed). Arguments are generated as nullable strings by default.

Copy
{
    "sources": [
        {
            "name": "MyGraphQLApi",
            "handler": {
                "JsonSchema": {
                    "baseUrl": "https://your-service/endpoint/",
                    "operations": [
                        {
                            "type": "Query",
                            "field": "user",
                            "path": "/user?id={args.id}",
                            "method": "GET",
                            "responseSchema": "./json-schemas/user.json"
                        }
                    ]
                }
            }
        }
    ]
}
Copied to your clipboard
{
    "sources": [
        {
            "name": "MyGraphQLApi",
            "handler": {
                "JsonSchema": {
                    "baseUrl": "https://your-service/endpoint/",
                    "operations": [
                        {
                            "type": "Query",
                            "field": "user",
                            "path": "/user?id={args.id}",
                            "method": "GET",
                            "responseSchema": "./json-schemas/user.json"
                        }
                    ]
                }
            }
        }
    ]
}

Manually declare query parameters

You can define the operation's arguments by modifying the argTypeMap config field according to the JSON Schema spec.

In this example, we declare a page argument as an object with limit and offset properties:

Copy
{
    "argTypeMap": {
        "page": {
            "type": "object",
            "properties": {
                "limit": {
                    "type": "number"
                },
                "offset": {
                    "type": "number"
                }
            }
        }
    }
}
Copied to your clipboard
{
    "argTypeMap": {
        "page": {
            "type": "object",
            "properties": {
                "limit": {
                    "type": "number"
                },
                "offset": {
                    "type": "number"
                }
            }
        }
    }
}

Arguments should be added to the path using the queryParamArgMap config field, especially for non-primitive types.

Here we add the page argument to the query parameters:

Copy
{
    "sources": [
        {
            "name": "MyGraphQLApi",
            "handler": {
                "JsonSchema": {
                    "baseUrl": "https://your-service-/endpoint/",
                    "operations": [
                        {
                            "type": "Query",
                            "field": "users",
                            "path": "/getUsers",
                            "method": "GET",
                            "responseSample": "./jsons/MyField.response.json",
                            "responseTypeName": "MyResponseName",
                            "argTypeMap": {
                                "page": {
                                    "type": "object",
                                    "properties": {
                                        "limit": {
                                            "type": "number"
                                        },
                                        "offset": {
                                            "type": "number"
                                        }
                                    }
                                }
                            },
                            "queryParamArgMap": {
                                "page": "page"
                            }
                        }
                    ]
                }
            }
        }
    ]
}
Copied to your clipboard
{
    "sources": [
        {
            "name": "MyGraphQLApi",
            "handler": {
                "JsonSchema": {
                    "baseUrl": "https://your-service-/endpoint/",
                    "operations": [
                        {
                            "type": "Query",
                            "field": "users",
                            "path": "/getUsers",
                            "method": "GET",
                            "responseSample": "./jsons/MyField.response.json",
                            "responseTypeName": "MyResponseName",
                            "argTypeMap": {
                                "page": {
                                    "type": "object",
                                    "properties": {
                                        "limit": {
                                            "type": "number"
                                        },
                                        "offset": {
                                            "type": "number"
                                        }
                                    }
                                }
                            },
                            "queryParamArgMap": {
                                "page": "page"
                            }
                        }
                    ]
                }
            }
        }
    ]
}

Config API reference

• baseUrl (type: String) - URL or file path for your JSON schema.
• schemaHeaders (type: JSON) - JSON object for adding headers to API calls for runtime schema introspection
• operationHeaders (type: JSON) - JSON object for adding headers to API calls for runtime operation execution
• operations - (required) Array of:
  • object:
    • field (type: String, required)
      • Cannot contain hyphens.
    • description (type: String)
    • type (type: String (Query | Mutation | Subscription), required)
    • requestSchema (type: Any)
    • requestSample (type: Any)
    • requestTypeName (type: String)
    • responseSchema (type: Any)
      • Remote files and URLs are not supported. You must provide a local path.
    • responseSample (type: Any)
      • Remote files and URLs are not supported. You must provide a local path.
    • responseTypeName (type: String)
    • argTypeMap (type: JSON)
• ignoreErrorResponses (type: Boolean) - Flag for ignoring errors in the response

Last updated 9/11/2023

Was this helpful?

Yes

No