Graphql-yoga: Use graphql extensions to provide information about bindings in server response

[kbrandwijk]

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]

I really like this idea! We'll try to prioritize this and come up with a first mockup over the next few weeks.

Would be great to hear other people's thoughts and ideas on this as well! 🙏

[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"]
    }
  }
]

[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]

Yes, I took inspiration from that. I am already discussing this with them, because currently apollo-server has 2 hardcoded extensions and no way to specify another. Tooling is very limited there, the only place to do it is formatResponse, but doing this 'under the covers' means being extra careful about how to wrap this when the user also specifies it's own formatResponse.

See: https://github.com/apollographql/apollo-server/issues/657#issuecomment-354635072

[stale[bot]]

Due to inactivity of this issue we have marked it stale. It will be closed if no further activity occurs.

[stale[bot]]

Due to inactivity of this issue we have marked it stale. It will be closed if no further activity occurs.

[stale[bot]]

Hey :wave:, It seems like this issue has been inactive for some time. In need for maintaining clear overview of the issues concerning the latest version of graphql-yoga we'll close it.
Feel free to reopen it at any time if you believe we should futher discuss its content. :slightly_smiling_face: