GraphQL Complete Guide — Panduan Lengkap API Query Language Modern

Pengenalan: Revolusi API Development dengan GraphQL

GraphQL menKamui perubahan paradigma fundamental dalam cara kita merancang dan menggunakan API. Diperkenalkan oleh Facebook (sekarang Meta) pada tahun 2015, GraphQL telah menjadi alternatif yang kuat untuk arsitektur REST, memberikan fleksibilitas, efisiensi, dan pengalaman pengembang yang jauh lebih baik.

Berbeda dengan REST yang menggunakan multiple endpoint dengan bentuk respons tetap, GraphQL menggunakan satu endpoint dengan query language yang powerful. Client dapat meminta data persis yang mereka butuhkan, menghilangkan masalah over-fetching dan under-fetching yang umum terjadi di REST API. Dalam panduan lengkap ini, kita akan menjelajahi setiap aspek GraphQL mulai dari konsep dasar hingga pola lanjutan dan strategi deployment produksi.

Daftar Isi

• GraphQL Fundamentals
• Type System dan Schema
• Queries
• Mutations
• Subscriptions
• Resolvers dan Field Resolution
• Error Handling
• Caching Strategies
• N+1 Problem dan DataLoader
• Authentication dan Authorization
• Real-World Patterns
• Performance Optimization
• Kesimpulan

GraphQL Fundamentals

REST vs GraphQL

REST (Multiple Endpoints):
GET /api/users/1           → { id, name, email, address, posts }
GET /api/users/1/posts     → [{ id, title, content }]
GET /api/posts/1/comments  → [{ id, text, author }]
Problem: Over-fetching (menerima data yang tidak dibutuhkan)

GraphQL (Single Endpoint):
POST /graphql
Query: {
  user(id: 1) {
    name
    email
    posts { title }
  }
}
Response: Exactly what was requested!

Keunggulan GraphQL

• Strongly Typed Schema: Self-documenting, dukungan IDE otomatis
• Single Endpoint: API yang lebih sederhana, versioning lebih mudah
• Precise Data Fetching: Ambil hanya data yang Kamu butuhkan
• Powerful Developer Tools: GraphiQL, Apollo DevTools
• Real-time Capabilities: Subscriptions untuk live data updates

Type System dan Schema

Type system mendefinisikan struktur data dan operasi yang tersedia. Ini merupakan kontrak antara client dan server.

Basic Type Definitions

Type definitions mendefinisikan struktur data yang akan digunakan di GraphQL schema. Ini mencakup scalar types (ID, String, Int, Boolean), custom types, input types untuk mutations, dan enums untuk nilai yang terbatas.

# Scalar Types
type User {
  id: ID!                    # Non-nullable
  name: String!
  email: String!
  age: Int
  isActive: Boolean!
  createdAt: String!
}

# List Types
type Post {
  id: ID!
  title: String!
  content: String!
  author: User!              # Reference ke User
  tags: [String!]!           # Non-null list of non-null strings
}

# Input Types (untuk mutations)
input CreatePostInput {
  title: String!
  content: String!
  authorId: ID!
}

# Custom Scalar Types
scalar DateTime
scalar JSON

# Enums
enum PostStatus {
  DRAFT
  PUBLISHED
  ARCHIVED
}

Relationships dan Nested Types

Relationships mendefinisikan bagaimana tipe-tipe berbeda saling terhubung. Kekuatan GraphQL adalah kemampuannya mengambil data terkait (nested) dalam satu query saja.

type User {
  id: ID!
  name: String!
  posts: [Post!]!
  followers: [User!]!
  following: [User!]!
}

type Post {
  id: ID!
  title: String!
  author: User!
  comments: [Comment!]!
  likes: [User!]!
}

type Comment {
  id: ID!
  text: String!
  author: User!
  post: Post!
  createdAt: DateTime!
}

Queries

