Belajar GraphQL - Migrating from REST to GraphQL

#Pendahuluan

Kebanyakan tim yang mengadopsi GraphQL tidak mulai dari nol — mereka punya sistem REST yang sudah berjalan. Episode 47 membahas migrasi dari REST ke GraphQL dengan strategi yang aman dan bertahap, tanpa menghentikan layanan.

Kita akan merencanakan migrasi, menerapkan pola strangler fig, membangun wrapper GraphQL untuk REST, memigrasi client, dan mengevaluasi hasil setelahnya.

#Planning Migration

#Assessment dan Inventory

Migrasi dimulai dari pemetaan, bukan dari kode. Buat inventaris lengkap:

• Daftar endpoint REST dan fungsinya.
• Pola konsumsi client (web, mobile, third-party).
• Data yang dibutuhkan setiap layar/use case.

/users           -> query user(id)
/users/:id/posts -> query user(id) { posts }
/posts           -> query posts(first, after)
POST /posts      -> mutation createPost

Dari sini tentukan prioritas: pilih use case yang paling diuntungkan GraphQL (over-fetching tinggi, N+1 request) untuk dimigrasi pertama, sebagai bukti keberhasilan (quick win).

#Timeline, Risiko, dan Kriteria Sukses

Tentukan timeline realistis (mingguan, bukan "sekali jadi"), identifikasi risiko (client yang tidak bisa diubah, layanan lama yang tidak terurus), dan definisikan kriteria sukses yang terukur: latensi turun sekian persen, jumlah request per tampilan berkurang, dan tidak ada regresi fungsional.

#Incremental Migration

#Strangler Fig Pattern

Pola strangler fig menggeser sistem lama sedikit demi sedikit: sistem baru "menjalari" yang lama sampai akhirnya menggantikan. Untuk GraphQL:

1. Bangun GraphQL server di samping REST.
2. Migrasi satu use case (query/endpoint) pada satu waktu.
3. Client baru memakai GraphQL; yang lama tetap berjalan di REST.
4. Setelah semua pindah, matikan endpoint REST yang tidak terpakai.

#Menjalankan REST dan GraphQL Paralel

Jalankan keduanya bersamaan — ini menghilangkan tekanan "semua atau tidak sama sekali". Gunakan feature flags untuk mengarahkan sebagian client ke GraphQL, lalu memperluas cakupan bertahap. Setiap rilis kecil bisa di-rollback tanpa menghentikan layanan.

#GraphQL Wrapper untuk REST

#RESTDataSource Pattern

Saat REST API tidak bisa diubah, bungkus dengan GraphQL. RESTDataSource (episode 8) menjadi jembatan utama:

Wrapper REST di GraphQL

import { RESTDataSource } from "@apollo/datasource-rest";
 
export class UsersAPI extends RESTDataSource {
  baseURL = "https://legacy-api.example.com/";
 
  async getUser(id) {
    return this.get(`/users/${id}`);
  }
 
  async getPosts(userId) {
    return this.get(`/users/${userId}/posts`);
  }
}

#Mapping dan Error Handling

Pertama lihat bentuk response REST-nya, misalnya dengan curl https://legacy-api.example.com/users/1. Petakan response REST ke bentuk GraphQL di data source atau resolver, dan terjemahkan error REST ke error GraphQL (episode 11). Perhatikan juga caching: REST API lama mungkin sudah punya header cache — manfaatkan di data source.

#Client Migration

#Apollo Client dan Backward Compatibility

Migrasi client dilakukan bertahap:

1. Tambahkan Apollo Client di samping client HTTP lama.
2. Ganti satu layar pada satu waktu.
3. Pertahankan backward compatibility: fitur lama tetap jalan via REST sampai selesai.

A/B testing GraphQL vs REST

const useGraphQL = featureFlags.get("graphql-profile");
 
if (useGraphQL) {
  return useGetUserQuery({ variables: { id } });
}
return useLegacyRestUser(id);

#Rollback Strategy

Siapkan rollback di dua level: feature flag untuk mematikan GraphQL kapan saja, dan versi deploy yang bisa kembali. Komunikasikan jadwal pemindahan ke pengguna internal — perubahan API jarang menimbulkan masalah teknis, sering menimbulkan masalah komunikasi.

#Post-Migration

#Deprecation dan Monitoring

Setelah client berpindah:

• Deprecate endpoint REST: tandai deprecated, pantau traffic-nya, lalu matikan yang sudah tidak dipakai.
• Monitoring kedua sistem: bandingkan error rate dan latensi REST lama versus GraphQL baru selama masa transisi.

#Evaluasi dan Dokumentasi

Bandingkan dengan kriteria sukses: ukur pengurangan round-trip, latensi, dan kemudahan development. Tulis pelajaran yang dipetik (episode 49) dan perbarui dokumentasi — schema GraphQL yang baru menjadi kontrak utama tim sekarang.

#Penutup

Inti yang harus dibawa pulang:

• Mulai dari inventory endpoint dan prioritas use case, bukan dari kode.
• Strangler fig memigrasi sistem lama secara bertahap.
• Jalankan REST dan GraphQL paralel dengan feature flags untuk rollback aman.
• RESTDataSource membungkus REST API yang tidak bisa diubah.
• Migrasi client layar per layar dengan backward compatibility.
• Evaluasi dengan kriteria sukses dan dokumentasikan pelajaran.

Di episode 48 selanjutnya kalian akan mempelajari GraphQL di berbagai bahasa — Graphene dan Strawberry untuk Python, GraphQL Java dan Spring Boot, gqlgen untuk Go, GraphQL Ruby untuk Rails, Lighthouse untuk Laravel, Hot Chocolate untuk .NET, hingga Juniper untuk Rust. GraphQL tidak hanya untuk JavaScript!