Kebanyakan API bekerja seperti menu tetap. Anda memanggil sebuah endpoint, lalu server menentukan apa yang Anda dapatkan, meskipun Anda hanya butuh satu potong kecil data. GraphQL membalik keadaan itu. Ia membiarkan klien menjelaskan tepat data apa yang dibutuhkan, lalu server mengembalikan respons yang bentuknya persis seperti permintaan. Satu perubahan inilah alasan banyak tim mengadopsinya untuk aplikasi dengan layar yang kompleks dan cepat berubah.
Poin Penting
GraphQL adalah bahasa query untuk API dan runtime untuk memenuhi query tersebut, yang dibangun di atas schema yang bertipe kuat.
Klien meminta tepat field yang dibutuhkan dalam satu permintaan, sehingga menghindari over-fetching dan under-fetching yang umum di REST.
Tiga jenis operasi mencakup sebagian besar kebutuhan: query membaca data, mutation mengubah data, dan subscription mengalirkan pembaruan langsung.
Schema, yang ditulis dalam Schema Definition Language, adalah kontrak antara klien dan server, dan ia membuat API mendokumentasikan dirinya sendiri.
GraphQL bukan pengganti REST di semua tempat. API yang sederhana, stabil, dan mudah di-cache sering kali lebih baik tetap memakai REST.
Apa Sebenarnya GraphQL Itu
GraphQL mendefinisikan dirinya sebagai bahasa query untuk API dan runtime sisi server untuk mengeksekusi query memakai sistem tipe yang Anda definisikan untuk data Anda. Definisi itu punya tiga bagian yang layak dibedah. Pertama, ia adalah bahasa: klien menulis permintaan yang menyebutkan field, bukan URL. Kedua, ia adalah runtime: server menerima permintaan itu, menjalankannya terhadap sumber datanya, dan mengembalikan data yang cocok. Ketiga, ia bertipe: setiap field punya tipe yang dinyatakan, sehingga kedua pihak sepakat sejak awal tentang apa saja yang mungkin.
GraphQL dibuat di dalam Facebook pada 2012, ketika aplikasi mobilnya butuh cara mengambil data yang lebih fleksibel daripada tumpukan endpoint REST yang terus bertambah. Pengembangan standar terbukanya dimulai pada 2015, dan GraphQL Foundation dibentuk pada 2019 sebagai rumah netral bagi ekosistemnya, menurut spesifikasi GraphQL. Kini ia dipakai perusahaan seperti GitHub dan Shopify, yang API publiknya dibangun di atasnya.
Kata "graph" dalam namanya menggambarkan cara data dimodelkan. Alih-alih endpoint terpisah untuk pengguna, postingan, dan komentar, GraphQL menampilkan satu graf berisi tipe dan field yang saling terhubung. Klien bisa mulai dari seorang pengguna, mengikuti sebuah field ke postingannya, lalu mengikuti field lain ke komentar tiap postingan, semuanya dalam satu permintaan. Bentuk respons mencerminkan bentuk query, sehingga tidak ada kejutan tentang apa yang dikembalikan.
Query: Minta Tepat Apa yang Anda Butuhkan
Query adalah operasi baca. Ia menyebutkan field yang Anda inginkan, dan server hanya mengembalikan field tersebut. Bayangkan layar profil yang butuh nama pengguna, avatar, dan judul lima postingan terbarunya. Dengan REST, itu bisa butuh dua atau tiga panggilan: satu untuk pengguna, satu untuk postingan, dan mungkin satu lagi untuk data terkait. Dengan GraphQL, satu query bisa menelusuri hubungan tersebut dan mengembalikan seluruh data layar itu sekaligus, seperti dijelaskan dokumentasi query resmi.
Cara ini menyelesaikan dua masalah klasik REST. Over-fetching terjadi ketika sebuah endpoint mengembalikan sumber daya lengkap padahal klien hanya butuh dua field, sehingga memboroskan bandwidth, terutama di koneksi seluler. Under-fetching terjadi ketika satu endpoint tidak mengembalikan cukup data, sehingga klien harus melakukan perjalanan tambahan untuk melengkapi kekurangannya. GraphQL menghilangkan keduanya dengan membiarkan klien menentukan bentuk setiap respons.
Query juga bisa memakai argumen, seperti id atau batas jumlah, dan bisa diberi nama serta dipakai ulang dengan variabel. Dua directive bawaan, @include dan @skip, membiarkan klien menyertakan atau melewatkan sebuah field secara kondisional berdasarkan variabel, yang berguna untuk layar yang berubah sesuai pengaturan pengguna.
Mutation: Mengubah Data, Lalu Mengonfirmasinya
Jika query membaca data, mutation menulisnya. Sebuah mutation membuat, memperbarui, atau menghapus record, dan mengembalikan data yang berubah dalam respons yang sama, memakai sintaks pemilihan field yang sama seperti query. Bagian terakhir ini penting dalam praktik: setelah memperbarui judul sebuah postingan, klien bisa langsung meminta judul yang diperbarui, penulis, dan stempel waktunya dalam satu perjalanan, bukan menulis dulu lalu membaca ulang.
Ada satu perbedaan penting dari query. Meskipun field query bisa diselesaikan secara paralel, field mutation tingkat atas berjalan satu demi satu, secara berurutan, seperti dicatat Hygraph. Urutan itu disengaja: ketika dua penulisan saling bergantung, menjalankannya berurutan membuat hasilnya bisa diprediksi. Nested mutation juga bisa mengubah entitas terkait dalam satu permintaan, misalnya membuat sebuah postingan bersama komentar pertamanya.
Subscription: Pembaruan Langsung Tanpa Polling
Query dan mutation mengikuti pola permintaan dan respons: klien bertanya, server menjawab, lalu koneksi ditutup. Pola itu kurang cocok untuk data langsung seperti pesan chat, skor langsung, atau status online, di mana klien harus bertanya berulang kali untuk memeriksa perubahan.
Subscription menyelesaikan ini dengan model publish dan subscribe, biasanya lewat WebSocket. Klien membuka satu koneksi dan berlangganan sebuah peristiwa, lalu server mendorong pembaruan setiap kali peristiwa itu terjadi, tanpa permintaan baru per pembaruan, seperti dijelaskan Hygraph. Sebuah subscription memakai gaya operasi yang sama seperti query dan mutation, termasuk variabel, operasi bernama, dan fragment, sehingga terasa sebagai jenis operasi ketiga yang alami, bukan sistem terpisah.
Schema: Kontrak yang Mendokumentasikan Dirinya Sendiri
Setiap API GraphQL didefinisikan oleh sebuah schema: kumpulan tipe dan field yang menjelaskan semua yang bisa dilakukan server, ditulis dalam Schema Definition Language (SDL). Apollo menggambarkan schema sebagai gambaran lengkap tentang apa yang bisa dilakukan sebuah server GraphQL, dan gambaran itu sekaligus menjadi dokumentasinya.
Schema mendefinisikan tiga tipe operasi akar, Query, Mutation, dan Subscription, ditambah tipe objek, field, dan hubungan di bawahnya. Lima tipe skalar bawaan adalah Int, Float, String, Boolean, dan ID, dan tipe-tipe itu bisa dikombinasikan dengan modifier list dan non-null, enum, interface, dan union, menurut Hygraph. Untuk setiap field, server menjalankan fungsi resolver yang mengambil nilainya dari sumber seperti database atau API REST yang sudah ada, yang berarti GraphQL bisa duduk di atas sistem yang sudah dimiliki sebuah tim.
Karena schema bertipe dan bisa di-query, perkakas bisa memeriksanya secara langsung. Introspeksi inilah yang menggerakkan autocomplete di editor seperti GraphiQL, dokumentasi otomatis, dan pembuatan kode untuk klien. Seorang developer yang baru bergabung dengan proyek bisa membuka schema dan langsung melihat apa saja yang ditawarkan API, tanpa berburu dokumen terpisah yang mungkin sudah kedaluwarsa.
GraphQL vs REST: Perbandingan Praktis
GraphQL dan REST menyelesaikan masalah yang sama dengan cara berbeda, dan trade-off-nya bersifat konkret, bukan ideologis. REST API Dijelaskan: Cara Kerja Gaya API Web yang Paling Umum membahas sisi REST secara detail. Tabel berikut merangkum perbedaan utamanya.
Aspek | REST | GraphQL |
|---|---|---|
Endpoint | Satu per sumber daya, seperti /users dan /posts | Umumnya satu, seperti /graphql |
Bentuk respons | Ditentukan server untuk tiap endpoint | Dipilih klien dalam tiap query |
Over-fetching | Umum, endpoint mengembalikan sumber daya lengkap | Dihindari, hanya field yang diminta yang dikembalikan |
Under-fetching | Umum, data terkait butuh panggilan tambahan | Dihindari, data bertingkat datang dalam satu query |
Schema | Opsional, sering dijelaskan dengan OpenAPI | Bawaan, bertipe kuat, mendokumentasikan diri sendiri |
Versioning | Sering butuh endpoint /v1, /v2 | Berkembang dengan menambah field dan menghentikan field lama |
Caching | Mudah dengan caching HTTP dan CDN | Lebih sulit, butuh cache klien atau persisted query |
Kurva belajar | Rendah, konsep HTTP yang familier | Lebih tinggi, schema, resolver, dan perkakas perlu dipelajari |
REST masih menang dalam beberapa situasi. Ketika data berasal dari satu sumber dan kebutuhan klien sederhana serta stabil, API REST lebih mudah dibangun, di-cache, dan dipahami, seperti dicatat Hygraph dalam perbandingannya. Caching HTTP bekerja langsung untuk permintaan GET, yang merupakan keunggulan nyata untuk data publik yang sering dibaca. GraphQL, sebaliknya, biasanya mengirim permintaan sebagai POST ke satu endpoint, sehingga cache HTTP standar tidak bisa membantu semudah itu, dan tim butuh cache klien yang dinormalisasi atau persisted query.
GraphQL layak dengan kompleksitasnya ketika kebutuhannya kompleks dan berubah: banyak sumber daya terkait dalam satu layar, beberapa platform klien dengan kebutuhan data berbeda, atau tim frontend yang ingin bergerak tanpa menunggu endpoint baru. Ia juga membawa risiko yang perlu dikelola. Query bertingkat yang dalam bisa mahal bagi server, sehingga API produksi butuh batas kedalaman query, batas kompleksitas, timeout, dan pemeriksaan autentikasi pada setiap field, bukan hanya di level endpoint.
Kapan Memilih yang Mana
Pilih GraphQL ketika satu layar menarik banyak sumber daya terkait, ketika klien seluler dan web butuh potongan data yang berbeda dari data yang sama, atau ketika frontend berubah lebih cepat daripada backend bisa merilis endpoint baru. Pilih REST ketika API-nya sederhana, publik dan mudah di-cache, atau ketika timnya kecil dan biaya desain schema, resolver, serta perkakas GraphQL lebih besar daripada manfaatnya. Banyak perusahaan memakai keduanya: REST untuk endpoint publik yang sederhana, GraphQL untuk API produk yang kompleks di balik aplikasinya.
Apa pun itu, keputusan harus mengikuti datanya, bukan trennya. Gaya API adalah perkakas, dan yang tepat adalah yang membuat layar yang benar-benar dilihat pengguna lebih murah dibangun dan lebih aman dijalankan.
Pertanyaan yang Sering Diajukan
Apakah GraphQL itu database?
Bukan. GraphQL adalah bahasa query dan runtime untuk API, bukan database. Resolver mengambil data dari apa pun yang ada di balik API, bisa database, API lain, atau campuran keduanya.
Apakah GraphQL menggantikan REST sepenuhnya?
Tidak. REST tetap cocok untuk API yang sederhana, stabil, dan mudah di-cache. GraphQL lebih kuat untuk data kompleks yang saling terkait dan untuk klien dengan kebutuhan data berbeda, tetapi ia menambah kompleksitas server yang tidak dibutuhkan API sederhana.
Apakah saya harus belajar bahasa baru untuk memakai GraphQL?
Anda menulis query dalam bahasa query GraphQL sendiri, tetapi bahasa itu kecil: field, argumen, variabel, dan tiga jenis operasi. Kode server bisa ditulis dalam banyak bahasa, termasuk JavaScript, Python, Ruby, Java, dan Go.
Apakah GraphQL hanya untuk perusahaan besar?
Tidak. Tim kecil juga bisa memakainya, terutama lewat layanan GraphQL terkelola atau hosted. Pertanyaannya adalah apakah kebutuhan data Anda membenarkan biaya setup-nya, bukan seberapa besar perusahaan Anda.
Bagaimana cara mulai belajar GraphQL?
Mulailah dari dokumentasi resmi di graphql.org, lalu coba API GraphQL publik, seperti milik GitHub, di sebuah perkakas explorer. Menulis beberapa query terhadap schema nyata mengajarkan lebih banyak, lebih cepat, daripada sekadar membaca tentang sintaksnya.