diff options
Diffstat (limited to 'doc/development/api_graphql_styleguide.md')
| -rw-r--r-- | doc/development/api_graphql_styleguide.md | 22 |
1 files changed, 22 insertions, 0 deletions
diff --git a/doc/development/api_graphql_styleguide.md b/doc/development/api_graphql_styleguide.md index e8aa33b31a7..96b256dc022 100644 --- a/doc/development/api_graphql_styleguide.md +++ b/doc/development/api_graphql_styleguide.md @@ -76,6 +76,28 @@ a new presenter specifically for GraphQL. The presenter is initialized using the object resolved by a field, and the context. +### Nullable fields + +GraphQL allows fields to be be "nullable" or "non-nullable". The former means +that `null` may be returned instead of a value of the specified type. **In +general**, you should prefer using nullable fields to non-nullable ones, for +the following reasons: + +- It's common for data to switch from required to not-required, and back again +- Even when there is no prospect of a field becoming optional, it may not be **available** at query time + - For instance, the `content` of a blob may need to be looked up from Gitaly + - If the `content` is nullable, we can return a **partial** response, instead of failing the whole query +- Changing from a non-nullable field to a nullable field is difficult with a versionless schema + +Non-nullable fields should only be used when a field is required, very unlikely +to become optional in the future, and very easy to calculate. An example would +be `id` fields. + +Further reading: + +- [GraphQL Best Practices Guide](https://graphql.org/learn/best-practices/#nullability) +- [Using nullability in GraphQL](https://blog.apollographql.com/using-nullability-in-graphql-2254f84c4ed7) + ### Exposing Global IDs When exposing an `ID` field on a type, we will by default try to |