Queries mengambil data dari GraphQL server. Clients dapat menentukan dengan tepat data apa yang mereka butuhkan, menghilangkan masalah over/under-fetching dari REST.

Simple Queries

Simple queries adalah query dasar yang mengambil data tanpa variabel atau logic kompleks. Setiap query menerima arguments tertentu dan mengembalikan field-field yang diminta client.

# Query Definition
type Query {
  user(id: ID!): User
  posts(limit: Int, offset: Int): [Post!]!
  searchPosts(query: String!): [Post!]!
}

# Client Query
query GetUser {
  user(id: "1") {
    id
    name
    email
  }
}

# Query dengan Arguments
query GetPosts {
  posts(limit: 10, offset: 0) {
    id
    title
    author {
      name
    }
  }
}

# Aliases (request field yang sama dengan nama berbeda)
query GetUserData {
  currentUser: user(id: "1") {
    name
    email
  }
  otherUser: user(id: "2") {
    name
    email
  }
}

# Fragments (bagian query yang dapat digunakan kembali)
fragment UserFields on User {
  id
  name
  email
  createdAt
}

query GetUsers {
  user1: user(id: "1") {
    ...UserFields
  }
  user2: user(id: "2") {
    ...UserFields
  }
}

Complex Queries

Complex queries menggabungkan multiple features seperti variables, aliases, fragments, dan directives untuk pola data fetching yang powerful.

query GetUserWithPosts {
  user(id: "1") {
    id
    name
    email
    posts {
      id
      title
      comments {
        text
        author {
          name
        }
      }
    }
  }
}

# Query dengan variables
query GetUserPosts($userId: ID!, $limit: Int!) {
  user(id: $userId) {
    name
    posts(limit: $limit) {
      title
      content
    }
  }
}

# JSON variables:
{
  "userId": "1",
  "limit": 5
}

# Directives
query GetPostsConditional($includeTags: Boolean!) {
  posts {
    id
    title
    tags @include(if: $includeTags)
  }
}

# Directive @skip
query GetPosts($skipComments: Boolean!) {
  posts {
    id
    title
    comments @skip(if: $skipComments) {
      text
    }
  }
}

Mutations

Mutations memodifikasi state server dan mengembalikan data yang diupdate. Mereka adalah setara GraphQL dari POST/PUT/DELETE di REST.

Basic Mutations

Basic mutations adalah operasi dasar untuk create, update, atau delete data. Setiap mutation didefinisikan dalam tipe Mutation dan menerima input object yang berisi data yang dibutuhkan.

type Mutation {
  createUser(input: CreateUserInput!): User!
  updateUser(id: ID!, input: UpdateUserInput!): User!
  deleteUser(id: ID!): Boolean!
  createPost(input: CreatePostInput!): Post!
}

input CreateUserInput {
  name: String!
  email: String!
  password: String!
}

input UpdateUserInput {
  name: String
  email: String
  age: Int
}

# Client mutation
mutation CreateNewUser {
  createUser(input: {
    name: "John Doe"
    email: "[email protected]"
    password: "secure123"
  }) {
    id
    name
    email
    createdAt
  }
}

# Mutation dengan variables
mutation UpdateUserProfile($id: ID!, $input: UpdateUserInput!) {
  updateUser(id: $id, input: $input) {
    id
    name
    email
    updatedAt
  }
}

# Multiple Mutations
mutation CreateAndUpdate {
  createPost(input: {
    title: "New Post"
    content: "Content"
    authorId: "1"
  }) {
    id
    title
  }
  updateUser(id: "1", input: { name: "Updated Name" }) {
    id
    name
  }
}

Subscriptions

Subscriptions memungkinkan client menerima real-time updates dari server menggunakan WebSocket. Berbeda dengan queries yang one-shot dan mutations yang memodifikasi data, subscriptions menjalin koneksi persistent untuk push data ke client kapan pun ada event tertentu terjadi.

