GraphQL — apa itu, bahasa kueri dan penerapan dalam proyek mobile

Apa itu GraphQL?

GraphQL — adalah spesifikasi dan lingkungan runtime untuk API yang memberikan klien kendali penuh atas data yang diterima. Dikembangkan oleh insinyur Facebook untuk memecahkan masalah aplikasi mobile News Feed, spesifikasi ini diterbitkan sebagai standar terbuka pada tahun 2015. Sejak 2018, GraphQL berada di bawah pengelolaan GraphQL Foundation dengan dukungan Linux Foundation dan perusahaan seperti Apollo, AWS, GitHub, SAP, dan lainnya.

Berbeda dengan REST, di mana setiap endpoint mengembalikan struktur data tetap, GraphQL menggunakan satu endpoint yang menerima string kueri. Klien menjelaskan dalam kueri bidang apa yang dibutuhkan, dan server mengembalikan persis bidang tersebut. Misalnya, kueri { user(id: “1”) { name email } } hanya akan mengembalikan name dan email pengguna, tanpa bidang tambahan seperti address, phone atau createdAt yang harus diambil di REST.

GraphQL tidak terikat pada basis data atau bahasa tertentu. Spesifikasi hanya mendefinisikan format kueri dan respons. Ada implementasi server di Node.js (graphql-js, Apollo Server), Kotlin (graphql-kotlin, Netflix DGS Framework), Python (Graphene, Strawberry), Ruby (graphql-ruby) dan bahasa lainnya. Pustaka klien tersedia untuk semua platform utama, termasuk Apollo Client untuk iOS, Android, dan web.

Bagaimana GraphQL bekerja

Arsitektur GraphQL terdiri dari tiga komponen utama: skema (Schema), resolver (Resolvers), dan mesin eksekusi (GraphQL Engine). Skema menentukan tipe data apa yang tersedia, kueri apa yang dapat dilakukan, dan argumen apa yang diterima. Resolver adalah fungsi di sisi server yang mengembalikan data untuk setiap bidang skema. Mesin eksekusi menerima kueri yang masuk, memvalidasinya terhadap skema, memanggil resolver yang sesuai, dan menyusun respons.

Proses pemrosesan kueri terlihat seperti ini:

• Klien mengirim permintaan POST ke /graphql dengan body JSON { “query”: “...” }
• Server mengurai kueri, membangun AST (Abstract Syntax Tree) dan memvalidasinya terhadap skema
• Mesin melintasi AST, memanggil resolver untuk setiap bidang dan mengumpulkan data
• Respons dikembalikan dalam format JSON, sesuai dengan struktur kueri

Keunggulan utama arsitektur GraphQL adalah resolusi di tingkat bidang. Di REST, pengembang mendapatkan semua bidang sumber daya (mungkin dengan kelebihan) atau menggunakan ekstensi seperti ?fields=name,email. Di GraphQL, penyaringan semacam itu sudah terintegrasi dalam bahasa: setiap kueri secara eksplisit menentukan bidang apa yang diperlukan, dan server mengembalikan persis bidang tersebut. Ini sangat penting untuk aplikasi mobile, di mana volume data yang dikirimkan secara langsung memengaruhi kecepatan pemuatan dan konsumsi data.

Query, Mutation dan Subscription

GraphQL mendefinisikan tiga jenis operasi, yang masing-masing sesuai dengan skenario interaksi tertentu. Query — untuk membaca data, analog dengan GET di REST. Mutation — untuk mengubah data (membuat, memperbarui, menghapus), analog dengan POST/PUT/DELETE. Subscription — untuk pembaruan real-time melalui WebSocket, yang tidak memiliki analog langsung di REST klasik (memerlukan solusi tambahan seperti WebSocket atau Server-Sent Events).

Sintaks dasar kueri intuitif:

// Kueri sederhana dengan argumen
query {
    user(id: "42") {
        name
        email
        avatarUrl
    }
}

// Mutation dengan mengembalikan data yang diubah
mutation {
    updateProfile(name: "Ivan") {
        id
        name
        updatedAt
    }
}

// Subscription — mendengarkan pembaruan real-time
subscription {
    newMessage(chatId: "chat_1") {
        id
        text
        sender { name }
    }
}

