Back to BlogJAY KYE

GraphQL vs REST API: Architecture Deep Dive and Practical Comparison

Jay Kye
14 min read

Comprehensive comparison of GraphQL and REST API architectures. Understanding resolvers vs handlers, schema-driven development, and when to choose each approach for your backend API.

GraphQLREST APIBackend ArchitectureAPI DesignGoWeb Development

GraphQL vs REST API: Architecture Deep Dive and Practical Comparison

After building REST APIs with both Express.js and Go/Gin, I've been exploring GraphQL as an alternative approach to API design. The architectural differences are fascinating and go much deeper than just "single endpoint vs multiple endpoints."

Architectural Overview

REST API Architecture

Client Request → Router → Handler → Service → Repository → Database
                           ↓
                      JSON Response

GraphQL Architecture

Client Query → GraphQL Server → Resolver Tree → Service → Repository → Database
                 ↓              ↓
              Schema        Field Resolvers

The fundamental difference lies in how data fetching and response construction work at the architectural level.

Core Concept Comparison

1. Schema Definition: Implicit vs Explicit

REST API: Implicit Schema

In REST APIs, the schema exists implicitly in your code:

// models/user.go
type User struct {
    ID        int       `json:"id" db:"id"`
    Email     string    `json:"email" db:"email"`
    Password  string    `json:"-" db:"password"` // Hidden from JSON
    CreatedAt time.Time `json:"created_at" db:"created_at"`
    Posts     []Post    `json:"posts,omitempty"`
}

// handlers/user.go
func GetUser(c *gin.Context) {
    userID := c.Param("id")
    
    user, err := userService.GetByID(userID)
    if err != nil {
        c.JSON(404, gin.H{"error": "User not found"})
        return
    }
    
    // Response structure is determined here
    c.JSON(200, user) // Client must know this structure
}

Issues with Implicit Schema:

  • No single source of truth for API structure
  • Documentation can become outdated
  • Client-server contract is unclear
  • Response structure scattered across handlers

GraphQL: Explicit Schema Definition

GraphQL requires explicit schema definition upfront:

# schema/user.graphql - Single source of truth
type User {
  id: ID!                 # Required field
  email: String!          # Required field  
  name: String            # Optional field
  posts: [Post!]!         # Relationship definition
  createdAt: Time!        # Custom scalar
}

type Post {
  id: ID!
  title: String!
  content: String
  author: User!           # Back-reference
}

type Query {
  user(id: ID!): User           # Input/output contract
  users(limit: Int = 10): [User!]!
}

type Mutation {
  createUser(input: CreateUserInput!): User!
  updateUser(id: ID!, input: UpdateUserInput!): User!
}

Benefits of Explicit Schema:

  • Single source of truth for API structure
  • Self-documenting API with introspection
  • Type safety at compile time
  • Clear contracts between client and server

2. Model Generation: Manual vs Automatic

REST API: Manual Model Definition

// You define models manually
type User struct {
    ID        int       `json:"id" db:"id"`
    Email     string    `json:"email" db:"email"`
    Password  string    `json:"-" db:"password"`
    CreatedAt time.Time `json:"created_at" db:"created_at"`
}

type CreateUserRequest struct {
    Email    string `json:"email" binding:"required,email"`
    Password string `json:"password" binding:"required,min=8"`
}

type UserResponse struct {
    ID        int       `json:"id"`
    Email     string    `json:"email"`
    CreatedAt time.Time `json:"created_at"`
    // Password intentionally omitted
}

GraphQL: Schema-Generated Models

// internal/graphql/model/models_gen.go (Auto-generated from schema)
type User struct {
    ID        string     `json:"id"`
    Email     string     `json:"email"`
    Name      *string    `json:"name"`      // Pointer for optional fields
    Posts     []*Post    `json:"posts"`
    CreatedAt time.Time  `json:"createdAt"`
}

type CreateUserInput struct {
    Email    string  `json:"email"`
    Name     *string `json:"name"`
    Password string  `json:"password"`
}

