REST sudah jadi standar API selama bertahun-tahun, tapi seiring aplikasi makin kompleks, keterbatasannya mulai terasa. Over-fetching (menerima data yang tidak kamu butuhkan), under-fetching (perlu multiple request untuk data terkait), dan versi API yang berantakan adalah masalah yang sering muncul. GraphQL lahir untuk menyelesaikan masalah ini. Di artikel ini aku bakal bahas GraphQL dari konsep dasar sampai implementasi: schema-first approach, queries, mutations, subscriptions, resolvers, dan cara setup Apollo Server di backend serta Apollo Client di frontend. Aku juga akan membandingkan GraphQL dengan REST agar kamu tahu kapan harus pakai yang mana. ## GraphQL vs REST: Apa Bedanya? Sebelum masuk ke kode, mari pahami perbedaan fundamental. ### REST REST berbasis resource. Setiap resource punya endpoint sendiri: ``` GET /api/users/1 -> detail user GET /api/users/1/posts -> post dari user GET /api/posts/5/comments -> komentar dari post ``` Masalahnya, kalau kamu mau menampilkan profil user beserta 3 post terbaru dan jumlah komentar tiap post, kamu butuh minimal 3 request. Atau backend bikin endpoint custom `/api/users/1/with-posts-and-comments` yang tidak scalable. Selain itu, `GET /api/users/1` mungkin mengembalikan 20 field padahal kamu cuma butuh `name` dan `avatar`. Ini disebut **over-fetching**. ### GraphQL GraphQL memberi kamu satu endpoint (`/graphql`) dan kamu mintu persis data yang kamu butuhkan: ```graphql query { user(id: 1) { name avatar posts(last: 3) { title commentCount } } } ``` Satu request, dapat persis apa yang kamu mau. Tidak ada over-fetching, tidak ada under-fetching. Ringkasan perbedaan: | Aspek | REST | GraphQL | |-------|------|---------| | Endpoint | Banyak (`/users`, `/posts`) | Satu (`/graphql`) | | Data shape | Ditentukan server | Ditentukan client | | Over-fetching | Sering terjadi | Tidak ada | | Versioning | `/v1/`, `/v2/` | Schema evolution (deprecation) | | Caching | HTTP caching mudah | Butuh strategi khusus | | Learning curve | Lebih mudah | Lebih curam di awal | GraphQL bukan peluru perak. Untuk API sederhana atau yang sangat caching-heavy (seperti CDN), REST masih pilihan yang baik. Tapi untuk aplikasi dengan data graph yang kompleks - seperti social media, e-commerce dashboard, atau CMS - GraphQL seringkali lebih efisien. ## Schema-First Design GraphQL punya filosofi **schema-first**. Kamu mendefinisikan tipe data dan operasi yang tersedia dulu, baru implement resolvers-nya. Schema ini juga jadi kontrak antara frontend dan backend. ### Tipe Dasar ```graphql type User { id: ID! name: String! email: String! avatar: String age: Int posts: [Post!]! createdAt: DateTime! } type Post { id: ID! title: String! content: String! published: Boolean! author: User! comments: [Comment!]! tags: [String!]! commentCount: Int! } type Comment { id: ID! text: String! author: User! post: Post! createdAt: DateTime! } ``` Penjelasan tanda: - `!` artinya field **non-nullable** - wajib ada nilainya. - `[Post!]!` artinya array yang tidak boleh null, dan tiap elemennya juga tidak boleh null. - `[String!]!` artinya array dari string yang tidak null. - Tanpa `!` berarti field boleh null (opsional). ### Query dan Mutation Type ```graphql type Query { # Ambil semua user dengan pagination users(limit: Int = 10, offset: Int = 0): [User!]! # Ambil user by ID user(id: ID!): User # Cari user by nama searchUsers(name: String!): [User!]! # Ambil post by ID post(id: ID!): Post # Ambil semua post yang published posts(published: Boolean = true): [Post!]! } type Mutation { # Bikin user baru createUser(input: CreateUserInput!): User! # Update user updateUser(id: ID!, input: UpdateUserInput!): User! # Hapus user deleteUser(id: ID!): Boolean! # Bikin post createPost(input: CreatePostInput!): Post! # Tambah komentar addComment(postId: ID!, text: String!): Comment! } type Subscription { # Real-time update saat post baru dibuat postCreated: Post! # Real-time update komentar di post tertentu commentAdded(postId: ID!): Comment! } # Input types untuk mutation input CreateUserInput { name: String! email: String! avatar: String } input UpdateUserInput { name: String email: String avatar: String } input CreatePostInput { title: String! content: String! tags: [String!] published: Boolean = false } ``` `Query` untuk baca data, `Mutation` untuk ubah data, `Subscription` untuk data real-time via WebSocket. ## Setup Apollo Server Apollo Server adalah implementasi GraphQL server untuk Node.js yang paling populer. Mari kita bangun server lengkap dengan resolvers. ### Install ```bash mkdir graphql-api && cd graphql-api npm init -y npm install @apollo/server graphql npm install cors express ``` ### Kode Server ```javascript // server.js import { ApolloServer } from '@apollo/server'; import { startStandaloneServer } from '@apollo/server/standalone'; // 1. Define schema (type definitions) const typeDefs = `#graphql type User { id: ID! name: String! email: String! avatar: String posts: [Post!]! postCount: Int! } type Post { id: ID! title: String! content: String! published: Boolean! author: User! tags: [String!]! likeCount: Int! } type Comment { id: ID! text: String! authorName: String! createdAt: String! } type Query { users: [User!]! user(id: ID!): User posts(published: Boolean): [Post!]! post(id: ID!): Post } type Mutation { createUser(name: String!, email: String!): User! createPost(title: String!, content: String!, authorId: ID!): Post! publishPost(id: ID!): Post! deletePost(id: ID!): Boolean! } input CreateUserInput { name: String! email: String! } `; // 2. Mock data (di production, ganti dengan database) const users = [ { id: '1', name: 'Budi Santoso', email: 'budi@mail.com', avatar: null }, { id: '2', name: 'Sari Indah', email: 'sari@mail.com', avatar: 'avatar2.png' }, { id: '3', name: 'Andi Wijaya', email: 'andi@mail.com', avatar: null }, ]; const posts = [ { id: '1', title: 'Belajar GraphQL', content: 'GraphQL itu keren...', published: true, authorId: '1', tags: ['tech', 'graphql'], likeCount: 42, }, { id: '2', title: 'REST vs GraphQL', content: 'Mana yang lebih baik?', published: true, authorId: '2', tags: ['tech', 'api'], likeCount: 18, }, { id: '3', title: 'Draft Post', content: 'Belum selesai...', published: false, authorId: '1', tags: [], likeCount: 0, }, ]; // 3. Resolvers: fungsi yang mengeksekusi setiap field const resolvers = { Query: { users: () => users, user: (parent, args) => { return users.find(u => u.id === args.id); }, posts: (parent, args) => { if (args.published === undefined) return posts; return posts.filter(p => p.published === args.published); }, post: (parent, args) => { return posts.find(p => p.id === args.id); }, }, Mutation: { createUser: (parent, args) => { const newUser = { id: String(users.length + 1), name: args.name, email: args.email, avatar: null, }; users.push(newUser); return newUser; }, createPost: (parent, args) => { const newPost = { id: String(posts.length + 1), title: args.title, content: args.content, published: false, authorId: args.authorId, tags: [], likeCount: 0, }; posts.push(newPost); return newPost; }, publishPost: (parent, args) => { const post = posts.find(p => p.id === args.id); if (!post) throw new Error('Post tidak ditemukan'); post.published = true; return post; }, deletePost: (parent, args) => { const index = posts.findIndex(p => p.id === args.id); if (index === -1) return false; posts.splice(index, 1); return true; }, }, // Field resolvers: resolve relasi antar type User: { posts: (parent) => { return posts.filter(p => p.authorId === parent.id); }, postCount: (parent) => { return posts.filter(p => p.authorId === parent.id).length; }, }, Post: { author: (parent) => { return users.find(u => u.id === parent.authorId); }, }, }; // 4. Start server const server = new ApolloServer({ typeDefs, resolvers, }); const { url } = await startStandaloneServer(server, { listen: { port: 4000 }, }); console.log(`Server berjalan di ${url}`); ``` Jalankan dengan `node server.js`. Buka browser ke `http://localhost:4000` dan kamu akan lihat Apollo Sandbox - sebuah playground interaktif untuk mencoba query. ## Contoh Query dan Mutation ### Query: Baca Data Ambil daftar user beserta jumlah post mereka: ```graphql query GetUsersWithPostCount { users { id name email postCount } } ``` Response: ```json { "data": { "users": [ { "id": "1", "name": "Budi Santoso", "email": "budi@mail.com", "postCount": 2 }, { "id": "2", "name": "Sari Indah", "email": "sari@mail.com", "postCount": 1 }, { "id": "3", "name": "Andi Wijaya", "email": "andi@mail.com", "postCount": 0 } ] } } ``` Ambil user beserta semua post-nya (nested data dalam satu request): ```graphql query GetUserWithPosts($userId: ID!) { user(id: $userId) { name email posts { title published likeCount tags } } } ``` Variables: ```json { "userId": "1" } ``` ### Mutation: Ubah Data Bikin user baru: ```graphql mutation CreateNewUser { createUser(name: "Dewi Lestari", email: "dewi@mail.com") { id name email } } ``` Bikin dan publish post: ```graphql mutation CreateAndPublishPost { createPost( title: "Judul Baru" content: "Isi konten" authorId: "2" ) { id title } } mutation PublishIt { publishPost(id: "4") { id title published } } ``` ### Fragments: Reusable Field Sets Kalau kamu sering butuh field yang sama, pakai fragment: ```graphql fragment UserBasic on User { id name email } fragment PostSummary on Post { id title likeCount } query GetDashboard { users { ...UserBasic posts { ...PostSummary } } } ``` Fragment membuat query kamu lebih bersih dan mudah dirawat. ## Subscription: Real-Time Data Subscription memungkinkan kamu menerima update real-time via WebSocket. Cocok untuk chat, notifikasi, atau live feed. ### Setup Subscription di Server ```bash npm install graphql-ws ws ``` ```javascript // server.js (update untuk support subscription) import { ApolloServer } from '@apollo/server'; import { expressMiddleware } from '@apollo/server/express4'; import { makeExecutableSchema } from '@graphql-tools/schema'; import { WebSocketServer } from 'ws'; import { useServer } from 'graphql-ws/lib/use/ws'; import express from 'express'; import { createServer } from 'http'; const typeDefs = `#graphql type Post { id: ID! title: String! content: String! } type Query { posts: [Post!]! } type Mutation { createPost(title: String!, content: String!): Post! } type Subscription { postCreated: Post! } `; const posts = []; const subscribers = []; // Pub/Sub sederhana const publish = (event, payload) => { subscribers.forEach(fn => fn(event, payload)); }; const subscribe = (fn) => { subscribers.push(fn); return () => { const index = subscribers.indexOf(fn); if (index > -1) subscribers.splice(index, 1); }; }; const resolvers = { Query: { posts: () => posts, }, Mutation: { createPost: (parent, args) => { const post = { id: String(posts.length + 1), title: args.title, content: args.content, }; posts.push(post); publish('postCreated', post); return post; }, }, Subscription: { postCreated: { subscribe: () => { // Return an AsyncIterator const queue = []; let pushToQueue; const getNext = () => new Promise(resolve => { pushToQueue = resolve; }); const unsubscribe = subscribe((event, payload) => { if (event === 'postCreated') { pushToQueue({ postCreated: payload }); } }); return { [Symbol.asyncIterator]() { return { next: async () => { const value = await getNext(); return { value, done: false }; }, return() { unsubscribe(); return { value: undefined, done: true }; }, }; }, }; }, }, }, }; // ... setup HTTP + WebSocket server ``` Di production, pakai library seperti `graphql-subscriptions` dengan Redis Pub/Sub untuk scaling ke multiple server. ### Pakai Subscription di Client ```javascript import { gql } from '@apollo/client'; const POST_CREATED_SUBSCRIPTION = gql` subscription OnPostCreated { postCreated { id title content } } `; // Dengan Apollo Client const { data, loading } = useSubscription(POST_CREATED_SUBSCRIPTION); // data akan otomatis update setiap kali post baru dibuat ``` ## Apollo Client di Frontend Di sisi frontend, Apollo Client menangani caching, query execution, dan state management. Kalau kamu pakai React, integrasinya sangat mulus. ### Install ```bash npm install @apollo/client graphql ``` ### Setup Client ```javascript // src/apollo-client.js import { ApolloClient, InMemoryCache, createHttpLink } from '@apollo/client'; import { setContext } from '@apollo/client/link/context'; const httpLink = createHttpLink({ uri: 'http://localhost:4000/graphql', }); // Tambahkan auth token ke setiap request const authLink = setContext((_, { headers }) => { const token = localStorage.getItem('token'); return { headers: { ...headers, authorization: token ? `Bearer ${token}` : '', }, }; }); export const client = new ApolloClient({ link: authLink.concat(httpLink), cache: new InMemoryCache(), }); ``` ### Pakai di React ```jsx // src/App.jsx import { ApolloProvider, useQuery, useMutation, gql } from '@apollo/client'; import { client } from './apollo-client'; const GET_USERS = gql` query GetUsers { users { id name email postCount } } `; const CREATE_USER = gql` mutation CreateUser($name: String!, $email: String!) { createUser(name: $name, email: $email) { id name email } } `; function UserList() { const { loading, error, data } = useQuery(GET_USERS); if (loading) return

