Use graphql extensions to provide information about bindings in server response

There was a discussion a while ago about how to visualize the composition of a GraphQL server that uses multiple bindings. This proposal addresses this issue.

What information to provide

A ‘best practice’ GraphQL server uses a single schema, and using delegation in the resolvers to delegate queries and mutations to 1 or more bindings (back-end GraphQL endpoints). During development and testing, it would be great to know:

• What binding(s) the different parts of a query response come from
• Which connection settings where used for a binding

How to provide this information

The GraphQL spec allows extensions to be added to a server response. Tracing and cache control already use these extensions to provide additional information. I would propose to also use extension information to provide information about the bindings. A sample bindings extension object could look like this:

bindings: [
  { 
    "path": ["post, "comments"],
    "binding": {
      "name": "mydatasource",
      "endpoint": "http://api.graph.cool/mydatasource/dev"
    }
  }
]

The path specification is identical to the cache control extension (for a uniform approach). Endpoint information will not always be easily available though. Graphcool bindings provide an explicit endpoint. Generic bindings provide an executableSchema, so that information might not be available at all. One option might be creating an apollo-link variation that supports keeping track of this. Another, more generic solution, might be to setup an inline proxy to route all outgoing traffic through, so the hosts can be gathered (this is a commonly used setup in express).

How to visualize this information

This information could be used by graphql-playground to provide some form of visual representation. This can be discussed further in the graphql-playground repo.

[schickling]

This is really awesome @kbrandwijk. Let’s see whether we can collaborate with the folks @apollographql on this, as this looks similar to the GraphQL tracing extension.

[kbrandwijk]

I’ve been playing around some more with this idea. This is what I’ve got so far:

• Whenever you call a delegate in graphcool-binding, the path to the current node and the delegate that is called is saved on the context
• A custom formatResponse function is used on apollo-server to access that information from the context, and put it in an extensions object.
• The updated extension object looks something like:

bindings: [
  { 
    "path": ["post, "comments"],
    "binding": {
      "name": "mydatasource",
      "endpoint": "http://api.graph.cool/mydatasource/dev",
      "path": ["query", "comments"]
    }
  }
]