8. API Design

# Resources (nouns, not verbs)
GET    /users              # List all users
GET    /users/123          # Get user 123
POST   /users              # Create a new user
PUT    /users/123          # Replace user 123
PATCH  /users/123          # Update user 123 partially
DELETE /users/123          # Delete user 123

# Nested resources
GET    /users/123/orders          # List orders for user 123
GET    /users/123/orders/456      # Get order 456 for user 123
POST   /users/123/orders          # Create order for user 123

# Filtering, sorting, pagination
GET    /users?status=active&sort=name&page=2&limit=20
GET    /orders?start_date=2025-01-01&end_date=2025-12-31

# Search
GET    /users/search?q=alice

# Actions (when CRUD doesn't fit)
POST   /orders/123/cancel         # Cancel order 123
POST   /users/123/verify-email    # Trigger email verification

// Success response
{
  "data": {
    "id": "user-123",
    "name": "Alice",
    "email": "alice@example.com",
    "createdAt": "2025-01-15T10:30:00Z"
  }
}

// List response with pagination
{
  "data": [
    {"id": "user-1", "name": "Alice"},
    {"id": "user-2", "name": "Bob"}
  ],
  "pagination": {
    "page": 1,
    "limit": 20,
    "total": 150,
    "totalPages": 8,
    "nextCursor": "eyJpZCI6InVzZXItMjAifQ=="
  }
}

// Error response
{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Invalid email format",
    "details": [
      {
        "field": "email",
        "message": "Must be a valid email address"
      }
    ]
  }
}

# Schema definition
type User {
  id: ID!
  name: String!
  email: String!
  orders: [Order!]!
}

type Order {
  id: ID!
  total: Float!
  status: String!
  items: [OrderItem!]!
}

type Query {
  user(id: ID!): User
  users(limit: Int, offset: Int): [User!]!
}

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

type Subscription {
  orderStatusChanged(orderId: ID!): Order!
}

# Client query — request exactly what you need
query {
  user(id: "123") {
    name
    email
    orders {
      id
      total
      status
    }
  }
}

// Response — matches the query shape exactly
{
  "data": {
    "user": {
      "name": "Alice",
      "email": "alice@example.com",
      "orders": [
        {"id": "ord-1", "total": 99.99, "status": "shipped"},
        {"id": "ord-2", "total": 49.50, "status": "pending"}
      ]
    }
  }
}

// user.proto
syntax = "proto3";

service UserService {
  rpc GetUser (GetUserRequest) returns (User);
  rpc ListUsers (ListUsersRequest) returns (stream User);
  rpc CreateUser (CreateUserRequest) returns (User);
  rpc Chat (stream ChatMessage) returns (stream ChatMessage);
}

message User {
  string id = 1;
  string name = 2;
  string email = 3;
  int32 age = 4;
}

message GetUserRequest {
  string id = 1;
}

Unary:               Client ──req──→ Server ──res──→ Client
Server streaming:    Client ──req──→ Server ══res══▷ Client (multiple responses)
Client streaming:    Client ══req══▷ Server ──res──→ Client
Bidirectional:       Client ◁══════▷ Server (both stream simultaneously)

Client ←→ Server  (persistent bidirectional connection)

1. Client sends HTTP Upgrade request
2. Server responds with 101 Switching Protocols
3. Both sides can send messages at any time

Client ──GET /events──→ Server
Client ◁──event: update\ndata: {...}──
Client ◁──event: update\ndata: {...}──
Client ◁──event: update\ndata: {...}──

{
  "error": {
    "code": "INSUFFICIENT_FUNDS",
    "message": "Account balance is too low",
    "requestId": "req-abc-123",
    "timestamp": "2025-01-15T10:30:00Z"
  }
}

X-RateLimit-Limit: 100
X-RateLimit-Remaining: 45
X-RateLimit-Reset: 1705312800
Retry-After: 30

Client → [API Gateway] → /users/* → User Service
                       → /orders/* → Order Service
                       → /payments/* → Payment Service