11 Apa Itu Skema GraphQL? Konsep dan Komponen

GraphQL telah mengubah cara kita membangun API. Tidak hanya memberi cara baru dalam query data, GraphQL menawarkan fleksibilitas yang sulit didapat dari REST API biasa. Di balik kekuatan GraphQL, terdapat elemen penting yang menjadi fondasinya: skema. Pada artikel ini, saya akan membahas secara mendalam tentang apa itu skema GraphQL, konsep dasar yang mendukungnya, serta komponen utama yang harus dipahami oleh setiap engineer yang ingin membangun sistem handal dengan GraphQL.

1. Pengantar Skema GraphQL

Sederhananya, skema GraphQL adalah kontrak antara server dan client. Ia mendeskripsikan keseluruhan kemampuan API - tipe data apa saja yang bisa di-query, relasi antar data, operasi apa saja yang bisa dijalankan, dan bagaimana bentuk hasilnya.

Bayangkan ketika membangun REST API, Anda harus mendokumentasikan endpoint, parameter, dan response-nya. Dalam GraphQL, seluruh detail itu tertuang dalam satu skema yang selalu up-to-date dan valid secara otomatis.

2. Mengapa Skema Penting?

• Otomatisasi Dokumentasi: Skema dapat didokumentasikan dan diinspeksi secara otomatis, salah satunya melalui tool seperti GraphQL Playground atau GraphiQL.
• Validasi Data: Setiap permintaan (query/mutation) yang tidak sesuai skema akan ditolak server.
• Introspeksi: Client bisa mengeksplorasi skema untuk mengetahui tipe data dan operasi yang tersedia.

3. Struktur Dasar Skema

Skema GraphQL ditulis dalam Schema Definition Language (SDL), yang bentuknya menyerupai definisi tipe pada TypeScript atau bahasa pemrograman modern lainnya.

Contoh Skema Sederhana

type Query {
  user(id: ID!): User
}

type User {
  id: ID!
  name: String!
  email: String
}

Di sini, skema menentukan ada satu query (user) yang menerima id bertipe ID! (wajib), dan mengembalikan tipe User.

4. Diagram Alur Kerja Skema

Mari kita visualisasikan bagaimana skema memproses query menggunakan diagram mermaid:

graph TD
    A[Client Kirim Query] --> B[Validasi Terhadap Skema]
    B -- Valid --> C[Eksekusi Resolver]
    B -- Tidak Valid --> D[Return Error]
    C --> E[Return Data]
    D --> F[Selesai]
    E --> F

5. Komponen Utama Skema GraphQL

1. Type (Tipe Data)
2. Query
3. Mutation
4. Subscription
5. Input Type
6. Enum
7. Interface
8. Union
9. Scalar
10. Directive
11. Resolver

Kita akan bahas satu per satu.

6. Type: Membangun Struktur Data

Setiap data di GraphQL didefinisikan sebagai type. Tipe dapat berupa objek, scalar, enum, atau gabungan.

type Book {
  id: ID!
  title: String!
  author: Author!
}

7. Query: Pintu Masuk Pengambilan Data

Semua pengambilan data dalam GraphQL lewat Query.

type Query {
  books: [Book]
  book(id: ID!): Book
}

8. Mutation: Manipulasi Data

Untuk menciptakan, mengubah, atau menghapus data, gunakan Mutation.

type Mutation {
  addBook(title: String!, authorId: ID!): Book!
  deleteBook(id: ID!): Boolean!
}

9. Subscription: Real-Time Data

Subscription memungkinkan client menikmati perubahan data secara real-time lewat WebSocket atau transport lainnya.

type Subscription {
  bookAdded: Book
}

10. Scalar, Enum, dan Input Type

Scalar

Tipe dasar (primitive) seperti Int, Float, String, Boolean, dan ID.

Enum

Untuk value yang terbatas.

enum BookStatus {
  AVAILABLE
  CHECKED_OUT
  LOST
}

Input Type

Digunakan agar input lebih terstruktur.

input AddBookInput {
  title: String!
  authorId: ID!
}

11. Interface dan Union: Polymorphism ala GraphQL

Interface

Definisi contract untuk beberapa type.

interface Character {
  id: ID!
  name: String!
}
type Human implements Character {
  id: ID!
  name: String!
  homePlanet: String
}
type Droid implements Character {
  id: ID!
  name: String!
  primaryFunction: String
}

Union

Untuk field yang mungkin hasilnya lebih dari satu type.

union SearchResult = Book | Author

12. Resolver: Implementasi Bisnis Logic

Setiap field dalam Query, Mutation, atau Subscription harus punya resolver, yang berfungsi mengeksekusi permintaan.

const resolvers = {
  Query: {
    books: () => getBooksFromDB(),
    book: (_, { id }) => getBookById(id),
  },
  Mutation: {
    addBook: (_, { title, authorId }) => insertBook(title, authorId),
  }
};

13. Directive: Customisasi di Level Skema

Directive adalah anotasi pada skema untuk modifikasi perilaku, misal @deprecated atau membuat directive sendiri seperti @auth.

type Book {
  title: String!
  published: Boolean! @deprecated(reason: "Field diganti dengan publishDate")
}

14. Skema Sebagai Sumber Kebenaran (Source of Truth)

Perlu diingat, skema GraphQL adalah pusat dari semua interaksi API. Perubahan pada skema (misal: menambah field baru, mengubah type) akan langsung berdampak ke seluruh ekosistem aplikasi.

15. Simulasi Query & Response

Agar lebih jelas, berikut simulasi query dan responsenya sesuai skema di atas.

Query:

query {
  books {
    id
    title
    author {
      name
    }
  }
}

Response:

{
  "data": {
    "books": [
      {
        "id": "1",
        "title": "GraphQL in Action",
        "author": { "name": "John Doe" }
      },
      {
        "id": "2",
        "title": "Learning GraphQL",
        "author": { "name": "Jane Doe" }
      }
    ]
  }
}

16. Tabel Perbandingan Komponen Skema

17. Kesimpulan

Memahami skema GraphQL adalah langkah paling fundamental dalam membangun API berbasis GraphQL. Skema bukan hanya mendeskripsikan data, tapi juga menentukan bagaimana client dan server harus berinteraksi. Dengan pemahaman yang kuat tentang konsep dan komponen skema, Anda bisa merancang API yang scalable, robust, dan mudah dikembangkan.

Sebagai engineer, jangan ragu mengeksplorasi skema dengan mencoba, menginspeksi, dan memanfaatkan auto-documentation yang tersedia di banyak ecosystem GraphQL. Selalu ingat: Skema adalah kontrak. Pastikan ia jelas, ketat, dan selalu menjadi source of truth di projek Anda.

Salam,

Engineer yang selalu belajar dari skema.