// Database model remains separate
type UserDB struct {
    ID           int       `db:"id"`
    Email        string    `db:"email"`
    PasswordHash string    `db:"password_hash"`
    Name         *string   `db:"name"`
    CreatedAt    time.Time `db:"created_at"`
}

Key Differences:

  • REST: Database model ≈ API model (often the same struct)
  • GraphQL: Schema model ≠ Database model (clear separation)

3. Request Handling: Handlers vs Resolvers

REST API: Handler-Based Processing

// handlers/user.go
func GetUser(c *gin.Context) {
    userID := c.Param("id")
    
    // Load ALL user data at once
    user, err := userService.GetByIDWithPosts(userID)
    if err != nil {
        c.JSON(404, gin.H{"error": "User not found"})
        return
    }
    
    // Always return complete object
    c.JSON(200, user) // Client gets everything, needed or not
}

func GetUsers(c *gin.Context) {
    users, err := userService.GetAllWithPosts() // N+1 problem!
    if err != nil {
        c.JSON(500, gin.H{"error": "Internal error"})
        return
    }
    c.JSON(200, users)
}

REST Handler Characteristics:

  • Monolithic: One handler processes entire request
  • All-or-nothing: Returns complete predefined structure
  • Over-fetching: Client gets data it might not need
  • N+1 problems: Often loads related data unnecessarily

GraphQL: Resolver-Based Processing

// resolver/query.resolvers.go
func (r *queryResolver) User(ctx context.Context, id string) (*model.User, error) {
    // Only load basic user info
    userDB, err := r.userService.GetByID(id)
    if err != nil {
        return nil, err
    }
    
    // Convert DB model to GraphQL model
    return &model.User{
        ID:        strconv.Itoa(userDB.ID),
        Email:     userDB.Email,
        Name:      userDB.Name,
        CreatedAt: userDB.CreatedAt,
        // Posts field will be resolved separately if requested
    }, nil
}

// resolver/user.resolvers.go - Field-level resolvers
func (r *userResolver) Posts(ctx context.Context, obj *model.User) ([]*model.Post, error) {
    // This only executes if 'posts' field is requested!
    if obj == nil {
        return nil, nil
    }
    
    userID, _ := strconv.Atoi(obj.ID)
    postsDB, err := r.postService.GetByUserID(userID)
    if err != nil {
        return nil, err
    }
    
    // Convert to GraphQL models
    posts := make([]*model.Post, len(postsDB))
    for i, post := range postsDB {
        posts[i] = &model.Post{
            ID:      strconv.Itoa(post.ID),
            Title:   post.Title,
            Content: post.Content,
        }
    }
    return posts, nil
}

func (r *userResolver) Email(ctx context.Context, obj *model.User) (*string, error) {
    // Field-level authorization
    currentUser := auth.GetUserFromContext(ctx)
    if currentUser == nil || currentUser.ID != obj.ID {
        return nil, nil // Return null for unauthorized access
    }
    return &obj.Email, nil
}

GraphQL Resolver Characteristics:

  • Granular: Each field can have its own resolver
  • Lazy loading: Only requested fields are processed
  • Precise fetching: Client gets exactly what it asks for
  • Field-level control: Authorization and logic per field

Execution Flow Comparison

REST API Execution Flow

1. GET /api/users/1
2. Router matches route → GetUser handler
3. Handler executes complete logic:
   - Load user from database
   - Load user's posts (always)
   - Load user's profile (always)
   - Format response
4. Return complete JSON object
5. Client receives all data (needed or not)

Example REST Response:

{
  "id": 1,
  "email": "user@example.com",
  "name": "John Doe",
  "posts": [
    {"id": 1, "title": "Post 1", "content": "..."},
    {"id": 2, "title": "Post 2", "content": "..."}
  ],
  "profile": {
    "bio": "Software developer",
    "avatar": "https://..."
  },
  "friends": [/* Array of friends */]
}

GraphQL Execution Flow

1. POST /graphql with query
2. GraphQL engine parses query
3. Execute resolver tree:
   - User resolver → basic user data
   - Email field resolver → check permissions
   - Posts field resolver → load posts (only if requested)
