Proposal: GraphQL editor deeplinking standard

[ncthbrt]

GraphQL has wide editor support, and projects like GraphiQL and GraphQL Playground have ensured that there is a proliferation of different web editor instances.

An invariable feature that we have already seen rolled out on an adhoc basis (e.g. https://www.onegraph.com/graphiql) is the ability to generate a link within a graphql editor that allows easy sharing of queries between users.

Such links are also useful from a documentation perspective, in that they allow users to easily open, edit, and run queries referenced in the documentation by simply clicking a link, improving the user experience.

A standardized format for these links would be a boon not only to online editors, but also IDEs, in that a given IDE would be able to register an app uri handler for GraphQL, making it very easy to implement features such as "open in local ide".

The format would not necessarily be restricted to just queries, it could also be potentially useful for service discovery, perhaps referencing an introspection endpoint, or schema SDL.

[acao]

this is a good idea for spec discussion!

[ncthbrt]

One important consideration, is the carrying capacity of the URIs, on the most common platforms, and whether encoding the information directly in the URI will be be sufficient for the purposes described above.

Encoding the info directly would be preferable in that it would allow implementation without requiring any sort of storage infrastructure beyond the URI itself.

The ReasonML Sandbox provides evidence that encoding data in the URI may be sufficient. As far as I can tell, the editor state is directly encoded in the query string.

e.g. Link to ReasonML example here.

Disadvantages of such a long URI is that, well, it's long

[ncthbrt]

Additional considerations are around security of the header values were they to be included in this standard.

OAuth 2's implicit flow places sensitive information in the hash fragment of the return url. This ensures that in browsers that this information remains on the client side, and is not transmitted to the backend.

It may be wise to mandate for similar reasons that header values are encoded in the hash fragment of the URI, as header values are likely to contain the authorization header.

Alternative approaches are simply to disallow header values, or include them in the non hash part of the uri at the user's risk.

[ncthbrt]

I'm busy prototyping a naive implementation in our current instance of the editor, so will be able to evaluate different url schemes.

[delagroove]

hey @ncthbrt, I wonder if you got stuff done over this issue, looking to deeplink certain mutations documentation and this seems the way to go

[ncthbrt]

Hi @delagroove Unfortunately we had to develop a proprietary version as hadn't got much traction on this. Fortunately the implementation is fairly straightforward, though the URL can become quite long

[acao]

@thomasheyenbrock and @jonathanawesome this one is also very important, and much requested! in fact, other tooling authors have asked about this as well. it ties in with the feature of adding query params we had planned for 2.0 in the roadmap