Query dijalankan secara paralel — semua bidang pada level yang sama dimuat secara bersamaan. Ini memungkinkan memuat data terkait (pengguna dan postingannya) dengan satu kueri tanpa banyak round-trip. Mutation dijalankan secara berurutan — mutasi dalam satu kueri dijalankan satu per satu sesuai urutan deklarasi. Subscription membuat koneksi permanen melalui WebSocket, di mana server mengirim data saat terjadi peristiwa.

Operasi dapat menerima variabel untuk memisahkan data dari kueri, direktif (@include, @skip) untuk penyertaan bidang bersyarat, dan fragmen untuk penggunaan kembali kumpulan bidang. Kemampuan ini membuat kueri GraphQL fleksibel dan dapat digunakan kembali, yang sangat penting dalam proyek besar dengan banyak layar dan komponen.

Skema dan sistem tipe GraphQL

Inti dari GraphQL adalah sistem tipe, yang menggambarkan semua kemungkinan data dan operasi API. Skema (Schema) adalah deskripsi tipe yang dapat dikembalikan server dan kueri yang diterimanya. Skema ditulis dalam Bahasa Schema Definition Language (SDL) dan berfungsi sebagai kontrak antara klien dan server. Klien dapat memperoleh skema melalui introspeksi — kueri khusus __schema yang mengembalikan deskripsi lengkap API.

Contoh skema untuk blog:

// SDL — Schema Definition Language
type User {
    id: ID!
    name: String!
    email: String
    posts: [Post!]!
}

type Post {
    id: ID!
    title: String!
    content: String
    author: User!
}

type Query {
    user(id: ID!): User
    posts(page: Int): [Post!]!
}

Tanda seru (!) berarti bidang non-null — dijamin akan ada dalam respons. Tanda kurung siku [ ] menunjukkan daftar. GraphQL mendukung tipe skalar (Int, Float, String, Boolean, ID), tipe objek, enum, union, interface, dan tipe input (untuk argumen mutasi). Pengetikan yang ketat membuat API mendokumentasikan diri sendiri dan memungkinkan alat klien menghasilkan kode: tipe TypeScript, kelas data Kotlin, struktur Swift.

Introspeksi — kemampuan unik GraphQL yang tidak ada di REST. Klien dapat mengirim kueri ke skema dan menerima deskripsi lengkap semua tipe, bidang, argumen, dan direktif. Ini menjadi dasar alat seperti GraphiQL dan Apollo Studio, yang secara otomatis menghasilkan dokumentasi dan pelengkapan otomatis untuk pengembang. Introspeksi juga memungkinkan penulisan tes otomatis yang memeriksa kesesuaian skema dengan struktur yang diharapkan.

Perbandingan GraphQL dengan REST

Pilihan antara GraphQL dan REST adalah salah satu pertanyaan arsitektur utama saat merancang API. Kedua pendekatan memiliki kelebihan dan kekurangan, dan pilihan tergantung pada kebutuhan spesifik proyek. REST unggul dalam kesederhanaan dan universalitas, GraphQL dalam fleksibilitas dan efisiensi kueri. Mari kita lihat tabel perbandingan.

Kekurangan utama GraphQL adalah kesulitan caching. Di REST, caching HTTP bekerja di tingkat URL: satu permintaan ke /api/users/42 selalu mengembalikan struktur yang sama, dan respons dapat di-cache berdasarkan URL. Di GraphQL, semua permintaan menuju ke satu endpoint, struktur respons tergantung pada body permintaan. Untuk mengatasi masalah ini, Apollo Client menggunakan cache yang dinormalisasi di sisi klien yang membagi respons menjadi entitas terpisah berdasarkan id dan secara otomatis memperbaruinya saat menerima data baru.

Aspek penting lainnya adalah masalah N+1. Saat meminta data bersarang (misalnya, postingan pengguna dan komentar untuk setiap postingan), GraphQL dapat menjalankan kueri SQL terpisah untuk setiap elemen daftar. Ini diselesaikan dengan DataLoader — utilitas untuk batch dan caching kueri basis data yang mengelompokkan kueri individu menjadi satu kueri batch. Di REST, masalah ini kurang terasa karena pengembang mengontrol struktur respons di sisi server.

Contoh kueri GraphQL