4. Construct response matching query structure
5. Client receives precisely requested data

Example GraphQL Query & Response:

# Query - client specifies exactly what it needs
query {
  user(id: "1") {
    email
    posts {
      title
    }
  }
}

{
  "data": {
    "user": {
      "email": "user@example.com",
      "posts": [
        {"title": "Post 1"},
        {"title": "Post 2"}
      ]
    }
  }
}

Project Structure Comparison

REST API Project Structure

internal/
├── handlers/
│   ├── user_handler.go          # GET, POST, PUT, DELETE users
│   ├── post_handler.go          # GET, POST, PUT, DELETE posts
│   └── auth_handler.go          # Login, register, refresh
├── services/
│   ├── user_service.go          # Business logic for users
│   ├── post_service.go          # Business logic for posts
│   └── auth_service.go          # Authentication logic
├── models/
│   ├── user.go                  # User data model
│   ├── post.go                  # Post data model
│   └── auth.go                  # Auth models
├── middleware/
│   ├── auth.go                  # JWT middleware
│   └── cors.go                  # CORS middleware
└── routes/
    └── routes.go                # Route definitions

GraphQL Project Structure

internal/graphql/
├── schema/
│   ├── user.graphql             # User type definitions
│   ├── post.graphql             # Post type definitions
│   └── auth.graphql             # Auth mutations/queries
├── model/
│   └── models_gen.go            # Auto-generated from schema
├── resolver/
│   ├── query.resolvers.go       # Query type resolvers
│   ├── mutation.resolvers.go    # Mutation type resolvers
│   ├── user.resolvers.go        # User field resolvers
│   ├── post.resolvers.go        # Post field resolvers
│   └── resolver.go              # Main resolver struct
├── generated/
│   └── generated.go             # GraphQL server code (auto-generated)
├── middleware/
│   ├── auth.go                  # GraphQL auth middleware
│   └── complexity.go            # Query complexity limiting
└── loader/
    └── dataloader.go            # Batch loading for N+1 prevention

Practical Implementation Examples

REST API Implementation

// Complete REST handler
func GetUserWithPosts(c *gin.Context) {
    userID, _ := strconv.Atoi(c.Param("id"))
    
    // Always load everything
    user, err := db.GetUser(userID)
    if err != nil {
        c.JSON(404, gin.H{"error": "User not found"})
        return
    }
    
    posts, err := db.GetPostsByUserID(userID)
    if err != nil {
        c.JSON(500, gin.H{"error": "Failed to load posts"})
        return
    }
    
    profile, err := db.GetUserProfile(userID)
    if err != nil {
        c.JSON(500, gin.H{"error": "Failed to load profile"})
        return
    }
    
    // Construct response
    response := UserWithPostsResponse{
        ID:      user.ID,
        Email:   user.Email,
        Posts:   posts,
        Profile: profile,
    }
    
    c.JSON(200, response)
}

GraphQL Implementation

// GraphQL resolvers - modular and precise
func (r *queryResolver) User(ctx context.Context, id string) (*model.User, error) {
    userID, _ := strconv.Atoi(id)
    user, err := r.db.GetUser(userID)
    if err != nil {
        return nil, err
    }
    
    return &model.User{
        ID:    id,
        Email: user.Email,
        Name:  user.Name,
    }, nil
}

func (r *userResolver) Posts(ctx context.Context, obj *model.User) ([]*model.Post, error) {
    // Only executes if posts are requested
    userID, _ := strconv.Atoi(obj.ID)
    posts, err := r.db.GetPostsByUserID(userID)
    if err != nil {
        return nil, err
    }
    
    result := make([]*model.Post, len(posts))
    for i, post := range posts {
        result[i] = &model.Post{
            ID:    strconv.Itoa(post.ID),
            Title: post.Title,
        }
    }
    return result, nil
}

func (r *userResolver) Profile(ctx context.Context, obj *model.User) (*model.Profile, error) {
    // Only executes if profile is requested
    userID, _ := strconv.Atoi(obj.ID)
    profile, err := r.db.GetUserProfile(userID)
    if err != nil {
        return nil, err
    }
    
    return &model.Profile{
        Bio:    profile.Bio,
        Avatar: profile.Avatar,
    }, nil
}

