💯 Generating the schema with independently versioned fields and directives
— 6 minute read
A few weeks ago I had added the ability to independently version fields and directives in GraphQL by PoP, by passing the version constraint as a field/directive argument when executing the query. This works well but has a problem: that specific version of the schema could be accessed only by running the query, but not by introspection. So we couldn't run clients or tools against it.
Today I have fixed this issue. Now, the specific version for a field/directive can be provided to the endpoint through URL params, so it can be incorporated when generating the schema artifact. This way, clients and tooling have complete visibility of all possible versions of the schema, allowing to:
have a client coded in TypeScript be generated by pointing to the exact required schema
point to a different version of the schema just by modifying the endpoint (eg: useful to wait for feature flags to kick in)
visualize the schema in GraphQL Voyager, run queries in GraphiQL
Let's check out some examples. In the GraphiQL clients below, the URL parameters fieldVersionConstraints and directiveVersionConstraints were added to the endpoint /api/graphql/ (check it out in the Network tab in Firefox/Chrome DevTools).
In this query, field userServiceURLs is queried with version 0.1.0 set by field argument, and with version 0.2.0 by default, as set through URL param fieldVersionConstraints[Root.userServiceURLs]=^0.2:
To double check that the default field has version 0.2.0, we can click on the documentation explorer, browse to Root.userServiceURLs, and read the version added to its description:
Services used in the application: GitHub data for a specific repository (Version: 0.2.0)
It works the same way for directives. In this query, directive makeTitle is queried with version 0.2.0 set by directive argument, and with version 0.1.0 by default, as set through URL param directiveVersionConstraints[makeTitle]=^0.1:
Of course they can be combined. In this query we are independently setting the version for fields userServiceURLs and userServiceData, and directive makeTitle:
I have added tons of new features to GraphQL by PoP lately. It is now finally time to work on providing documentation (so I am not the only one who can get to use it!). For that, the following weeks I will be completing the documentation on the newly-launched GraphQL by PoP site.
Access Control Lists, to control who can access the schema, set-up on a field-by-field basis
HTTP caching, configured through Cache Control Lists, to define the Cache-Control max-age on a field-by-field basis (and it will be smart: if a field cannot be cached, then the whole request will not be cached!); and internal caching for expensive operations
Most of the features are ready, and I can already say: they are so awesome! Check out this screenshot:
Exciting times are coming!
Don't be shy, contact me (I'm here to help) permalink