Files

admin 1817158f25 251202:2300 Prepare 1.5.1

2025-12-03 01:16:27 +07:00

18 KiB

Raw Blame History

🌐 API Design Specification

title: 'API Design' version: 1.5.1 status: active owner: Nattanin Peancharoen last_updated: 2025-12-02 related:

specs/01-requirements/02-architecture.md
specs/02-architecture/system-architecture.md
specs/03-implementation/fullftack-js-v1.5.0.md

📋ภาพรวม (Overview)

เอกสารนี้กำหนดมาตรฐานการออกแบบ API สำหรับระบบ LCBP3-DMS โดยใช้แนวทาง API-First Design ที่เน้นความชัดเจน ความสอดคล้อง และความปลอดภัย

🎯 หลักการออกแบบ API (API Design Principles)

1.1 API-First Approach

ออกแบบ API ก่อนการ Implement: ทำการออกแบบ API Endpoint และ Data Contract ให้ชัดเจนก่อนเริ่มเขียนโค้ด
Documentation-Driven: ใช้ OpenAPI/Swagger เป็นเอกสารอ้างอิงหลัก
Contract Testing: ทดสอบ API ตาม Contract ที่กำหนดไว้

1.2 RESTful Principles

ใช้ HTTP Methods อย่างถูกต้อง: GET, POST, PUT, PATCH, DELETE
ใช้ HTTP Status Codes ที่เหมาะสม
Resource-Based URL Design
Stateless Communication

1.3 Consistency & Predictability

Naming Conventions: ใช้ kebab-case สำหรับ URL paths
Property Naming: ใช้ snake_case สำหรับ JSON properties (สอดคล้องกับ Database Schema)
Versioning: รองรับการ Version API ผ่าน URL path (/api/v1/...)

🔐 Authentication & Authorization

2.1 Authentication

JWT-Based Authentication: ใช้ JSON Web Token สำหรับการยืนยันตัวตน
Token Management:
- Access Token Expiration: 8 ชั่วโมง
- Refresh Token Expiration: 7 วัน
- Token Rotation: รองรับการหมุนเวียน Refresh Token
- Token Revocation: บันทึก Revoked Tokens จนกว่าจะหมดอายุ

Endpoints:

POST / api / v1 / auth / login;
POST / api / v1 / auth / logout;
POST / api / v1 / auth / refresh;
POST / api / v1 / auth / change - password;

2.2 Authorization (RBAC)

4-Level Permission Hierarchy:
1. Global Level: System-wide permissions (Superadmin)
2. Organization Level: Organization-specific permissions
3. Project Level: Project-specific permissions
4. Contract Level: Contract-specific permissions
Permission Checking: ใช้ Decorator @RequirePermission('resource.action')

Example:

@RequirePermission('correspondence.create')
@Post('correspondences')
async createCorrespondence(@Body() dto: CreateCorrespondenceDto) {
  // Implementation
}

2.3 Token Payload Optimization

JWT Payload เก็บเฉพาะ userId และ scope ปัจจุบัน
Permissions Caching: เก็บ Permission List ใน Redis และดึงมาตรวจสอบเมื่อมี Request

📡 API Conventions

3.1 Base URL Structure

https://backend.np-dms.work/api/v1/{resource}

3.2 HTTP Methods & Usage

Method	Usage	Idempotent	Example
`GET`	ดึงข้อมูล (Read)	✅ Yes	`GET /api/v1/correspondences`
`POST`	สร้างข้อมูลใหม่ (Create)	❌ No*	`POST /api/v1/correspondences`
`PUT`	อัปเดตทั้งหมด (Full Update)	✅ Yes	`PUT /api/v1/correspondences/:id`
`PATCH`	อัปเดตบางส่วน (Partial Update)	✅ Yes	`PATCH /api/v1/correspondences/:id`
`DELETE`	ลบข้อมูล (Soft Delete)	✅ Yes	`DELETE /api/v1/correspondences/:id`

Note: POST เป็น Idempotent ได้เมื่อใช้ Idempotency-Key Header

3.3 HTTP Status Codes

