Apa saja best practice untuk desain GraphQL schema?

Question

IT Interview Practice · Accepted Answer

Schema yang baik itu **client-driven, nullable-by-default di tepian, dan bisa berevolusi tanpa versioning**. Ia memodelkan domain dalam istilah yang benar-benar dipakai client, bukan tabel database Anda.

## Nullability

Jadikan sebuah field non-null (`!`) hanya jika Anda bisa *selalu* mengembalikannya. Terlalu banyak memakai `!` adalah jebakan: jika sebuah field non-null error, ia menjadikan seluruh parent object-nya null, mengubah kegagalan kecil menjadi kekosongan besar. Lebih baik nullable untuk apa pun yang bergantung pada downstream service.

```graphql
type User {
  id: ID!             # truly always present
  email: String!      # required in your DB -> safe as non-null
  avatarUrl: String   # comes from an external service -> nullable, so its failure is isolated
}
```

## Penamaan & input

- Gunakan nama yang konsisten dan deskriptif; boolean dibaca sebagai predikat (`isPublished`).
- Beri setiap mutation satu tipe **`input`** dan kembalikan tipe **payload** — Anda bisa menambah field belakangan tanpa merusak signature.

```graphql
input CreatePostInput { title: String!, body: String! }
type CreatePostPayload { post: Post!, errors: [UserError!]! }  # room to grow
type Mutation { createPost(input: CreatePostInput!): CreatePostPayload! }
```

## Evolusi tanpa versioning

GraphQL menghindari URL `/v2`. Anda berevolusi secara **aditif**: tambahkan field sebebasnya, dan pensiunkan yang lama dengan `@deprecated` sementara client bermigrasi.

```graphql
type User {
  fullName: String!
  name: String! @deprecated(reason: "Use fullName")   # keep serving until clients move off
}
```

Menghapus atau mengganti nama field adalah satu-satunya breaking change yang sesungguhnya, jadi desainlah sedemikian rupa agar Anda jarang perlu melakukannya. Hindari juga membocorkan bentuk DB (ekspos `fullName`, bukan `first_name`/`last_name` jika client menginginkan satu field).

## Mengapa ini penting

Pilihan-pilihan inilah yang membedakan schema yang bertahan bertahun-tahun dari yang justru dilawan oleh client. Interviewer memakai ini untuk mengukur **kematangan desain API** — terutama trade-off nullability/error dan pola pikir evolusi aditif, yang unik pada GraphQL.

Nullability

Penamaan & input

Evolusi tanpa versioning

Mengapa ini penting

Pertanyaan terkait