JSON schema handlers

This handler allows you to load any remote REST service and describe its request/response. With this handler, you can easily customize and control the GraphQL schema in API Mesh for Adobe Developer App Builder.

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.

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

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

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

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 a few methods to define the query parameters, select the one that fits your needs (or combine them):

Auto declare

The mesh automatically generates arguments for operations if needed. Arguments are generated as nullable strings by default.

Copy
{
    "sources": [
        {
            "name": "MyGraphQLApi",
            "handler": {
                "JsonSchema": {
                    "baseUrl": "https://some-service-url/endpoint-path/",
                    "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://some-service-url/endpoint-path/",
                    "operations": [
                        {
                            "type": "Query",
                            "field": "user",
                            "path": "/user?id={args.id}",
                            "method": "GET",
                            "responseSchema": "./json-schemas/user.json"
                        }
                    ]
                }
            }
        }
    ]
}

Manual declare

You can define the arguments of the operation using 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"
                }
            }
        }
    }
}

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

Here we add the page argument to the query parameters:

Copy
{
    "queryParamArgMap": {
        "page": "page"
    }
}
Copied to your clipboard
{
    "queryParamArgMap": {
        "page": "page"
    }
}

And here is the final config:

Copy
{
    "sources": [
        {
            "name": "MyGraphQLApi",
            "handler": {
                "JsonSchema": {
                    "baseUrl": "https://some-service-url/endpoint-path/",
                    "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://some-service-url/endpoint-path/",
                    "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)
• operationHeaders (type: JSON)
• schemaHeaders (type: JSON)
• 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)

Last updated 9/11/2023

Was this helpful?

Yes

No