RFC - consistent GraphQL API Schema between roles

[ryami333]

AKA - "don't use the GraphQL schema as an access-control mechanism."

Summary

One of the fundamental reasons why GraphQL is so advantageous as a front-end application query language is that the GraphQL schema acts as a universal (and machine-readable) contract for the shape of data that crosses the application's data boundaries. In other words, its value is that we can predict the exact shape of a query's response payload, by cross-referencing only the query itself and the GraphQL schema, and nothing else.

However, Directus has subverted this expectation by implementing dynamic GraphQL schema. Two different users will have different schema, depending on their access permissions to each of the available collections. This means we can no longer effectively use ubiquitous tools like GraphQL Codegen, because the generated types only reflect one role's GraphQL schema. Two queries that are otherwise identical (besides headers) can be validated against entirely different schema. This problem is likely to be exacerbated even further once policies are implemented.

We are requesting that the GraphQL API behave more like other headless CMS solutions' (eg. Contentful, Sanity.io et al.) and decouple the GraphQL schema from collections' access-control, so that GraphQL queries can be statically analysed. We recognise that this would be a breaking change, and therefore would need to be tied to a major Directus release (eg. v11).

Basic Example

No response

Motivation

We want a single source-of-truth for our GraphQL APIs schema - and access-control to be enforced only at the server level (which it is already). This makes it possible to statically analyse .graphql files, which enables eg.

• Linting and (statically) validating queries.
• Using code-generators like GraphQL Codegen.

Detailed Design

All outlined above.

Requirements List

All outlined above.

Drawbacks

This would be a breaking change to tooling+integrations, which would necessitate a major Directus release (eg. v11.0.0).

However, it's worth pointing out that this would be a non-breaking change to queries. In other words, the runtime behaviour is more-or-less unchanged. A query that worked before will work now, and a query that failed before will fail now, except it might fail with 403 FORBIDDEN instead of 400 FAILED VALIDATION.

Alternatives

Alternative is to do nothing.

Adoption Strategy

See drawbacks, above.

Unresolved Questions

No response

[rijkvanzanten]

One of the fundamental reasons why GraphQL is so advantageous as a front-end application query language is that the GraphQL schema acts as a universal (and machine-readable) contract for the shape of data that crosses the application's data boundaries

The contract and shape of the data differs based on the access control though. For example access to nested relational data changes the shape of the output, hence the contract. If you were to use a shared contract for every user, you'll have to include the whole schema, which will not be accurate for users that have access control (and therefore exposing the shape of your data model to non-authenticated users if you have introspection enabled).

---

Now riffing on that thought: wouldn't you want your front-end GraphQL contract to be based on the actual access you have from that front-end paradigm? If have a GraphQL file that documents the whole data model, but your user only has access to some of it, wouldn't you find yourself constantly running into unexpected unauthorized errors as the graphql tooling allowed you to make the requests without warning? 🤔

[rijkvanzanten]

I guess the TL;DR is:

[...] This makes it possible to statically analyse .graphql files, which enables eg.

• Linting and (statically) validating queries.
• Using code-generators like GraphQL Codegen.

This should already be possible. You can use the /specs/graphql endpoint to generate the GraphQL schema for the role your using on your front-end ensuring that the contract you have in your graphql tooling for the project matches the actual queries you're allowed to make, or use the same endpoint to generate the admin-schema which includes everything (which would behave the same as your suggested change to have a single schema for everybody)