Clarify documentation about feature-flagged GraphQL entities
We currently provide some hints on how to deal with feature flags in GraphQL queries but it has some flaws:
- We recommend using the
@includedirective, but we do not clearly state that this requires feature-flagged entities to exist in the schema, no matter what the directive evaluates to. So, in the case where the flag is off, we should recommend that the corresponding resolver returnsnullin the backend.- We could also mention the
@skipdirective which is the opposite of@includeand can be used for similar purposes.
- We could also mention the
- It might be worth mentioning that another option to dealing with this is to maintain 2 versions of a client-side query: one including the new fields, and the other one without them. Then, the client should trigger the correct query based on the feature flag's state. This is a less maintainable approach as it involves duplicated code, but it can be useful in cases where the field is removed from the schema when the flag is off.
/cc @farias-gl