REST API Design

---

Definition

---

HTTP Methods

---

Status Codes

---

Request/Response Design

// REQUEST DESIGN

// Path parameters: Identify resource
GET /users/{userId}/orders/{orderId}

// Query parameters: Filter, sort, paginate
GET /users?status=active&sort=created_at:desc&page=1&limit=20

// Request body: Create/update data
POST /users
Content-Type: application/json
{
    "name": "John Doe",
    "email": "[email protected]"
}

// RESPONSE DESIGN

// Single resource
{
    "id": "123",
    "name": "John Doe",
    "email": "[email protected]",
    "createdAt": "2024-01-15T10:30:00Z"
}

// Collection with pagination
{
    "data": [
        { "id": "1", "name": "John" },
        { "id": "2", "name": "Jane" }
    ],
    "pagination": {
        "page": 1,
        "limit": 20,
        "total": 100,
        "totalPages": 5
    },
    "links": {
        "self": "/users?page=1",
        "next": "/users?page=2",
        "last": "/users?page=5"
    }
}

// Error response
{
    "error": {
        "code": "VALIDATION_ERROR",
        "message": "Invalid request parameters",
        "details": [
            { "field": "email", "message": "Invalid email format" },
            { "field": "age", "message": "Must be positive" }
        ]
    },
    "requestId": "abc-123"
}

---

Versioning

---

Best Practices

// URL NAMING
// ✓ Use nouns: /users, /orders, /products
// ✗ Avoid verbs: /getUsers, /createOrder

// ✓ Plural nouns: /users, /orders
// ✗ Singular: /user, /order (inconsistent)

// ✓ Lowercase with hyphens: /order-items
// ✗ camelCase or underscores: /orderItems, /order_items

// ✓ Hierarchy reflects relationships
GET /users/123/orders/456/items

// FILTERING, SORTING, PAGINATION
GET /orders?status=pending&created_after=2024-01-01
GET /orders?sort=created_at:desc,total:asc
GET /orders?page=2&limit=20
GET /orders?cursor=eyJpZCI6MTIzfQ==  // Cursor pagination

// PARTIAL RESPONSES (fields selection)
GET /users/123?fields=id,name,email

// BULK OPERATIONS
POST /users/bulk
[{ "name": "John" }, { "name": "Jane" }]

DELETE /orders?ids=1,2,3

// ASYNC OPERATIONS
POST /reports
202 Accepted
Location: /reports/123/status

GET /reports/123/status
{ "status": "processing", "progress": 45 }

// RATE LIMITING HEADERS
X-RateLimit-Limit: 100
X-RateLimit-Remaining: 95
X-RateLimit-Reset: 1609459200

---

Tips & Tricks

---