JSON Schema or Samples

This handler allows you to load any remote REST service and describe its request/response using the YAML config.

You can easily customize and control the built GraphQL schema with this handler.

To get started, install the handler library:

yarn add @graphql-mesh/json-schema

Now, you can use it directly in your Mesh config file:

sources:
  - name: MyApi
    handler:
      jsonSchema:
        baseUrl: https://some-service-url/endpoint-path/
        operations:
          - type: Query
            field: users
            path: /users
            method: GET
            responseSchema: ./json-schemas/users.json

Dynamic Values

Mesh can take dynamic values from the GraphQL Context or the environmental variables. For example, if you use mesh dev or mesh start, GraphQL Context will be the incoming HTTP request.

The expression inside dynamic values should be as in JS.

From Context (HTTP Header for mesh dev or mesh start)

sources:
  - name: MyGraphQLApi
    handler:
      jsonSchema:
        baseUrl: https://some-service-url/endpoint-path/
        operationHeaders:
          # Please do not use capital letters while getting the headers
          Authorization: Bearer {context.headers['x-my-api-token']}

And for mesh dev or mesh start, you can pass the value using x-my-graphql-api-token HTTP header.

From Environmental Variable

MY_API_TOKEN is the name of the environmental variable you have the value.

sources:
  - name: MyGraphQLApi
    handler:
      jsonSchema:
        baseUrl: https://some-service-url/endpoint-path/
        operationHeaders:
          Authorization: Bearer {env.MY_API_TOKEN}
          # You can also access to the cookies like below;
          # Authorization: Bearer {context.cookies.myApiToken}

From Arguments

Mesh automatically generates arguments for operations if needed;

sources:
  - name: MyGraphQLApi
    handler:
      jsonSchema:
        baseUrl: https://some-service-url/endpoint-path/
        operations:
          - type: Query
            field: user
            path: /user/{args.id}
            method: GET
            responseSchema: ./json-schemas/user.json

This example operation definition will generate a root field with id: ID argument. Mesh will interpolate the expression in path to get id value from args.

From JSON Samples

Mesh can also load JSON samples from a remote service. Add a json-samples directory in your project root, and put the JSON samples there (responseSample: ./jsons/MyField.response.json - Create a new folder like Jsons). By declaring the responseSample, you can use the JSON sample in the GraphQL schema.

Mesh Sample Example - .meshrc.yml file

sources:
  - name: MyGraphQLApi
    handler:
      jsonSchema:
        baseUrl: https://some-service-url/endpoint-path/
        operations:
          - type: Query
            field: MyField
            path: /MyField?id={args.id}
            method: GET
            responseSample: ./jsons/MyField.response.json
            responseTypeName: MyResponseName
            argsTypeMap:
              id: String

Mesh Sample Example - ./jsons/MyField.response.json file

Any JSON sample file can be used.

Codesandbox Example

You can check out our example that uses the JSON Schema handler with mock data.

Config API Reference

• baseUrl (type: String)
• operationHeaders - One of:
  • JSON
  • String
• schemaHeaders (type: JSON)
• operations - (required) Array of:
  • object:
    • field (type: String, required) - This Field based on the field name of the URL path. Example: "https://MyAPIURL.com/FieldNameHere/", so we will set the "field: FieldNameHere".
    • description (type: String) - Your chance to describe the operation! Make sure the description is clear and concise.
    • type (type: String (Query | Mutation | Subscription), required) - Type field is set the opertion type: Query, Mutation or Subscription.
    • requestSchema (type: Any) - Your chance to provide request schema name.
    • requestSample (type: Any) - The path definition of the JSON Schema sample. Example: "./jsons/questions.response.json".
    • requestTypeName (type: String) - Inset any name for the type of the request body.
    • requestBaseBody (type: Any) - This body will be merged with the request body sent with the underlying HTTP request
    • responseSchema (type: Any) - Yay! Now you can provide the response schema name.
    • responseSample (type: Any) - Did you use Sample? Provide the response sample path.
    • responseTypeName (type: String) - Inset any name for the type of the response body.
    • responseByStatusCode (type: Any) - You can define your response schemas by status codes;

responseByStatusCode:
  200:
    responseSchema: ./someschema.json#/somepath
  404:
    responseSample: ./error-sample.json
    responseTypeName: MyError

• exposeResponseMetadata (type: Boolean) - Expose response details done to the upstream API When you enable this, you will see a new field in the response type;

type MyResponseType {
  myFooField: String
  _response: ResponseMetadata
}
 
# And a new type for the response metadata object
type ResponseMetadata {
  url: URL
  status: Int
  method: String
  headers: JSON
  body: String
}

• argTypeMap (type: JSON) - Mapping the JSON Schema and define the arguments of the operation. Example: 'argTypeMap: ID: String'
• path (type: String, required)
• method (type: String (GET | HEAD | POST | PUT | DELETE | CONNECT | OPTIONS | TRACE | PATCH))
• headers (type: JSON)
• binary (type: Boolean) - If true, this operation cannot have requestSchema or requestSample And the request body will be passed as binary with its mime type unless you define an explicit Content-Type header
• object:
  • field (type: String, required)
  • description (type: String)
  • type (type: String (Query | Mutation | Subscription), required)
  • requestSchema (type: Any)
  • requestSample (type: Any)
  • requestTypeName (type: String)
  • requestBaseBody (type: Any) - This body will be merged with the request body sent with the underlying HTTP request
  • responseSchema (type: Any)
  • responseSample (type: Any)
  • responseTypeName (type: String)
  • argTypeMap (type: JSON)
  • pubsubTopic (type: String, required)
• ignoreErrorResponses (type: Boolean)
• queryParams (type: Any)
• queryStringOptions (type: Object):
  • indices (type: Boolean) - When arrays are stringified, by default they are not given explicit indices: a=b&a=c&a=d You may override this by setting the indices option to true: a[0]=b&a[1]=c&a[2]=d
  • arrayFormat (type: String (indices | brackets | repeat | comma)) - You can configure how to format arrays in the query strings.

Note: when using arrayFormat set to 'comma', you can also pass the commaRoundTrip option set to true or false, to append [] on single-item arrays, so that they can round trip through a parse.

• commaRoundTrip (type: Boolean) - Even if there is a single item in an array, this option treats them as arrays (default: false)