Migrate

microservices/.agent/skills/documentation/references/API_TABLES.md

@@ -0,0 +1,105 @@
+# API Endpoint Tables / Bảng Danh Sách API
+
+This reference provides standard table formats for documenting API endpoints.
+
+## Standard Endpoint Table Format
+
+```markdown
+## 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
+
+```markdown
+### 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
+
+```markdown
+### 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
+
+```markdown
+### 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
+
+```markdown
+### 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](OPENAPI.md) - For OpenAPI spec documentation
+- [Back to Documentation Skill](../SKILL.md)