Performance Implications

REST API Performance Characteristics

Over-fetching Example:

# Client only needs user email
GET /api/users/1

# But receives everything:
{
  "id": 1,
  "email": "user@example.com",     # ← Only this needed
  "name": "John Doe",              # ← Unnecessary
  "posts": [...],                  # ← Unnecessary (expensive!)
  "profile": {...},                # ← Unnecessary
  "friends": [...]                 # ← Unnecessary (very expensive!)
}

Under-fetching Example:

# Need user info AND their latest posts
GET /api/users/1          # First request
GET /api/users/1/posts    # Second request required

GraphQL Performance Characteristics

Precise Fetching:

# Client specifies exactly what it needs
query {
  user(id: "1") {
    email          # Only email field resolver executes
  }
}

# Or with relationships:
query {
  user(id: "1") {
    email
    posts(limit: 5) {    # Posts resolver executes with limit
      title
    }
  }
}

N+1 Problem Prevention:

// DataLoader pattern in GraphQL
func (r *userResolver) Posts(ctx context.Context, obj *model.User) ([]*model.Post, error) {
    // Batch multiple user post requests
    return r.postLoader.Load(ctx, obj.ID)
}

// Loader batches requests:
// Instead of: SELECT * FROM posts WHERE user_id = 1
//            SELECT * FROM posts WHERE user_id = 2  
//            SELECT * FROM posts WHERE user_id = 3
// 
// Executes: SELECT * FROM posts WHERE user_id IN (1, 2, 3)

Caching Strategies

REST API Caching

// HTTP-level caching is straightforward
func GetUser(c *gin.Context) {
    // Set cache headers
    c.Header("Cache-Control", "public, max-age=300")
    c.Header("ETag", generateETag(user))
    
    // Browser/CDN can cache this response
    c.JSON(200, user)
}

// Redis caching
func GetUserCached(c *gin.Context) {
    userID := c.Param("id")
    cacheKey := fmt.Sprintf("user:%s", userID)
    
    // Try cache first
    if cached := redis.Get(cacheKey); cached != "" {
        c.JSON(200, cached)
        return
    }
    
    // Load from database and cache
    user := loadUser(userID)
    redis.Set(cacheKey, user, 5*time.Minute)
    c.JSON(200, user)
}

GraphQL Caching Challenges

// Query-level caching is complex due to dynamic queries
query1 := `{ user(id: "1") { email } }`
query2 := `{ user(id: "1") { email, name } }`
query3 := `{ user(id: "1") { posts { title } } }`

// Each query is different, traditional HTTP caching doesn't work
// Need sophisticated caching strategies:

// 1. Field-level caching
func (r *userResolver) Email(ctx context.Context, obj *model.User) (*string, error) {
    cacheKey := fmt.Sprintf("user:%s:email", obj.ID)
    if cached := cache.Get(cacheKey); cached != nil {
        return cached.(*string), nil
    }
    
    email := loadUserEmail(obj.ID)
    cache.Set(cacheKey, &email, 5*time.Minute)
    return &email, nil
}

// 2. Query result caching with normalized cache
// 3. DataLoader for request-level caching

Error Handling Comparison

REST API Error Handling

func GetUser(c *gin.Context) {
    userID := c.Param("id")
    
    user, err := userService.GetByID(userID)
    if err != nil {
        switch err {
        case ErrUserNotFound:
            c.JSON(404, gin.H{"error": "User not found"})
        case ErrDatabaseConnection:
            c.JSON(500, gin.H{"error": "Internal server error"})
        default:
            c.JSON(500, gin.H{"error": "Unknown error"})
        }
        return
    }
    
    c.JSON(200, user)
}

GraphQL Error Handling

func (r *queryResolver) User(ctx context.Context, id string) (*model.User, error) {
    user, err := r.userService.GetByID(id)
    if err != nil {
        // GraphQL handles error formatting
        return nil, fmt.Errorf("failed to load user: %w", err)
    }
    return user, nil
}