Real-Time Subscriptions

type Subscription {
  postCreated: Post!
  userFollowed(userId: ID!): User!
  commentAdded(postId: ID!): Comment!
}

# Client Subscription
subscription OnPostCreated {
  postCreated {
    id
    title
    author {
      name
    }
  }
}

# Listen untuk event tertentu
subscription OnUserFollowed($userId: ID!) {
  userFollowed(userId: $userId) {
    id
    name
    followers {
      name
    }
  }
}

Resolvers dan Field Resolution

Basic Resolvers (Node.js dengan Apollo Server)

Resolvers adalah function yang mengembalikan data untuk setiap field di schema. Setiap type dan field dapat memiliki resolver sendiri yang menentukan bagaimana data diambil atau diproses.

const typeDefs = `
  type User {
    id: ID!
    name: String!
    email: String!
    posts: [Post!]!
  }
  
  type Post {
    id: ID!
    title: String!
    author: User!
  }
  
  type Query {
    user(id: ID!): User
    posts: [Post!]!
  }
`;

const resolvers = {
  Query: {
    user: (parent, args, context, info) => {
      return users.find(u => u.id === args.id);
    },
    posts: () => {
      return posts;
    }
  },
  User: {
    posts: (parent) => {
      // parent adalah user object
      return posts.filter(p => p.authorId === parent.id);
    }
  },
  Post: {
    author: (parent) => {
      return users.find(u => u.id === parent.authorId);
    }
  }
};

Context dan Dependency Injection

Context adalah object yang diteruskan ke setiap resolver dan berisi informasi global seperti authenticated user, database instances, atau data sources. Ini memungkinkan dependency injection dan state sharing antar resolvers.

const server = new ApolloServer({
  typeDefs,
  resolvers,
  context: async ({ req }) => {
    // Ambil user dari JWT token
    const token = req.headers.authorization || '';
    const user = await verifyToken(token);
    
    return {
      user,
      dataSources: {
        userAPI: new UserAPI(),
        postAPI: new PostAPI()
      }
    };
  }
});

// Menggunakan context di resolver
const resolvers = {
  Query: {
    me: (parent, args, context) => {
      if (!context.user) {
        throw new Error('Not authenticated');
      }
      return context.user;
    },
    posts: (parent, args, context) => {
      return context.dataSources.postAPI.getPosts();
    }
  }
};

Error Handling

GraphQL Error Handling

Error handling di GraphQL dapat dilakukan dengan returning union types yang meng-include error type, atau dengan throwing exceptions. Client menerima error details dalam response beserta error path dan code untuk debugging.

# Custom error types
type Error {
  message: String!
  code: String!
  path: [String!]
}

type User {
  id: ID!
  name: String!
}

union UserResult = User | Error

type Query {
  user(id: ID!): UserResult!
}

// Error handling dalam resolvers
const resolvers = {
  Query: {
    user: async (parent, args) => {
      try {
        const user = await db.users.findById(args.id);
        if (!user) {
          return {
            __typename: 'Error',
            message: 'User not found',
            code: 'USER_NOT_FOUND'
          };
        }
        return {
          __typename: 'User',
          ...user
        };
      } catch (error) {
        throw new GraphQLError('Database error', {
          extensions: {
            code: 'INTERNAL_SERVER_ERROR',
            originalError: error
          }
        });
      }
    }
  }
};

// Error formatting
const server = new ApolloServer({
  typeDefs,
  resolvers,
  formatError: (error) => {
    console.error(error);
    return {
      message: error.message,
      code: error.extensions?.code,
      path: error.path
    };
  }
});

Caching Strategies

HTTP Caching Headers

HTTP caching headers menggunakan standard cache-control untuk memberitahu browser atau CDN tentang durasi cache. Gunakan max-age untuk public data dan private, no-cache untuk authenticated/sensitive data.