; if (error) return

Error: {error.message}

; return (

{user.name} ({user.email}) - {user.postCount} posts

); } function AddUserForm() { const [createUser, { loading }] = useMutation(CREATE_USER, { // Update cache otomatis setelah mutation refetchQueries: [{ query: GET_USERS }], }); const handleSubmit = async (e) => { e.preventDefault(); const formData = new FormData(e.target); await createUser({ variables: { name: formData.get('name'), email: formData.get('email'), }, }); e.target.reset(); }; return ( ); } export default function App() { return (

Blog Dashboard

); } ``` Perhatikan `refetchQueries` - setelah mutation berhasil, Apollo Client otomatis re-fetch query `GET_USERS` sehingga UI update tanpa perlu refresh halaman. Apollo Client juga punya normalized cache yang cerdas, jadi data yang sudah di-fetch tidak perlu di-request ulang. ### Optimistic UI Apollo Client mendukung **optimistic updates** - UI diupdate langsung sebelum server merespons, memberikan sensasi instan: ```javascript const [addComment] = useMutation(ADD_COMMENT, { optimisticResponse: ({ variables }) => ({ __typename: 'Mutation', addComment: { __typename: 'Comment', id: 'temp-id', text: variables.text, authorName: 'Kamu', createdAt: new Date().toISOString(), }, }), update: (cache, { data }) => { cache.modify({ fields: { comments: (existing = []) => [...existing, data.addComment], }, }); }, }); ``` Kalau server gagal, Apollo otomatis rollback ke state sebelumnya. ## Best Practices Beberapa praktik yang akan membuat GraphQL API kamu lebih baik: **1. Pagination dengan Cursor** Jangan return semua data sekaligus. Pakai cursor-based pagination: ```graphql type Query { posts(first: Int = 10, after: String): PostConnection! } type PostConnection { edges: [PostEdge!]! pageInfo: PageInfo! } type PostEdge { node: Post! cursor: String! } type PageInfo { hasNextPage: Boolean! endCursor: String } ``` **2. Input Types untuk Mutation** Daripada banyak parameter terpisah, kumpulkan jadi input type: ```graphql input CreatePostInput { title: String! content: String! tags: [String!] published: Boolean } type Mutation { createPost(input: CreatePostInput!): Post! } ``` **3. Error Handling** GraphQL mengembalikan HTTP 200 bahkan saat ada error. Error ada di field `errors`: ```json { "errors": [ { "message": "User tidak ditemukan", "locations": [{ "line": 2, "column": 3 }], "path": ["user"], "extensions": { "code": "NOT_FOUND" } } ], "data": { "user": null } } ``` **4. Authorization di Resolver** ```javascript const resolvers = { Mutation: { deletePost: (parent, args, context) => { if (!context.user) { throw new Error('Anda harus login'); } const post = posts.find(p => p.id === args.id); if (post.authorId !== context.user.id) { throw new Error('Anda tidak punya akses'); } // hapus post }, }, }; ``` **5. Depth Limiting** Query yang terlalu dalam bisa menyebabkan DoS. Batasi depth: ```javascript import depthLimit from 'graphql-depth-limit'; const server = new ApolloServer({ typeDefs, resolvers, validationRules: [depthLimit(5)], }); ``` ## Kapan Pakai GraphQL vs REST? Pakai **GraphQL** kalau: - Aplikasi kamu punya banyak relasi data yang complex. - Frontend butuh data dengan shape yang berbeda-beda di tiap halaman. - Kamu punya multiple client (web, mobile, dll) yang butuh data berbeda. - Real-time updates penting (subscriptions). - Tim frontend dan backend bekerja secara terpisah. Pakai **REST** kalau: - API kamu sederhana dan resource-oriented. - HTTP caching lewat CDN sangat penting. - Kamu butuh interoperabilitas dengan sistem yang sudah ada. - Tim kamu lebih familiar dengan REST. - Kamu bikin public API yang akan dipakai banyak orang. Banyak organisasi akhirnya pakai **keduanya** - REST untuk API publik dan GraphQL untuk internal dashboard. Tidak harus pilih satu. ## Kesimpulan GraphQL menawarkan cara yang lebih fleksibel dan efisien untuk mendesain API. Dengan satu endpoint, client bisa minta persis data yang dibutuhkan - tidak lebih, tidak kurang. Yang perlu kamu kuasai: - **Schema-first design** - definisikan type dan operasi dulu sebelum implementasi. - **Queries, mutations, subscriptions** - tiga operasi dasar GraphQL. - **Resolvers** - function yang menghubungkan schema dengan data source. - **Apollo Server** untuk backend dan **Apollo Client** untuk frontend. - **Fragments** untuk reusable query parts. - **Caching dan optimistic UI** di sisi client. - **Best practices**: pagination, authorization, depth limiting. Mulai dari project kecil: bikin satu entity dengan query dan mutation, connect ke database, lalu tambahkan subscription untuk real-time. Setelah nyaman dengan polanya, expand ke use case yang lebih kompleks. GraphQL bukan solusi untuk semua masalah API, tapi untuk banyak kasus modern - terutama yang melibatkan data graph yang kompleks - GraphQL bisa menghemat banyak waktu dan bandwidth. Frontend developer kamu akan berterima kasih karena tidak perlu lagi memohon backend untuk bikin endpoint baru tiap kali butuh field tambahan.