// GraphQL response with errors:
{
  "data": {
    "user": null
  },
  "errors": [
    {
      "message": "failed to load user: user not found",
      "path": ["user"],
      "extensions": {
        "code": "USER_NOT_FOUND"
      }
    }
  ]
}

When to Choose Each Approach

Choose REST API When:

✅ Simple CRUD Operations

// Straightforward resource management
GET    /api/users      // List users
POST   /api/users      // Create user  
GET    /api/users/1    // Get user
PUT    /api/users/1    // Update user
DELETE /api/users/1    // Delete user

✅ Caching is Critical

  • HTTP caching works out of the box
  • CDN integration is straightforward
  • Browser caching is automatic

✅ Team Familiarity

  • Most developers understand REST
  • Abundant tooling and libraries
  • Simple debugging with curl/Postman

✅ Mobile Apps with Fixed Screens

  • Screen layouts are predictable
  • Data requirements are stable
  • Over-fetching is acceptable

Choose GraphQL When:

✅ Complex Data Relationships

query {
  user(id: "1") {
    posts {
      comments {
        author {
          profile {
            avatar
          }
        }
      }
    }
  }
}

✅ Multiple Client Types

  • Web app needs full data
  • Mobile app needs minimal data
  • Different clients, same API

✅ Rapid Frontend Development

  • Frontend teams can iterate independently
  • No backend changes for new UI requirements
  • Strong typing prevents runtime errors

✅ Real-time Features

subscription {
  messageAdded(chatId: "123") {
    id
    content
    author {
      name
    }
  }
}

Performance Benchmarks

Based on practical testing with similar data sets:

REST API Performance

Simple GET /users/1:           ~2ms
GET /users/1 with posts:       ~15ms (N+1 problem)
GET /users with all relations: ~200ms (100 users)

GraphQL Performance

{ user(id: "1") { email } }:           ~1ms
{ user(id: "1") { posts { title } } }: ~8ms (with DataLoader)
{ users { posts { comments } } }:      ~50ms (with proper batching)

Key Insight: GraphQL can be faster for complex queries when properly optimized, but requires more sophisticated caching and batching strategies.

Migration Strategies

REST to GraphQL Migration

// Phase 1: Add GraphQL alongside REST
func main() {
    r := gin.Default()
    
    // Keep existing REST endpoints
    api := r.Group("/api/v1")
    api.GET("/users/:id", handlers.GetUser)
    
    // Add GraphQL endpoint
    r.POST("/graphql", graphqlHandler())
    
    r.Run(":8080")
}

// Phase 2: Gradual migration
// Move complex queries to GraphQL first
// Keep simple CRUD in REST initially

// Phase 3: Full migration or hybrid approach
// Some teams keep both long-term

Conclusion

The choice between REST and GraphQL isn't just about technology—it's about matching your architecture to your use case:

REST API Strengths:

  • Simplicity: Easy to understand and implement
  • Caching: HTTP caching works seamlessly
  • Tooling: Mature ecosystem and debugging tools
  • Predictability: Fixed endpoints and responses

GraphQL Strengths:

  • Flexibility: Clients control data fetching
  • Efficiency: Precise data loading
  • Type Safety: Schema-driven development
  • Developer Experience: Introspection and tooling

My Recommendation:

Start with REST for:

  • MVP and simple applications
  • Teams new to API development
  • Applications with predictable data needs

Consider GraphQL for:

  • Complex data relationships
  • Multiple client applications
  • Teams prioritizing frontend flexibility
  • Applications requiring real-time features

The most successful projects I've seen often use a hybrid approach: REST for simple operations and GraphQL for complex data fetching. This gives you the best of both worlds while allowing gradual migration as your application grows in complexity.

Next Steps: In future posts, I'll explore implementing both approaches in Go, covering practical patterns for DataLoaders, caching strategies, and performance optimization techniques.

References:

This comparison is based on practical experience building both REST and GraphQL APIs in production environments. The examples use Go, but the architectural principles apply across all programming languages.