Skip to content

README.md

Latest commit

 

History

History
144 lines (109 loc) · 3.94 KB

README.md

File metadata and controls

144 lines (109 loc) · 3.94 KB

API Experiments: REST vs GraphQL vs gRPC

A practical comparison of three popular API architectures through hands-on experimentation.

Overview

This project implements the same e-commerce API using three different approaches:

  • REST API (Express.js)
  • GraphQL API (Apollo Server)
  • gRPC API (Protocol Buffers)

All APIs share the same SQLite database and implement identical operations for direct comparison.

Quick Start

Option 1: Docker (Recommended)

# Simple one-command test
run-docker-test.cmd

# Or using PowerShell
.\run-tests.ps1 test

# Or manually with docker-compose
docker-compose -f docker-compose.simple.yml up -d --build
docker-compose -f docker-compose.simple.yml exec -T test-client node benchmarks/comparison.js
docker-compose -f docker-compose.simple.yml down

Option 2: Local Development

# Install dependencies
npm install

# Set up the database
npm run setup-db

# Start all servers (in separate terminals)
npm run start-rest      # http://localhost:3001
npm run start-graphql   # http://localhost:3002/graphql
npm run start-grpc      # 0.0.0.0:50051

# Run experiments (wait ~5 seconds after starting servers)
npm run test-all

# Or run individual performance tests
npm run benchmark

API Operations

Each API implements these core operations:

  • Create user
  • Get user by ID
  • List products (with filtering/pagination)
  • Create order
  • Get user's order history

Development Experience Comparison

Setup Complexity

  • REST: ⭐⭐⭐ Simple Express setup
  • GraphQL: ⭐⭐ Schema + resolvers needed
  • gRPC: ⭐ Proto files + code generation

Learning Curve

  • REST: ⭐⭐⭐ Most familiar to developers
  • GraphQL: ⭐⭐ Query language to learn
  • gRPC: ⭐ Protocol buffers + concepts

Type Safety

  • REST: ⭐ Manual validation needed
  • GraphQL: ⭐⭐ Schema provides some safety
  • gRPC: ⭐⭐⭐ Strong typing with proto files

Documentation

  • REST: ⭐ Manual API documentation
  • GraphQL: ⭐⭐⭐ Self-documenting schema
  • gRPC: ⭐⭐ Proto files as documentation

Tooling

  • REST: ⭐⭐⭐ Excellent ecosystem
  • GraphQL: ⭐⭐⭐ GraphQL Playground, Apollo
  • gRPC: ⭐⭐ Growing but limited tools

Flexibility

  • REST: ⭐⭐ Multiple endpoints needed
  • GraphQL: ⭐⭐⭐ Query exactly what you need
  • gRPC: ⭐⭐ Structured service definitions

Use Case Recommendations

🏆 REST API - Best for:

  • Simple CRUD applications
  • Public APIs with wide compatibility
  • Teams new to API development
  • Caching-heavy applications

🏆 GraphQL - Best for:

  • Frontend-driven development
  • Complex data relationships
  • Mobile apps (bandwidth efficiency)
  • Real-time applications

🏆 gRPC - Best for:

  • Microservices communication
  • High-performance requirements
  • Streaming data applications
  • Polyglot environments

Pros & Cons Summary

REST API

Pros: Simple, widely supported, HTTP caching, stateless Cons: Over/under-fetching, multiple requests, versioning issues

GraphQL

Pros: Single endpoint, precise data fetching, strong typing, real-time Cons: Complex caching, learning curve, can be overkill for simple APIs

gRPC

Pros: High performance, strong typing, streaming, language agnostic Cons: Browser limitations, steeper learning curve, limited HTTP integration

Project Structure

├── database/           # SQLite schema and setup
├── rest-api/          # Express.js REST server
├── graphql-api/       # Apollo GraphQL server
├── grpc-api/          # gRPC server with proto files
├── clients/           # Client implementations for each API
└── benchmarks/        # Performance testing tools

Running Experiments

The benchmark suite tests:

  • Response times under different loads
  • Payload sizes
  • Success rates
  • Functionality verification

Results show practical differences in performance and developer experience across all three approaches.