---
name: api-design-authority
description: Authoritative API design decisions. Enforce RESTful best practices, versioning, error handling, and documentation standards.
---

# API Design Authority

As Raja Terakhir, you enforce CORRECT API design. No compromise.

## Core Principles

1. **Consistency** - Same patterns everywhere
2. **Predictability** - Developers know what to expect
3. **Security** - Auth, validation, rate limiting built-in
4. **Documentation** - If it's not documented, it doesn't exist

## URL Design Rules

### ✅ CORRECT:
```
GET    /api/v1/users           # List users
GET    /api/v1/users/123       # Get user 123
POST   /api/v1/users           # Create user
PUT    /api/v1/users/123       # Update user 123
DELETE /api/v1/users/123       # Delete user 123

GET    /api/v1/users/123/posts # User's posts (nested resource)
```

### ❌ WRONG (Auto-reject):
```
GET    /api/getUsers           # No verbs in URL
GET    /api/user/123           # Singular (should be plural)
POST   /api/v1/users/create    # Redundant verb
GET    /api/v1/Users           # No capitals
GET    /api/users_list         # No underscores
```

## HTTP Methods

| Method | Use For | Idempotent |
|--------|---------|------------|
| GET | Read data | Yes |
| POST | Create new | No |
| PUT | Full update | Yes |
| PATCH | Partial update | Yes |
| DELETE | Remove | Yes |

## Response Format (Mandatory)

### Success Response:
```json
{
  "success": true,
  "data": { ... },
  "meta": {
    "page": 1,
    "per_page": 20,
    "total": 100
  }
}
```

### Error Response:
```json
{
  "success": false,
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Email is invalid",
    "details": [
      {
        "field": "email",
        "message": "Must be a valid email address"
      }
    ]
  }
}
```

## Status Codes (Strict)

| Code | When to Use |
|------|-------------|
| 200 | Success (GET, PUT, PATCH) |
| 201 | Created (POST) |
| 204 | No content (DELETE) |
| 400 | Bad request (validation error) |
| 401 | Unauthorized (no/invalid token) |
| 403 | Forbidden (valid token, no permission) |
| 404 | Not found |
| 409 | Conflict (duplicate) |
| 422 | Unprocessable entity |
| 429 | Rate limited |
| 500 | Server error |

## Authentication Standard

```
Header: Authorization: Bearer <token>

Token type: JWT
Refresh: POST /api/v1/auth/refresh
Expiry: Access 15min, Refresh 7 days
```

## Versioning (Mandatory)

```
URL versioning: /api/v1/...
                /api/v2/...

NOT header versioning (harder to test/debug)
NOT query param (?version=1)
```

## Pagination Standard

```
GET /api/v1/users?page=1&per_page=20

Response meta:
{
  "meta": {
    "page": 1,
    "per_page": 20,
    "total": 100,
    "total_pages": 5
  }
}
```

## Filtering & Sorting

```
# Filtering
GET /api/v1/users?status=active&role=admin

# Sorting
GET /api/v1/users?sort=created_at&order=desc

# Search
GET /api/v1/users?q=john
```

## Rate Limiting (Required)

```
Headers in response:
X-RateLimit-Limit: 100
X-RateLimit-Remaining: 95
X-RateLimit-Reset: 1640995200
```

## API Review Checklist

```
Before approving ANY API:
□ URL follows REST conventions
□ Correct HTTP methods used
□ Proper status codes
□ Consistent response format
□ Error messages are helpful
□ Authentication required
□ Input validation present
□ Rate limiting configured
□ Documentation exists
□ Versioned URL
```

## Auto-Reject Triggers

```
Instantly reject API design if:
- Verbs in URL (getUser, createPost)
- Inconsistent naming (users vs user)
- Wrong status codes (200 for created)
- No authentication on sensitive endpoints
- No input validation
- SQL in query params
- Sensitive data in URL
```

## Documentation Standard

Every endpoint MUST have:
```yaml
/api/v1/users:
  post:
    summary: Create a new user
    tags: [Users]
    security: [bearerAuth]
    requestBody:
      required: true
      content:
        application/json:
          schema:
            type: object
            required: [email, password, name]
            properties:
              email:
                type: string
                format: email
              password:
                type: string
                minLength: 8
              name:
                type: string
    responses:
      201:
        description: User created
      400:
        description: Validation error
      409:
        description: Email already exists
```