const resolvers = {
  Query: {
    posts: (parent, args, context, info) => {
      // Set cache headers
      context.res.set('Cache-Control', 'max-age=300'); // 5 menit
      return posts;
    },
    user: (parent, args, context) => {
      // Private data - no cache
      context.res.set('Cache-Control', 'private, no-cache');
      return user;
    }
  }
};

Response Caching

Response caching menyimpan hasil query di memory atau cache store untuk menghindari kalkulasi ulang atau database query berulang. Strategi ini sangat efektif untuk data yang jarang berubah atau saat ada traffic tinggi.

const cacheMap = new Map();

const resolvers = {
  Query: {
    posts: async (parent, args) => {
      const cacheKey = `posts:${JSON.stringify(args)}`;
      
      if (cacheMap.has(cacheKey)) {
        return cacheMap.get(cacheKey);
      }
      
      const posts = await fetchFromDB();
      cacheMap.set(cacheKey, posts);
      
      // Clear cache after 5 minutes
      setTimeout(() => cacheMap.delete(cacheKey), 5 * 60 * 1000);
      
      return posts;
    }
  }
};

N+1 Problem dan DataLoader

The N+1 Problem

N+1 problem terjadi ketika resolver field melakukan query database untuk setiap parent object, menyebabkan N+1 total queries. DataLoader menyelesaikan ini dengan batching requests dalam satu event loop untuk hanya 1 query bulk ke database.

// ✗ TIDAK BAGUS: N+1 Query Problem
const resolvers = {
  Query: {
    users: async () => {
      return await db.users.find();  // 1 query
    }
  },
  User: {
    posts: async (parent) => {
      return await db.posts.find({ userId: parent.id });  // N queries!
    }
  }
};

// ✓ BAGUS: Menggunakan DataLoader
import DataLoader from 'dataloader';

const postsByUserLoader = new DataLoader(async (userIds) => {
  const postsMap = await db.posts.find({ userId: { $in: userIds } });
  return userIds.map(id => postsMap[id]);
});

const resolvers = {
  Query: {
    users: async () => {
      return await db.users.find();
    }
  },
  User: {
    posts: async (parent, args, context) => {
      return context.postsByUserLoader.load(parent.id);
    }
  }
};

// Setup context
const context = () => ({
  postsByUserLoader: new DataLoader(async (userIds) => {
    // Batch query semua posts dalam sekali jalan
    const posts = await db.posts.find({ userId: { $in: userIds } });
    return userIds.map(id => posts.filter(p => p.userId === id));
  })
});

Authentication dan Authorization

JWT Authentication

JWT (JSON Web Token) authentication menggunakan tokens yang di-sign oleh server untuk authenticate requests. Token berisi user information dan dipassing di Authorization header, lalu diverify di context function sebelum resolver dijalankan.

const typeDefs = `
  type User {
    id: ID!
    name: String!
    email: String!
  }
  
  type AuthPayload {
    token: String!
    user: User!
  }
  
  type Mutation {
    login(email: String!, password: String!): AuthPayload!
    signup(name: String!, email: String!, password: String!): AuthPayload!
  }
`;

const resolvers = {
  Mutation: {
    login: async (parent, { email, password }) => {
      const user = await db.users.findOne({ email });
      
      if (!user || !await bcrypt.compare(password, user.password)) {
        throw new Error('Invalid credentials');
      }
      
      const token = jwt.sign(
        { userId: user.id },
        process.env.JWT_SECRET,
        { expiresIn: '7d' }
      );
      
      return { token, user };
    },
    
    signup: async (parent, { name, email, password }) => {
      const existingUser = await db.users.findOne({ email });
      
      if (existingUser) {
        throw new Error('User already exists');
      }
      
      const hashedPassword = await bcrypt.hash(password, 10);
      const user = await db.users.create({
        name,
        email,
        password: hashedPassword
      });
      
      const token = jwt.sign(
        { userId: user.id },
        process.env.JWT_SECRET,
        { expiresIn: '7d' }
      );
      
      return { token, user };
    }
  }
};