Status Code	Usage
`200 OK`	Request สำเร็จ (GET, PUT, PATCH)
`201 Created`	สร้างข้อมูลสำเร็จ (POST)
`204 No Content`	ลบสำเร็จ (DELETE)
`400 Bad Request`	ข้อมูล Request ไม่ถูกต้อง
`401 Unauthorized`	ไม่มี Token หรือ Token หมดอายุ
`403 Forbidden`	ไม่มีสิทธิ์เข้าถึง
`404 Not Found`	ไม่พบข้อมูล
`409 Conflict`	ข้อมูลซ้ำ หรือ State Conflict
`422 Unprocessable Entity`	Validation Error
`429 Too Many Requests`	Rate Limit Exceeded
`500 Internal Server Error`	Server Error
`503 Service Unavailable`	Maintenance Mode

3.4 Request & Response Format

Request Headers:

Content-Type: application/json
Authorization: Bearer <access_token>
Idempotency-Key: <uuid> # สำหรับ POST/PUT/DELETE

Success Response Format:

{
  "success": true,
  "data": {
    // Resource data
  },
  "message": "Operation completed successfully"
}

Error Response Format:

{
  "success": false,
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Validation failed",
    "details": [
      {
        "field": "email",
        "message": "Invalid email format"
      }
    ]
  },
  "timestamp": "2025-11-30T13:48:20Z",
  "path": "/api/v1/users"
}

🔄 Idempotency

4.1 Implementation

ทุก Critical Operation (Create, Update, Delete) ต้องรองรับ Idempotency
Client ส่ง Header: Idempotency-Key: <uuid>
Server เช็คว่า Key นี้เคยประมวลผลสำเร็จแล้วหรือไม่
ถ้าเคยทำแล้ว: ส่งผลลัพธ์เดิมกลับไป (ไม่ทำซ้ำ)

Example:

POST /api/v1/correspondences
Idempotency-Key: 550e8400-e29b-41d4-a716-446655440000
Content-Type: application/json

{
  "title": "New Correspondence",
  "type_id": 1
}

📊 Pagination, Filtering & Sorting

5.1 Pagination (Server-Side)

Query Parameters:

GET /api/v1/correspondences?page=1&page_size=20

Response:

{
  "success": true,
  "data": [...],
  "meta": {
    "current_page": 1,
    "page_size": 20,
    "total_items": 150,
    "total_pages": 8,
    "has_next_page": true,
    "has_previous_page": false
  }
}

5.2 Filtering

GET /api/v1/correspondences?project_id=1&status=PENDING

5.3 Sorting

GET /api/v1/correspondences?sort=created_at&order=desc

5.4 Combined Example

GET /api/v1/correspondences?project_id=1&status=PENDING&page=1&page_size=20&sort=created_at&order=desc

🛡️ Security Features

6.1 Rate Limiting

Endpoint Type	Limit	Scope
Anonymous Endpoints	100 requests/hour	IP
Viewer	500 requests/hour	User
Editor	1000 requests/hour	User
Document Control	2000 requests/hour	User
Admin/Superadmin	5000 requests/hour	User
File Upload	50 requests/hour	User
Search	500 requests/hour	User
Authentication	10 requests/minute	IP

Rate Limit Headers:

X-RateLimit-Limit: 1000
X-RateLimit-Remaining: 999
X-RateLimit-Reset: 1638360000

6.2 Input Validation

DTOs with Class Validator: ทุก Request ต้องผ่าน Validation
XSS Protection: Input Sanitization
SQL Injection Prevention: ใช้ ORM (TypeORM) Parameterized Queries
CSRF Protection: CSRF Tokens สำหรับ State-Changing Operations

6.3 File Upload Security

Endpoint:

POST /api/v1/files/upload

Security Measures:

Virus Scanning: ใช้ ClamAV scan ทุกไฟล์
File Type Validation: White-list (PDF, DWG, DOCX, XLSX, ZIP)
File Size Limit: 50MB per file
Two-Phase Storage:
1. Upload to temp/ folder
2. Commit to permanent/{YYYY}/{MM}/ when operation succeeds

Response:

{
  "success": true,
  "data": {
    "temp_id": "uuid",
    "filename": "document.pdf",
    "size": 1024000,
    "mime_type": "application/pdf",
    "scan_status": "CLEAN"
  }
}

📦 Core Module APIs

7.1 Correspondence Module

Base Path: /api/v1/correspondences

