rest-api-designer

# REST API Designer

Design RESTful APIs with proper resource modeling and endpoint structure.

## Quick Start

Use resource-based URLs with plural nouns, proper HTTP methods, and consistent patterns.

## Instructions

### Core REST Principles

**Resources, not actions:**
```
Good: GET /users, POST /users
Bad: GET /getUsers, POST /createUser
```

**Use HTTP methods correctly:**
- GET: Retrieve (safe, idempotent)
- POST: Create (not idempotent)
- PUT: Replace (idempotent)
- PATCH: Partial update (not idempotent)
- DELETE: Remove (idempotent)

**Use plural nouns:**
```
Good: /products, /orders
Bad: /product, /order
```

### Resource Modeling

**Identify resources:**
1. List main entities (users, products, orders)
2. Identify relationships (user has orders, order has items)
3. Determine hierarchies (posts have comments)

**Design URL structure:**
```
/api/v1/resources
/api/v1/resources/{id}
/api/v1/resources/{id}/sub-resources
```

**Example - Blog API:**
```
GET    /api/v1/posts           # List posts
POST   /api/v1/posts           # Create post
GET    /api/v1/posts/{id}      # Get post
PUT    /api/v1/posts/{id}      # Replace post
PATCH  /api/v1/posts/{id}      # Update post
DELETE /api/v1/posts/{id}      # Delete post

GET    /api/v1/posts/{id}/comments    # List comments
POST   /api/v1/posts/{id}/comments    # Create comment
```

### HTTP Methods

**GET - Retrieve resources:**
```
GET /api/v1/users           # List all users
GET /api/v1/users/{id}      # Get specific user
GET /api/v1/users?role=admin # Filter users
```

Response:
```json
{
  "data": [
    { "id": 1, "name": "John" }
  ],
  "meta": {
    "total": 100,
    "page": 1
  }
}
```

**POST - Create resources:**
```
POST /api/v1/users
Content-Type: application/json

{
  "name": "John Doe",
  "email": "john@example.com"
}
```

Response (201 Created):
```json
{
  "id": 123,
  "name": "John Doe",
  "email": "john@example.com",
  "created_at": "2024-01-01T00:00:00Z"
}
```

**PUT - Replace resource:**
```
PUT /a