Wat zijn best practices voor het ontwerpen van een GraphQL-schema?

Question

IT Interview Practice · Accepted Answer

Een goed schema is **client-gedreven, nullable-by-default aan de randen, en evolueerbaar zonder versies**. Het modelleert het domein in termen die clients daadwerkelijk gebruiken, niet je databasetabellen.

## Nullability

Maak een veld alleen non-null (`!`) wanneer je het *altijd* kunt teruggeven. `!` overmatig gebruiken is een valkuil: als een non-null veld een fout geeft, zet het zijn hele parent-object op null, waardoor een kleine fout een groot leeg vlak wordt. Kies nullable voor alles wat afhangt van een downstream service.

```graphql
type User {
  id: ID!             # werkelijk altijd aanwezig
  email: String!      # verplicht in je DB -> veilig als non-null
  avatarUrl: String   # komt van een externe service -> nullable, zodat een fout geïsoleerd blijft
}
```

## Naamgeving & inputs

- Gebruik consistente, beschrijvende namen; booleans lezen als predicaten (`isPublished`).
- Geef elke mutation één enkel **`input`**-type en geef een **payload**-type terug — je kunt later velden toevoegen zonder de signatuur te breken.

```graphql
input CreatePostInput { title: String!, body: String! }
type CreatePostPayload { post: Post!, errors: [UserError!]! }  # ruimte om te groeien
type Mutation { createPost(input: CreatePostInput!): CreatePostPayload! }
```

## Evolutie zonder versionering

GraphQL vermijdt `/v2`-URLs. Je evolueert **additief**: voeg velden vrij toe, en trek oude terug met `@deprecated` terwijl clients migreren.

```graphql
type User {
  fullName: String!
  name: String! @deprecated(reason: "Use fullName")   # blijf serveren tot clients overstappen
}
```

Een veld verwijderen of hernoemen is de enige echte breaking change, dus ontwerp zo dat je het zelden nodig hebt. Vermijd ook het lekken van de DB-vorm (expose `fullName`, niet `first_name`/`last_name` als clients één veld willen).

## Waarom het belangrijk is

Deze keuzes onderscheiden een schema dat jaren meegaat van een schema waar clients tegen vechten. Interviewers gebruiken dit om **volwassenheid in API-ontwerp** te peilen — vooral de trade-off tussen nullability en fouten en de additieve-evolutie-mindset, die uniek zijn voor GraphQL.

Nullability

Naamgeving & inputs

Evolutie zonder versionering

Waarom het belangrijk is

Gerelateerde vragen