# RMDC API Design Rules

## Core Principles

1. **POST + RequestBody 优先**: 所有 API 优先使用 POST 方法
2. **避免 PathVariables**: 资源标识放入 RequestBody
3. **避免 RequestParams**: 查询参数放入 RequestBody
4. **统一响应格式**: 所有响应遵循标准结构

## URL Naming Convention

| Operation | Suffix | Example |
|-----------|--------|---------|
| List | `/list` | `POST /api/projects/list` |
| Detail | `/detail` | `POST /api/projects/detail` |
| Create | `/create` | `POST /api/projects/create` |
| Update | `/update` | `POST /api/projects/update` |
| Delete | `/delete` | `POST /api/projects/delete` |

## Request Format

```json
{
    "project_id": "namespace_xxx",
    "page": 1,
    "page_size": 20,
    "filters": {
        "status": "ONLINE",
        "name": "keyword"
    }
}
```

## Response Format

### Success Response

```json
{
    "code": 0,
    "message": "success",
    "data": {
        // response payload
    }
}
```

### Paginated Response

```json
{
    "code": 0,
    "message": "success",
    "data": {
        "list": [...],
        "total": 100,
        "page": 1,
        "page_size": 20
    }
}
```

### Error Response

```json
{
    "code": 40001,
    "message": "Invalid parameter: project_id is required",
    "data": null
}
```

## Error Code Ranges

| Range | Module | Description |
|-------|--------|-------------|
| 0 | - | Success |
| 10000-19999 | rmdc-core | Gateway errors |
| 20000-29999 | rmdc-jenkins-dac | Jenkins errors |
| 30000-39999 | rmdc-project-mgmt | Project errors |
| 40000-49999 | rmdc-exchange-hub | Exchange errors |
| 50000-59999 | rmdc-watchdog | Watchdog errors |
| 60000-69999 | rmdc-user-auth | Auth errors |
| 70000-79999 | rmdc-audit-log | Audit errors |

## Common Error Codes

| Code | HTTP Status | Description |
|------|-------------|-------------|
| 10001 | 401 | Unauthorized |
| 10002 | 403 | Forbidden |
| 10003 | 404 | Resource not found |
| 10004 | 400 | Invalid parameters |
| 10005 | 500 | Internal server error |
| 10006 | 429 | Rate limit exceeded |

## HTTP Headers

### Request Headers

| Header | Required | Description |
|--------|----------|-------------|
| `Authorization` | Yes | `Bearer {jwt_token}` |
| `Content-Type` | Yes | `application/json` |
| `X-Request-ID` | No | 请求追踪 ID |

### Response Headers

| Header | Description |
|--------|-------------|
| `X-Request-ID` | 请求追踪 ID（回显或生成） |
| `X-Response-Time` | 响应耗时（毫秒） |

## JWT Claims

```json
{
    "user_id": 1,
    "username": "admin",
    "role": "SuperAdmin",
    "permissions": ["project:read", "project:write"],
    "exp": 1704501234,
    "iat": 1704414834
}
```

## Versioning Strategy

- 当前版本: 无版本前缀 (`/api/...`)
- 破坏性变更: 使用版本前缀 (`/api/v2/...`)
- 废弃策略: 旧版本保留 6 个月，响应头标记 `Deprecation: true`
