GraphQL Persisted Queries: Mengurangi Beban API dan Membatasi Operasi Tak Dikenal

GraphQL memberi klien keleluasaan memilih field yang dibutuhkan dari satu endpoint. Fleksibilitas ini praktis, tetapi string operasi yang dikirim berulang kali dapat menambah ukuran request dan membuka ruang bagi operasi yang tidak direncanakan. Persisted queries mengatasi sebagian masalah tersebut dengan menyimpan operasi GraphQL yang telah dikenal, lalu merujuknya menggunakan identitas ringkas. Jika dirancang dengan benar, pendekatan ini dapat mengurangi lalu lintas jaringan sekaligus membantu membatasi permukaan serangan API.

Apa Itu Persisted Queries?

Dalam pola GraphQL biasa, klien mengirim dokumen operasi—misalnya query beserta nama field, argumen, dan fragment—ke server. Pada persisted queries, operasi didaftarkan atau dikenali terlebih dahulu, kemudian klien mengirim ID atau hash yang merujuk ke operasi itu. Server mencari operasi yang cocok dan menjalankannya sesuai skema serta aturan akses yang berlaku.

Istilah ini mencakup dua pola yang berkaitan, tetapi tidak identik. Automatic Persisted Queries (APQ) biasanya menggunakan hash, sering kali SHA-256, untuk mengurangi ukuran request dan memanfaatkan cache. Sementara itu, daftar persisted query yang didaftarkan sebelumnya dapat berfungsi sebagai allowlist: hanya operasi yang telah disetujui yang diterima. Perbedaan ini penting karena penghematan bandwidth tidak otomatis menjadi kontrol keamanan.

Manfaat yang Bisa Didapat

• Request lebih kecil. Klien dapat mengirim ID operasi alih-alih teks GraphQL yang panjang. Dampaknya paling terasa pada operasi besar atau jaringan dengan latensi tinggi.
• Perilaku klien lebih terkontrol. Tim dapat meninjau operasi yang disertakan dalam rilis aplikasi dan mendeteksi perubahan yang tidak diharapkan.
• Permukaan serangan dapat dipersempit. Dengan allowlist yang benar-benar ditegakkan, server bisa menolak operasi arbitrer yang tidak terdaftar.
• Observabilitas lebih jelas. Nama operasi dan ID yang stabil membantu pengelompokan metrik, log, serta analisis penggunaan.

Namun, persisted queries tidak menggantikan autentikasi, otorisasi, validasi input, pembatasan kompleksitas query, ataupun rate limiting. Operasi yang sudah terdaftar tetap dapat berbahaya bila mengembalikan data tanpa memeriksa hak akses pengguna.

APQ atau Allowlist: Pilih Sesuai Tujuan

APQ cocok ketika sasaran utamanya adalah mengurangi ukuran request dan latensi tanpa mengubah alur pengembangan secara drastis. Pada implementasi umum, klien mengirim hash; jika server belum mengenalinya, klien dapat mengirim teks operasi agar hash tersebut disimpan. Mekanisme pendaftaran saat runtime ini berarti operasi baru berpotensi masuk ke cache, sehingga APQ saja bukan allowlist keamanan.

Allowlist lebih ketat. Operasi yang diizinkan didaftarkan saat proses build atau rilis, lalu server menolak operasi yang tidak ada dalam daftar. Sebagian platform juga dapat mewajibkan klien mengirim ID saja, bukan teks operasi. Mode paling ketat ini perlu diterapkan bertahap karena aplikasi versi lama yang masih mengirim dokumen GraphQL mentah dapat gagal setelah kebijakan diaktifkan.

Langkah Implementasi yang Praktis

1. Inventarisasi operasi aktif. Kumpulkan query, mutation, dan subscription yang benar-benar digunakan oleh seluruh klien yang masih didukung. Sertakan aplikasi web, seluler, dan integrasi pihak ketiga yang sah.
2. Bangun manifest pada pipeline rilis. Buat daftar operasi dari kode sumber dan validasi setiap operasi terhadap skema GraphQL yang sesuai. Jangan mengandalkan pendaftaran otomatis dari request produksi bila tujuannya adalah allowlisting.
3. Mulai dengan mode audit. Catat operasi yang belum terdaftar tanpa langsung memblokirnya. Bandingkan log dengan versi aplikasi aktif untuk menemukan klien yang tertinggal atau operasi yang terlewat.
4. Uji kompatibilitas. Periksa bahwa tool klien tidak mengubah dokumen operasi secara tak terduga—misalnya dengan menambahkan field tertentu—dan pastikan manifest dibuat dengan proses yang sama seperti request saat runtime.
5. Terapkan penegakan bertahap. Setelah operasi sah tercakup, tolak operasi di luar daftar. Bila memungkinkan, aktifkan persyaratan ID saja setelah seluruh klien mendukungnya dan siapkan prosedur rollback.
6. Pantau dampaknya. Ukur rasio operasi ditolak, latensi, ukuran request, error per versi klien, dan perubahan volume trafik. Simpan log secukupnya tanpa mencatat data sensitif dari variabel atau respons.

Kontrol Keamanan yang Tetap Diperlukan

Jangan menganggap ID operasi sebagai rahasia atau bukti identitas. ID yang sulit ditebak bukan pengganti kontrol akses. Terapkan otorisasi pada tingkat objek dan field, batasi kedalaman serta kompleksitas query, dan beri batas biaya untuk operasi yang dapat memicu pekerjaan berat. Gunakan rate limiting berdasarkan identitas yang relevan, bukan hanya alamat IP. Panduan keamanan API dan rate limiting API dapat menjadi pelengkap saat menyusun pertahanan berlapis.

Perhatikan pula proses pembaruan daftar. Manifest yang usang dapat membuat fitur baru gagal, sedangkan daftar yang terlalu longgar mengurangi manfaat allowlist. Untuk detail APQ dan persisted queries, lihat dokumentasi Apollo tentang persisted queries. Batasi siapa yang boleh menyetujui operasi, tinjau perubahan dalam code review, dan sinkronkan rilis server dengan versi klien. Untuk layanan multi-tenant, pastikan kebijakan daftar operasi tidak pernah menggantikan pemeriksaan izin tenant dan pengguna.

Kesimpulan

Persisted queries dapat mengurangi ukuran permintaan dan membantu membatasi operasi yang diterima, terutama jika server menerapkan allowlist yang dikelola dengan ketat. Tetap lakukan autentikasi, otorisasi per pengguna dan tenant, validasi input, serta pemantauan; mekanisme ini bukan pengganti kontrol keamanan API lainnya.