Authorization Directives

Directives adalah instruksi yang dapat diterapkan ke fields atau types untuk menambah behavior khusus, seperti @auth untuk check authentication atau @role untuk check user permissions sebelum resolver dieksekusi.

const typeDefs = `
  directive @auth on FIELD_DEFINITION
  directive @role(role: String!) on FIELD_DEFINITION
  
  type Query {
    me: User @auth
    adminPanel: String @role(role: \"ADMIN\")
  }
`;

const authDirective = {
  '@auth': (resolve) => async (...args) => {
    const context = args[2];
    if (!context.user) {
      throw new Error('Not authenticated');
    }
    return resolve(...args);
  }
};

const roleDirective = {
  '@role': (resolve, parent, args) => async (...resolveArgs) => {
    const context = resolveArgs[2];
    if (!context.user || context.user.role !== args.role) {
      throw new Error('Insufficient permissions');
    }
    return resolve(...resolveArgs);
  }
};

Real-World Patterns

Connection-based Pagination (Relay Cursor Pagination)

Connection-based pagination menggunakan cursor untuk navigasi antar halaman, bukan offset. Pendekatan ini lebih robust karena cursor tidak terpengaruh oleh insertion atau deletion data saat pagination berlangsung, menjadikannya ideal untuk data yang frequently updated.

type PageInfo {
  hasNextPage: Boolean!
  hasPreviousPage: Boolean!
  startCursor: String
  endCursor: String
}

type PostEdge {
  node: Post!
  cursor: String!
}

type PostConnection {
  edges: [PostEdge!]!
  pageInfo: PageInfo!
  totalCount: Int!
}

type Query {
  posts(first: Int, after: String): PostConnection!
}

Aggregations dan Analytics

Aggregations dan analytics fields mengembalikan ringkasan data atau statistik daripada record individual. Pattern ini berguna untuk dashboard, reporting, dan analytical queries yang perlu aggregate data dari multiple records.

type PostStats {
  totalPosts: Int!
  avgCommentsPerPost: Float!
  mostLikedPost: Post
  tagCloud: [TagCount!]!
}

type Query {
  stats: PostStats!
}

Performance Optimization

Query Complexity Analysis

Query complexity analysis menghitung weighted score dari setiap query berdasarkan nesting depth dan field access, lalu membuat request jika score melebihi limit. Ini mencegah malicious queries yang ingin membanjiri server dengan queries yang sangat expensive.

const { createComplexityLimitRule } = require('graphql-validation-complexity');

const server = new ApolloServer({
  typeDefs,
  resolvers,
  validationRules: [
    createComplexityLimitRule({
      maxComplexity: 1000,
      variables: {},
      onComplete: (complexity) => {
        console.log('Query complexity:', complexity);
      }
    })
  ]
});

Kesimpulan

GraphQL merupakan tool yang powerful untuk mengubah cara kita membangun dan mengonsumsi APIs. Dengan strong type system, precise data fetching, dan real-time capabilities, GraphQL memungkinkan development yang lebih efisien dan scalable. Menguasai GraphQL—dari schema design hingga advanced patterns dan optimization techniques—membuat Kamu menjadi aset berharga di landscape API development modern.

Checklist untuk Production GraphQL API:

• ✓ Schema yang well-designed dengan types dan relationships yang jelas
• ✓ Error handling dan validation yang tepat
• ✓ Mechanisms authentication dan authorization
• ✓ DataLoader untuk mengatasi N+1 problems
• ✓ Query complexity limits untuk mencegah penyalahgunaan
• ✓ Caching strategies (HTTP dan response caching)
• ✓ Monitoring dan logging
• ✓ Documentation dengan comments dan descriptions
• ✓ Testing (unit, integration, schema validation)
• ✓ Performance profiling dan optimization