12 Menulis File Skema GraphQL Pertama Anda

Ditulis oleh: Seorang engineer yang pernah tersesat dalam hutan RESTful API

GraphQL sudah menjadi API favorit banyak tim engineering tidak hanya karena fleksibilitas query-nya, tapi juga berkat sistem tipenya yang sangat eksplisit. Namun, bagi yang baru kenal, memahami bagaimana menulis file skema (schema file) pertama bisa terasa intimidatif. Tenang, di artikel ini saya akan membimbing Anda langkah demi langkah hingga menghasilkan skema GraphQL pertama yang siap diuji.

Apa Itu File Skema GraphQL?

Secara sederhana, file skema GraphQL (*.graphql atau *.gql) adalah blueprint API Anda. Di sana Anda mendeskripsikan tipe data apa yang tersedia, field apa saja yang bisa diquery, dan tipe operasi apa (Query, Mutation, Subscription) yang didukung.

Skema GraphQL biasanya ditulis dalam format Schema Definition Language (SDL).

Diagram Alur: Skema GraphQL dalam API Lifecycle

Mari mulai dengan gambaran besarnya dulu. Berikut alur sederhana (menggunakan Mermaid):

flowchart TD
    A[Client mengirim query] --> B[Server memetakan ke skema GraphQL]
    B --> C[GraphQL Resolver menangani logic]
    C --> D[Data dikembalikan ke client]

Kuncinya: Skema adalah kontrak antara client dan server.

Simulasi Kasus: API Buku

Anggap tim Anda ingin membangun API sederhana untuk data buku dan penulis. Fungsionalitas awal berupa:

• Mengambil daftar buku
• Mengambil detail buku
• Menambah buku baru

Mari peta kebutuhan tersebut ke skema.

1. Mulai dengan type Dasar

Pikirkan entitas utama: buku dan penulis.

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

type Author {
  id: ID!
  name: String!
  books: [Book!]!
}

Penjelasan:

• Tipe data Boolean, String, Int, Float, ID tersedia secara default.
• ! menandakan required (tidak boleh null).

2. Definisikan Query

Operasi baca (read/fetch) adalah domain dari type Query.

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

Dengan begini, client bisa melakukan:

• books → Mendapat semua buku
• book(id: ...) → Mendapat detail sebuah buku
• authors → Mendapat semua penulis

Contoh query:

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

3. Tambahkan Mutation

Untuk menambah data, gunakan type Mutation.

type Mutation {
  addBook(title: String!, authorId: ID!, year: Int): Book
}

Contoh mutasi:

mutation {
  addBook(title: "Clean Code", authorId: "1", year: 2008) {
    id
    title
  }
}

4. Susun Menjadi Satu Skema

File schema.graphql Anda sekarang kira-kira jadi begini:

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

type Author {
  id: ID!
  name: String!
  books: [Book!]!
}

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

type Mutation {
  addBook(title: String!, authorId: ID!, year: Int): Book
}

5. Validasi dengan Tool

Disarankan menggunakan GraphQL Playground atau extensi VSCode seperti Apollo GraphQL. Copy-paste skema di atas, server Anda siap menerima query dan mutation.

6. Simulasi Resolver (Pseudocode)

Bagian penting setelah skema: resolver (handler logic). Contoh dalam JavaScript (Node.js):

const resolvers = {
  Query: {
    books: () => db.books,
    book: (_, { id }) => db.books.find(b => b.id === id),
    authors: () => db.authors,
  },
  Mutation: {
    addBook: (_, { title, authorId, year }) => {
      const book = { id: uuid(), title, author: authorId, year };
      db.books.push(book);
      return book;
    }
  },
  Book: {
    author: (book) => db.authors.find(a => a.id === book.author),
  },
  Author: {
    books: (author) => db.books.filter(b => b.author === author.id),
  }
};

7. Kembangkan!

GraphQL sangat fleksibel. Skema tinggal Anda kembangkan: mari tambah field baru, misal rating:

type Book {
  ...
  rating: Float
}

Atau type baru, misal Review, lalu relasikan dengan Book.

8. Tips Praktis Penulisan Skema

• Modular: Pisahkan tipe-tipe besar ke file sendiri (book.graphql, author.graphql), lalu import (pakai tool seperti Apollo/GraphQL-tools).
• Komentar: Pakai tanda # untuk menulis komentar agar skema tetap terjaga jelas.
• Enum: Gunakan Enum untuk field dengan pilihan terbatas (misal status).

enum BookStatus {
  AVAILABLE
  OUT_OF_STOCK
  DELETED
}

• InputType: Untuk input kompleks pada mutation, deklarasikan tipe input terpisah.

input BookInput {
  title: String!
  authorId: ID!
  year: Int
}

9. Testing: Query Table

Berikut tabel perbandingan query dan response dari skema yang Anda buat:

10. Kapan schema diubah?

Merubah schema (misal menambah field baru) sebaiknya:

• Setelah diskusi kebutuhan client
• Setelah validasi data model
• Mengikuti versioning, jika breaking change

11. Skema dan Dokumentasi Otomatis

Skema adalah dokumentasi API. Tools seperti GraphQL Playground, Apollo Studio, atau Voyager akan menampilkan API dari skema tadi secara otomatis.

12. Review: 5 Checklist Validasi Skema Anda

Penutup

Skema GraphQL adalah pondasi utama API modern. Luangkan waktu mendesain sebelum coding resolvernya. Modularisasi skema, tulis komentar, dan diskusikan dengan tim. Dengan 12 langkah di atas, saya harap Anda tidak hanya mampu menulis file skema pertama, tapi juga siap untuk membuat API GraphQL yang solid, ekspansif, dan mudah di-maintain.

Jika ada tips lain atau ingin request topik lanjutan, sila tinggalkan komentar. Happy GraphQL-ing! 🚀