# Abstraction Ladder Example: API Design

## Topic: RESTful API Design

## Overview
This ladder shows how abstract API design principles translate into concrete implementation decisions for a user management endpoint.

## Abstraction Levels

### Level 1 (Most Abstract): Universal Principle
**"Interfaces should be intuitive, consistent, and predictable"**

This applies to all interfaces: APIs, UI, command-line tools, hardware controls. Users should be able to predict behavior based on consistent patterns.

### Level 2: Framework & Standards
**"Follow REST architectural constraints and HTTP semantics"**

RESTful design provides standardized patterns:
- Resources identified by URIs
- Stateless communication
- Standard HTTP methods (GET, POST, PUT, DELETE)
- Appropriate status codes
- HATEOAS (where applicable)

### Level 3: Approach & Patterns
**"Design resource-oriented endpoints with predictable CRUD operations"**

Concrete patterns:
- Use nouns for resources, not verbs
- Plural resource names
- Nested resources show relationships
- Query parameters for filtering/pagination
- Consistent error response format

### Level 4: Specific Implementation
**"User management API with standard CRUD endpoints"**

```
GET    /api/v1/users          # List all users
GET    /api/v1/users/:id      # Get specific user
POST   /api/v1/users          # Create user
PUT    /api/v1/users/:id      # Update user (full)
PATCH  /api/v1/users/:id      # Update user (partial)
DELETE /api/v1/users/:id      # Delete user
```

Authentication: Bearer token in Authorization header
Content-Type: application/json

### Level 5 (Most Concrete): Precise Details
**Exact endpoint specification:**

```http
GET /api/v1/users/12345
Authorization: Bearer eyJhbGciOiJIUzI1NiIs...
Accept: application/json

Response: 200 OK
{
  "id": 12345,
  "email": "user@example.com",
  "firstName": "Jane",
  "lastName": "Doe",
  "createdAt": "2024-01-15T10:30:00Z",
  "role": "standard"
}

Edge cases:
- User not found: 404 Not Found
- Invalid token: 401 Unauthorized
- Insufficient permissions: 403 Forbidden
- Invalid ID format: 400 Bad Request
- Server error: 500 Internal Server Error
```

Rate limit: 1000 requests/hour per token
Pagination: max 100 items per page, default 20

## Connections & Transitions

**L1 → L2**: REST provides a proven framework for creating predictable interfaces through standard conventions.

**L2 → L3**: Resource-oriented design is how REST constraints manifest in practical API design.

**L3 → L4**: User management is a concrete application of CRUD patterns to a specific domain resource.

**L4 → L5**: Exact HTTP requests/responses and error handling show how design patterns become actual code.

## Edge Cases & Boundary Testing

### Case 1: Deleting a non-existent user
- **Abstract principle (L1)**: Interface should provide clear feedback
- **Expected (L3)**: Return error for invalid operations
- **Actual (L5)**: `DELETE /users/99999` returns `404 Not Found` with body `{"error": "User not found"}`
- **Alignment**: ✓ Concrete implementation matches principle

### Case 2: Updating with partial data
- **Abstract principle (L1)**: Interface should be predictable
- **Expected (L3)**: PATCH for partial updates, PUT for full replacement
- **Actual (L5)**: `PATCH /users/123` with `{"firstName": "John"}` updates only firstName, leaves other fields unchanged
- **Alignment**: ✓ Follows REST semantics

### Case 3: Bulk operations
- **Abstract principle (L1)**: Interfaces should be consistent
- **Question**: How to delete multiple users?
- **Options**:
  - POST /users/bulk-delete (violates resource-oriented design)
  - DELETE /users with query params (non-standard)
  - Multiple DELETE requests (chatty but consistent)
- **Gap**: Pure REST doesn't handle bulk operations elegantly
- **Resolution**: Accept trade-off; use `POST /users/actions/bulk-delete` with clear documentation

## Applications

This ladder is useful for:
- **Onboarding new developers**: Show how design principles inform specific code
- **API review**: Check if implementation aligns with stated principles
- **Documentation**: Explain "why" behind specific endpoint designs
- **Consistency checking**: Ensure new endpoints follow same patterns
- **Client SDK design**: Derive SDK structure from abstraction levels

## Gaps & Assumptions

**Assumptions:**
- Using JSON (could be XML, Protocol Buffers, etc.)
- Token-based auth (could be OAuth, API keys, etc.)
- Synchronous operations (could be async/webhooks)

**Gaps:**
- Real-time updates not covered (WebSockets?)
- File uploads not addressed (multipart/form-data?)
- Versioning strategy mentioned but not detailed
- Caching strategy not specified
- Bulk operations awkward in pure REST

**Questions for deeper exploration:**
- How do GraphQL or gRPC change this ladder?
- What happens at massive scale (millions of requests/sec)?
- How does distributed/microservices architecture affect this?