Method	Endpoint	Permission	Description
GET	`/correspondences`	`correspondence.view`	รายการ Correspondence
GET	`/correspondences/:id`	`correspondence.view`	รายละเอียด
POST	`/correspondences`	`correspondence.create`	สร้างใหม่
PUT	`/correspondences/:id`	`correspondence.update`	อัปเดตทั้งหมด
PATCH	`/correspondences/:id`	`correspondence.update`	อัปเดตบางส่วน
DELETE	`/correspondences/:id`	`correspondence.delete`	ลบ (Soft Delete)
POST	`/correspondences/:id/revisions`	`correspondence.update`	สร้าง Revision ใหม่
GET	`/correspondences/:id/revisions`	`correspondence.view`	ดู Revisions ทั้งหมด
POST	`/correspondences/:id/attachments`	`correspondence.update`	เพิ่มไฟล์แนบ

7.2 RFA Module

Base Path: /api/v1/rfas

Method	Endpoint	Permission	Description
GET	`/rfas`	`rfas.view`	รายการ RFA
GET	`/rfas/:id`	`rfas.view`	รายละเอียด
POST	`/rfas`	`rfas.create`	สร้างใหม่
PUT	`/rfas/:id`	`rfas.update`	อัปเดต
DELETE	`/rfas/:id`	`rfas.delete`	ลบ
POST	`/rfas/:id/respond`	`rfas.respond`	ตอบกลับ RFA
POST	`/rfas/:id/approve`	`rfas.approve`	อนุมัติ RFA
POST	`/rfas/:id/revisions`	`rfas.update`	สร้าง Revision
GET	`/rfas/:id/workflow`	`rfas.view`	ดู Workflow Status

7.3 Drawing Module

Base Path: /api/v1/drawings

Shop Drawings:

Method	Endpoint	Permission	Description
GET	`/shop-drawings`	`drawings.view`	รายการ Shop Drawing
POST	`/shop-drawings`	`drawings.upload`	อัปโหลดใหม่
GET	`/shop-drawings/:id/revisions`	`drawings.view`	ดู Revisions

Contract Drawings:

Method	Endpoint	Permission	Description
GET	`/contract-drawings`	`drawings.view`	รายการ Contract Drawing
POST	`/contract-drawings`	`drawings.upload`	อัปโหลดใหม่

7.4 Project Module

Base Path: /api/v1/projects

Method	Endpoint	Permission	Description
GET	`/projects`	`projects.view`	รายการโครงการ
GET	`/projects/:id`	`projects.view`	รายละเอียด
POST	`/projects`	`projects.create`	สร้างโครงการใหม่
PUT	`/projects/:id`	`projects.update`	อัปเดต
POST	`/projects/:id/contracts`	`contracts.create`	สร้าง Contract
GET	`/projects/:id/parties`	`projects.view`	ดู Project Parties
POST	`/projects/:id/parties`	`project_parties.manage`	เพิ่ม Party

7.5 User & Auth Module

Base Path: /api/v1/users, /api/v1/auth

Authentication:

POST / api / v1 / auth / login;
POST / api / v1 / auth / logout;
POST / api / v1 / auth / refresh;
POST / api / v1 / auth / change - password;
POST / api / v1 / auth / reset - password;

User Management:

GET    /api/v1/users              # List users
GET    /api/v1/users/:id          # User details
POST   /api/v1/users              # Create user
PUT    /api/v1/users/:id          # Update user
DELETE /api/v1/users/:id          # Delete user
POST   /api/v1/users/:id/roles    # Assign roles
GET    /api/v1/users/me           # Current user info
GET    /api/v1/users/me/permissions # Current user permissions

7.6 Search Module

Base Path: /api/v1/search

GET /api/v1/search?q=<query>&type=<correspondence|rfa|drawing>&project_id=<id>

Response:

{
  "success": true,
  "data": {
    "results": [...],
    "aggregations": {
      "by_type": { "correspondence": 10, "rfa": 5 },
      "by_status": { "PENDING": 8, "APPROVED": 7 }
    }
  },
  "meta": {
    "total": 15,
    "took_ms": 45
  }
}

🔔 Notification API

Base Path: /api/v1/notifications

GET    /api/v1/notifications           # List notifications
GET    /api/v1/notifications/:id       # Notification details
PATCH  /api/v1/notifications/:id/read  # Mark as read
DELETE /api/v1/notifications/:id       # Delete notification

📈 Reporting & Export APIs

Base Path: /api/v1/reports

