pos-system/microservices/.agent/skills/documentation/references/API_TABLES.md

API Endpoint Tables / Bảng Danh Sách API

This reference provides standard table formats for documenting API endpoints.

Standard Endpoint Table Format

## API Endpoints

### Resource Management / Quản Lý Tài Nguyên

| Method | Endpoint | Description / Mô Tả | Auth |
|--------|----------|---------------------|------|
| GET | `/api/v1/resources` | List all resources / Liệt kê tài nguyên | ✓ |
| POST | `/api/v1/resources` | Create new resource / Tạo mới tài nguyên | ✓ |
| GET | `/api/v1/resources/{id}` | Get resource details / Lấy chi tiết tài nguyên | ✓ |
| PUT | `/api/v1/resources/{id}` | Update resource / Cập nhật tài nguyên | ✓ |
| DELETE | `/api/v1/resources/{id}` | Delete resource / Xóa tài nguyên | ✓ |

### Admin Endpoints / Endpoint Quản Trị

| Method | Endpoint | Description / Mô Tả | Roles |
|--------|----------|---------------------|-------|
| GET | `/api/v1/admin/users` | List all users / Liệt kê người dùng | Admin |
| POST | `/api/v1/admin/users/{id}/suspend` | Suspend user / Tạm dừng người dùng | Admin |

Query Parameters Table

### Query Parameters for `GET /api/v1/resources`

| Parameter | Type | Required | Description / Mô Tả | Default | Example |
|-----------|------|----------|---------------------|---------|----------|
| `page` | integer | No | Page number (1-indexed) / Số trang | 1 | `?page=2` |
| `pageSize` | integer | No | Items per page / Số item mỗi trang | 10 | `?pageSize=20` |
| `search` | string | No | Search keyword / Từ khóa tìm kiếm | - | `?search=product` |
| `sortBy` | string | No | Sort field / Trường sắp xếp | `createdAt` | `?sortBy=name` |
| `sortOrder` | enum | No | Sort direction: `asc`, `desc` / Thứ tự | `desc` | `?sortOrder=asc` |
| `status` | enum | No | Filter by status / Lọc theo trạng thái | - | `?status=active` |

Request Body Table

### Request Body for `POST /api/v1/resources`

| Field | Type | Required | Description / Mô Tả | Validation |
|-------|------|----------|---------------------|------------|
| `name` | string | Yes | Resource name / Tên tài nguyên | Min: 3, Max: 100 chars |
| `description` | string | No | Resource description / Mô tả | Max: 500 chars |
| `type` | enum | Yes | Resource type: `product`, `service` | Must be valid enum |
| `price` | decimal | No | Price in VND / Giá (VNĐ) | Min: 0, Max: 1000000000 |
| `tags` | array | No | Tags for categorization / Thẻ phân loại | Max: 10 items |

Response Codes Table

### Response Codes

| Code | Status | Description / Mô Tả |
|------|--------|---------------------|
| 200 | OK | Request successful / Yêu cầu thành công |
| 201 | Created | Resource created / Tài nguyên đã tạo |
| 400 | Bad Request | Invalid input / Dữ liệu không hợp lệ |
| 401 | Unauthorized | Authentication required / Cần xác thực |
| 403 | Forbidden | Insufficient permissions / Không đủ quyền |
| 404 | Not Found | Resource not found / Không tìm thấy tài nguyên |
| 409 | Conflict | Resource already exists / Tài nguyên đã tồn tại |
| 422 | Unprocessable Entity | Validation failed / Xác thực thất bại |
| 500 | Internal Server Error | Server error / Lỗi server |

Error Response Format

### Error Response Structure

\`\`\`json
{
  "type": "validation_error",
  "title": "Validation Failed",
  "status": 422,
  "errors": {
    "name": ["Name is required", "Name must be at least 3 characters"],
    "email": ["Email format is invalid"]
  },
  "traceId": "00-abc123-def456-00"
}
\`\`\`

**Error Types:**
- `validation_error` - Input validation failures
- `authentication_error` - Authentication issues
- `authorization_error` - Permission denied
- `not_found_error` - Resource not found
- `conflict_error` - Duplicate or conflicting resource
- `internal_error` - Unexpected server error

Resources

• OpenAPI Reference - For OpenAPI spec documentation
• Back to Documentation Skill