The Guild LogoThe Guild Monogram
GraphQL Mesh

GraphQL Mesh

Query anything, run anywhere.

Contact Us

JSON Schema or Samples#

image

 

For a guided tutorial, please refer to "How to: Configure Sources with no definition"

 


 

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 (type: JSON)
  • schemaHeaders (type: JSON)
  • operations - (required) Array of:
    • 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)
      • 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

  • argTypeMap (type: JSON)
  • 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)