Api Design

職業

分類

Backend

RESTful APIs

Core Concepts

• Resource-based approach using HTTP methods
• Stateless - each request contains all needed information
• Uses standard HTTP methods

HTTP Methods (CRUD Operations)

Status Codes

REST Best Practices

1. Use Plural Nouns (not verbs):

✅ GET /products
✅ GET /products/123
❌ GET /getProducts
❌ POST /createProduct

2. Filtering, Sorting, Pagination:

GET /products?category=electronics&in_stock=true    # Filtering
GET /products?sort=price_asc                          # Sorting
GET /products?page=3&limit=10                         # Pagination
GET /products?offset=20&limit=10                     # Alternative pagination

3. API Versioning:

GET /api/v1/products
GET /api/v2/products

4. Nested Resources:

GET /products/123/reviews        # Reviews for product 123
GET /users/456/orders            # Orders for user 456

GraphQL APIs

Why GraphQL Exists

Created by Facebook to solve:

• Multiple API calls for single view
• Over-fetching data
• Under-fetching data

REST vs GraphQL

REST (Multiple calls):

GET /users/123
GET /users/123/posts
GET /users/123/followers

GraphQL (Single call):

query {
  user(id: "123") {
    name
    posts {
      title
      content
    }
    followers {
      name
    }
  }
}

Schema Definition

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

type Post {
  id: ID!
  title: String!
  content: String
  author: User
}

type Query {
  user(id: ID!): User
  posts: [Post]
}

type Mutation {
  createUser(name: String!): User
  createPost(title: String!, content: String!): Post
}

Operations

Error Handling

GraphQL always returns 200 OK - errors in response body:

{
  "data": { "user": null },
  "errors": [{
    "message": "User not found",
    "path": ["user"],
    "extensions": { "code": "NOT_FOUND" }
  }]
}

gRPC

Overview

• High-performance RPC framework by Google
• Uses Protocol Buffers for serialization
• Runs on HTTP/2

Best For

• Microservices communication
• Internal system-to-system calls
• When performance is critical

Comparison

API Protocols

HTTP/HTTPS

Request Structure:

GET /api/products/123 HTTP/1.1
Host: api.example.com
Authorization: Bearer <token>
Content-Type: application/json

Response Structure:

HTTP/1.1 200 OK
Content-Type: application/json
Cache-Control: max-age=3600

{"id": 123, "name": "Product"}

⚠️ Always use HTTPS - encrypts data in transit with TLS/SSL

WebSockets

Problem with HTTP for real-time:

Client: "Any messages?" → Server: "No"
Client: "Any messages?" → Server: "No"
Client: "Any messages?" → Server: "Yes, here's one"
(Wasteful polling!)

WebSocket Solution:

Client ←──── Bidirectional ────→ Server
       │                         │
       │  Server can push data   │
       │  without client asking  │

Use Cases:

• Chat applications
• Live notifications
• Real-time gaming
• Stock tickers

AMQP (Advanced Message Queuing Protocol)

┌──────────┐     ┌─────────────┐     ┌──────────┐
│ Producer │ ──► │   Message   │ ──► │ Consumer │
│ (Payment │     │    Queue    │     │(Process  │
│  System) │     │   (Broker)  │     │ Orders)  │
└──────────┘     └─────────────┘     └──────────┘

Benefits:

• Decouples producers and consumers
• Handles traffic spikes (queue buffers)
• Guaranteed delivery

TCP vs UDP

Transport Layer Protocols

Application Layer (HTTP, WebSocket, gRPC)
              │
              ▼
Transport Layer (TCP or UDP)  ◄── We're here
              │
              ▼
Network Layer (IP)

TCP (Transmission Control Protocol)

Like sending a package with tracking & signature:

• ✅ Guaranteed delivery
• ✅ Ordered packets
• ✅ Error checking
• ❌ Slower (overhead)

Three-Way Handshake:

Client ──── SYN ────► Server
Client ◄── SYN-ACK ── Server
Client ──── ACK ────► Server
(Connection established!)

UDP (User Datagram Protocol)

Like sending postcards:

• ✅ Fast
• ✅ Low overhead
• ❌ No delivery guarantee
• ❌ No ordering

When to Use

API Design Best Practices

Performance

• Implement caching strategies
• Use pagination for large datasets
• Minimize payload sizes
• Reduce round trips (batch requests when possible)

Security

• Use HTTPS always
• Implement authentication (JWT, OAuth 2.0)
• Use authorization (RBAC, ABAC)
• Rate limiting
• Input validation
• CORS configuration

Documentation

• Document request/response schemas
• Include error response formats
• Provide example requests
• Use OpenAPI/Swagger for REST APIs
• Use GraphQL schema introspection

Versioning

• Version your APIs (/api/v1/, /api/v2/)
• Maintain backward compatibility
• Deprecate old versions gracefully
• Communicate breaking changes

Reference Material

For detailed examples and explanations, refer to:

• references/SYSTEM_DESIGN_MASTER_GUIDE.md - Part 3: API Design section