GET /api/v1/reports/correspondences?format=csv&project_id=1&from=2025-01-01&to=2025-12-31
GET /api/v1/reports/rfas?format=excel&project_id=1
GET /api/v1/reports/dashboard # Dashboard KPIs

Supported Formats:

csv - CSV file
excel - Excel file (.xlsx)
pdf - PDF file

🔧 Workflow Engine API

Base Path: /api/v1/workflows

GET    /api/v1/workflows/definitions              # List workflow definitions
GET    /api/v1/workflows/definitions/:id          # Definition details
POST   /api/v1/workflows/instances                # Create workflow instance
GET    /api/v1/workflows/instances/:id            # Instance details
POST   /api/v1/workflows/instances/:id/transition # Execute transition
GET    /api/v1/workflows/instances/:id/history    # View history

⚡ Performance Optimization

11.1 Caching Strategy

Cache Headers:

Cache-Control: max-age=3600, private
ETag: "33a64df551425fcc55e4d42a148795d9f25f89d4"

Cache TTL:

Master Data: 1 hour
User Sessions: 30 minutes
Search Results: 15 minutes
File Metadata: 1 hour

11.2 Response Compression

Accept-Encoding: gzip, deflate, br
Content-Encoding: gzip

🧪 Testing & Documentation

12.1 API Documentation

Swagger/OpenAPI: Auto-generated จาก NestJS Decorators
URL: https://backend.np-dms.work/api/docs

12.2 Testing Strategy

Unit Tests: Test individual controllers & services
Integration Tests: Test API endpoints with database
E2E Tests: Test complete user flows
Contract Tests: Verify API contracts

🚦 Health Check & Monitoring

GET /health              # Health check endpoint
GET /health/ready        # Readiness probe
GET /health/live         # Liveness probe
GET /metrics             # Prometheus metrics

Response:

{
  "status": "ok",
  "uptime": 86400,
  "checks": {
    "database": "ok",
    "redis": "ok",
    "elasticsearch": "ok"
  }
}

📝 API Versioning Strategy

14.1 Versioning Approach

URL-Based Versioning: /api/v1/..., /api/v2/...
Backward Compatibility: รองรับ API เวอร์ชันเก่าอย่างน้อย 1 เวอร์ชัน
Deprecation Headers:

X-API-Deprecation-Warning: This endpoint will be deprecated on 2026-01-01
X-API-Deprecation-Info: https://docs.np-dms.work/migration/v2

🎯 Best Practices Summary

ใช้ DTOs สำหรับ Validation ทุก Request
ส่ง Idempotency-Key สำหรับ Critical Operations
ใช้ Proper HTTP Status Codes
Implement Rate Limiting บน Client Side
Handle Errors Gracefully
Cache Frequently-Accessed Data
Use Pagination สำหรับ Large Datasets
Document ทุก Endpoint ด้วย Swagger

Document Control:

Version: 1.5.1
Status: Active
Last Updated: 2025-12-02
Owner: Nattanin Peancharoen

18 KiB Raw Blame History

🌐 API Design Specification

📋ภาพรวม (Overview)

🎯 หลักการออกแบบ API (API Design Principles)

1.1 API-First Approach

1.2 RESTful Principles

1.3 Consistency & Predictability

🔐 Authentication & Authorization

2.1 Authentication

2.2 Authorization (RBAC)

2.3 Token Payload Optimization

📡 API Conventions

3.1 Base URL Structure

3.2 HTTP Methods & Usage

3.3 HTTP Status Codes

3.4 Request & Response Format

🔄 Idempotency

4.1 Implementation

📊 Pagination, Filtering & Sorting

5.1 Pagination (Server-Side)

5.2 Filtering

5.3 Sorting

5.4 Combined Example

🛡️ Security Features

6.1 Rate Limiting

6.2 Input Validation

6.3 File Upload Security

📦 Core Module APIs

7.1 Correspondence Module

7.2 RFA Module

7.3 Drawing Module

7.4 Project Module

7.5 User & Auth Module

7.6 Search Module

🔔 Notification API

📈 Reporting & Export APIs

🔧 Workflow Engine API

⚡ Performance Optimization

11.1 Caching Strategy

11.2 Response Compression

🧪 Testing & Documentation

12.1 API Documentation

12.2 Testing Strategy

🚦 Health Check & Monitoring

📝 API Versioning Strategy

14.1 Versioning Approach

🎯 Best Practices Summary

18 KiB

Raw Blame History