Mari kita lihat contoh praktis penggunaan GraphQL dalam aplikasi mobile di Kotlin dengan Apollo Client. Contoh-contoh tersebut mendemonstrasikan skenario umum: memuat data untuk layar profil (query), membuat postingan baru (mutation), dan berlangganan komentar baru (subscription). Setiap contoh mencakup kueri GraphQL dan kode di sisi klien.

Query: memuat profil dengan postingan

Satu kueri GraphQL memuat pengguna, postingan terakhirnya, dan jumlah total pengikut. Di REST, diperlukan setidaknya 2-3 permintaan: /users/42, /users/42/posts, /users/42/stats. GraphQL menggabungkannya dalam satu round-trip, mengurangi waktu pemuatan layar pada koneksi lambat.

// Kueri GraphQL (dalam file .graphql)
query ProfileScreen($userId: ID!) {
    user(id: $userId) {
        name
        bio
        avatarUrl
        posts(limit: 10) {
            id
            title
            createdAt
        }
        followersCount
        followingCount
    }
}

// Panggilan di sisi klien (Apollo Client + Kotlin)
val response = apolloClient
    .query(ProfileScreenQuery(userId = "42"))
    .execute()
binding.nameText.text = response.data?.user?.name

Mutation: membuat postingan baru

Mutasi tidak hanya membuat sumber daya, tetapi juga mengembalikan data terkini untuk memperbarui UI. Bidang __typename digunakan oleh Apollo Client untuk normalisasi cache — klien secara otomatis memperbarui catatan Post di cache saat menerima respons mutasi yang berhasil.

// Mutasi GraphQL
mutation CreatePost($input: CreatePostInput!) {
    createPost(input: $input) {
        id
        title
        createdAt
        author {
            id
            name
        }
    }
}

// Panggilan mutasi dengan tipe input
val input = CreatePostInput(
    title = "Postingan baru tentang GraphQL",
    content = "GraphQL menyederhanakan bekerja dengan API..."
)
val result = apolloClient
    .mutation(CreatePostMutation(input))
    .execute()

Keunggulan penting GraphQL dibandingkan REST dalam konteks pengembangan mobile adalah generasi kode otomatis. Apollo Client untuk Kotlin (Apollo GraphQL) menghasilkan kelas yang aman tipe dari file .graphql pada tahap build. Jika server mengubah skema, proyek tidak akan terbuild hingga kueri diperbarui. Ini mencegah kesalahan runtime yang khas di REST, di mana perubahan struktur respons mungkin tidak terdeteksi selama pengembangan.

Ekosistem: Apollo, Relay dan alat

Ekosistem GraphQL mencakup beberapa pustaka dan alat utama yang menyederhanakan pengembangan dan operasi. Apollo Client — pustaka klien paling populer, mendukung React, iOS, Android, dan Kotlin Multiplatform. Relay dari Facebook — alternatif untuk aplikasi React dengan pendekatan unik dalam manajemen data dan caching. Pilihan antara Apollo dan Relay tergantung pada platform dan kebutuhan kinerja.

Di sisi server, Apollo Server (Node.js), Netflix DGS Framework (Kotlin/Java), dan graphql-ruby memimpin. Untuk mengembangkan skema dan menguji kueri, digunakan GraphiQL — IDE interaktif yang terintegrasi di browser. Apollo Studio menyediakan metrik kinerja, pelacakan kueri, dan manajemen skema untuk lingkungan produksi. Secara terpisah, perlu disebutkan GraphQL Code Generator — alat yang menghasilkan tipe TypeScript, Kotlin, Swift, dan Dart dari skema SDL.

Untuk pengembangan mobile, Apollo Kotlin (Apollo GraphQL) sangat menarik — pustaka yang sepenuhnya ditulis dalam Kotlin dengan dukungan coroutine, Flow, dan Multiplatform. Ini memungkinkan penggunaan kueri GraphQL yang sama untuk Android dan iOS dalam proyek Kotlin Multiplatform. Apollo Kotlin menormalkan cache, mendukung kesalahan di tingkat bidang (partial errors), dan secara otomatis menghasilkan model data dari file .graphql. Ini menjadikan GraphQL pilihan utama untuk proyek mobile besar di mana kecepatan pengembangan dan keamanan tipe sangat penting.