pos-system/docs/vi/skills/api-design.md

Thiết Kế API RESTful

RESTful API design standards for GoodGo microservices. Use when creating new API endpoints, designing DTOs, implementing controllers, writing OpenAPI documentation, or standardizing API responses.

Tiêu chuẩn thiết kế API RESTful cho các microservices của GoodGo. Sử dụng khi tạo endpoint API mới, thiết kế DTOs, triển khai controllers, viết tài liệu OpenAPI, hoặc chuẩn hóa response API.

Tổng Quan

This skill covers the RESTful API design patterns and standards used across all GoodGo microservices. It ensures consistency, predictability, and maintainability of APIs through standardized URL structures, HTTP methods, response formats, error handling, and DTO validation.

Skill này bao gồm các pattern và tiêu chuẩn thiết kế API RESTful được sử dụng trong tất cả các microservices của GoodGo. Nó đảm bảo tính nhất quán, dự đoán được và dễ bảo trì của APIs thông qua cấu trúc URL chuẩn hóa, HTTP methods, định dạng response, xử lý lỗi và validation DTO.

Khi Nào Sử Dụng

Use this skill when:

• Creating new API endpoints
• Designing request/response DTOs
• Implementing controllers and routes
• Writing OpenAPI/Swagger documentation
• Standardizing error responses
• Implementing pagination, filtering, and sorting
• Setting up API versioning
• Designing resource relationships

Sử dụng skill này khi:

• Tạo endpoint API mới
• Thiết kế DTOs cho request/response
• Triển khai controllers và routes
• Viết tài liệu OpenAPI/Swagger
• Chuẩn hóa error responses
• Triển khai pagination, filtering và sorting
• Thiết lập API versioning
• Thiết kế quan hệ giữa các resources

Khái Niệm Chính

Cấu Trúc URL

URLs follow a hierarchical resource-based structure with versioning.

URLs tuân theo cấu trúc phân cấp dựa trên resource với versioning.

https://api.goodgo.com/v1/{resource}/{id}/{sub-resource}

Examples:
GET    /v1/users                 # List users / Liệt kê users
POST   /v1/users                 # Create user / Tạo user
GET    /v1/users/123             # Get user by ID / Lấy user theo ID
PUT    /v1/users/123             # Update user / Cập nhật user
DELETE /v1/users/123             # Delete user / Xóa user
GET    /v1/users/123/orders      # Get user's orders / Lấy orders của user
POST   /v1/users/123/orders      # Create order for user / Tạo order cho user

Phương Thức HTTP

• GET: Retrieve resource(s) - Safe, Idempotent / Lấy resource(s) - An toàn, Idempotent
• POST: Create new resource - Not idempotent / Tạo resource mới - Không idempotent
• PUT: Full update - Idempotent / Cập nhật toàn bộ - Idempotent
• PATCH: Partial update - Idempotent / Cập nhật một phần - Idempotent
• DELETE: Remove resource - Idempotent / Xóa resource - Idempotent

Định Dạng Response Chuẩn

All API responses follow a consistent structure with success, data, and optional metadata fields.

Tất cả API responses tuân theo cấu trúc nhất quán với các trường success, data, và metadata tùy chọn.

Các Pattern Thường Dùng

Pattern Response Thành Công

interface SuccessResponse<T> {
  success: true;
  data: T;
  message?: string;
  timestamp?: string;
  pagination?: {
    total: number;
    skip: number;
    take: number;
  };
}

Example from codebase / Ví dụ từ codebase:

// services/iam-service/src/modules/identity/user/user.controller.ts
res.json({
  success: true,
  data: {
    users: result.users,
    pagination: {
      total: result.total,
      skip: filters.skip,
      take: filters.take,
    },
  },
});

Pattern Response Lỗi

interface ErrorResponse {
  success: false;
  error: {
    code: string;
    message: string;
    details?: any;
    field?: string;
  };
  timestamp?: string;
}

Example from codebase / Ví dụ từ codebase:

// services/iam-service/src/modules/identity/user/user.controller.ts
if (error instanceof z.ZodError) {
  res.status(400).json({
    success: false,
    error: {
      code: 'VALIDATION_ERROR',
      message: 'Invalid filters',
      details: error.errors,
    },
  });
  return;
}

Mã Trạng Thái HTTP

// Mã thành công
200 OK                  // GET, PUT, PATCH success
201 Created            // POST success with resource creation
204 No Content         // DELETE success

// Lỗi client
// Dữ liệu request không hợp lệ
// Thiếu/sai xác thực
// Xác thực hợp lệ nhưng không có quyền
// Resource không tồn tại
// Xung đột resource (trùng lặp)
// Lỗi validation

// Lỗi server
// Lỗi server không mong đợi
// Lỗi dịch vụ bên ngoài
// Dịch vụ tạm thời không khả dụng

DTOs với Zod Validation

DTOs use Zod for runtime validation with bilingual error messages.

DTOs sử dụng Zod cho validation runtime với thông báo lỗi song ngữ.

Example from codebase / Ví dụ từ codebase:

// services/iam-service/src/modules/identity/identity.dto.ts
import { z } from 'zod';

export const CreateOrganizationDto = z.object({
  name: z.string().min(1, 'Organization name is required / Tên tổ chức là bắt buộc').max(255),
  domain: z.string().email().optional().or(z.string().min(1).max(255).optional()),
  parentId: z.string().optional(),
  settings: z.record(z.any()).optional(),
});

export type CreateOrganizationDto = z.infer<typeof CreateOrganizationDto>;

export const UserFiltersDto = z.object({
  organizationId: z.string().optional(),
  isActive: z.boolean().optional(),
  emailVerified: z.boolean().optional(),
  search: z.string().optional(),
  skip: z.number().int().min(0).default(0),
  take: z.number().int().min(1).max(100).default(20),
});

Pattern Triển Khai Controller

Example from codebase / Ví dụ từ codebase:

// services/iam-service/src/modules/identity/user/user.controller.ts
export class UserManagementController {
  /**
List users
   * VI: Liệt kê users
   */
  async list(req: Request, res: Response): Promise<void> {
    try {
      const filters = UserFiltersDto.parse({
        organizationId: req.query.organizationId as string,
        isActive: req.query.isActive === 'true' ? true : req.query.isActive === 'false' ? false : undefined,
        emailVerified: req.query.emailVerified === 'true' ? true : req.query.emailVerified === 'false' ? false : undefined,
        search: req.query.search as string,
        skip: parseInt(req.query.skip as string) || 0,
        take: parseInt(req.query.take as string) || 20,
      });

      const result = await userManagementService.searchUsers(filters);

      res.json({
        success: true,
        data: {
          users: result.users,
          pagination: {
            total: result.total,
            skip: filters.skip,
            take: filters.take,
          },
        },
      });
    } catch (error: any) {
      if (error instanceof z.ZodError) {
        res.status(400).json({
          success: false,
          error: {
            code: 'VALIDATION_ERROR',
            message: 'Invalid filters',
            details: error.errors,
          },
        });
        return;
      }

      res.status(500).json({
        success: false,
        error: {
          code: 'LIST_USERS_FAILED',
          message: error.message || 'Failed to list users',
        },
      });
    }
  }

  /**
Get user by ID
   * VI: Lấy user theo ID
   */
  async get(req: Request, res: Response): Promise<void> {
    try {
      const { id } = req.params;
      const user = await userManagementService.getUser(id);

      res.json({
        success: true,
        data: user,
      });
    } catch (error: any) {
      if (error instanceof NotFoundError) {
        res.status(404).json(error.toApiResponse());
        return;
      }

      res.status(500).json({
        success: false,
        error: {
          code: 'GET_USER_FAILED',
          message: error.message || 'Failed to get user',
        },
      });
    }
  }
}

Xử Lý Lỗi với Custom Error Classes

Example from codebase / Ví dụ từ codebase:

// services/iam-service/src/errors/http-error.ts
export class HttpError extends Error {
  public readonly statusCode: number;
  public readonly errorCode: string;
  public readonly isOperational: boolean;
  public readonly details?: any;

  constructor(
    message: string,
    statusCode: number = 500,
    errorCode: string = 'INTERNAL_ERROR',
    isOperational: boolean = true,
    details?: any
  ) {
    super(message);
    this.name = this.constructor.name;
    this.statusCode = statusCode;
    this.errorCode = errorCode;
    this.isOperational = isOperational;
    this.details = details;
    Error.captureStackTrace(this, this.constructor);
  }

  toApiResponse() {
    return {
      success: false,
      error: {
        code: this.errorCode,
        message: this.message,
        ...(this.details && { details: this.details }),
      },
      timestamp: new Date().toISOString(),
    };
  }
}

export class NotFoundError extends HttpError {
  constructor(resource: string = 'Resource / Tài nguyên', details?: any) {
    super(`${resource} not found / ${resource} không tìm thấy`, 404, 'NOT_FOUND', true, details);
  }
}

export class ValidationError extends HttpError {
  constructor(message: string = 'Validation failed / Validation thất bại', details?: any) {
    super(message, 422, 'VALIDATION_ERROR', true, details);
  }
}

Thực Hành Tốt Nhất

Đặt Tên Resource

• ✅ Use plural nouns (/users not /user) / Sử dụng danh từ số nhiều
• ✅ Use kebab-case for multi-word resources (/user-profiles) / Sử dụng kebab-case cho resource nhiều từ
• ✅ Keep URLs as short as possible / Giữ URLs ngắn gọn nhất có thể
• ❌ Avoid verbs in URLs (use HTTP methods instead) / Tránh động từ trong URLs (dùng HTTP methods thay thế)

Phiên Bản Hóa

• ✅ Include version in URL (/v1/users) / Bao gồm version trong URL
• ✅ Maintain backward compatibility / Duy trì tương thích ngược
• ✅ Deprecate old versions gracefully with warnings / Ngừng hỗ trợ các version cũ một cách lịch sự với cảnh báo

Bảo Mật

• ✅ Always use HTTPS / Luôn sử dụng HTTPS
• ✅ Implement rate limiting / Triển khai rate limiting
• ✅ Validate all inputs with DTOs / Validate tất cả inputs với DTOs
• ✅ Use proper authentication/authorization middleware / Sử dụng middleware xác thực/ủy quyền phù hợp
• ✅ Never expose sensitive data in responses / Không bao giờ expose dữ liệu nhạy cảm trong responses

Hiệu Năng

• ✅ Implement pagination for lists (use skip and take) / Triển khai pagination cho danh sách
• ✅ Use field filtering when possible (select in Prisma) / Sử dụng field filtering khi có thể
• ✅ Cache responses appropriately / Cache responses phù hợp
• ✅ Compress responses (gzip) / Nén responses (gzip)

Tài Liệu

• ✅ Keep OpenAPI spec up to date / Giữ OpenAPI spec cập nhật
• ✅ Include examples in documentation / Bao gồm ví dụ trong tài liệu
• ✅ Document error responses / Tài liệu hóa error responses
• ✅ Version your documentation / Phiên bản hóa tài liệu

Xử Lý Lỗi

• ✅ Use consistent error response format / Sử dụng định dạng error response nhất quán
• ✅ Provide actionable error messages / Cung cấp thông báo lỗi có thể hành động
• ✅ Include error codes for programmatic handling / Bao gồm error codes cho xử lý lập trình
• ✅ Log errors server-side, don't expose stack traces in production / Log lỗi phía server, không expose stack traces trong production

Ví Dụ Từ Dự Án

Ví Dụ Controller

• User Management: services/iam-service/src/modules/identity/user/user.controller.ts
• Feature Controller: services/iam-service/src/modules/feature/feature.controller.ts
• RBAC Controller: services/iam-service/src/modules/rbac/rbac.controller.ts

Ví Dụ DTO

• Identity DTOs: services/iam-service/src/modules/identity/identity.dto.ts
• Auth DTOs: services/iam-service/src/modules/auth/auth.dto.ts
• RBAC DTOs: services/iam-service/src/modules/rbac/rbac.dto.ts

Ví Dụ Xử Lý Lỗi

• HTTP Error Classes: services/iam-service/src/errors/http-error.ts
• Error Middleware: services/iam-service/src/middlewares/error.middleware.ts

Tham Khảo Nhanh

Bảng Tra Cứu Định Dạng Response

Scenario / Tình Huống	Status Code	Response Structure / Cấu Trúc Response
Success (GET)	200	{ success: true, data: {...} }
Success (POST)	201	{ success: true, data: {...} }
Success (DELETE)	200	{ success: true, message: "..." }
Validation Error / Lỗi Validation	400/422	{ success: false, error: { code, message, details } }
Not Found	404	{ success: false, error: { code: "NOT_FOUND", message } }
Unauthorized	401	{ success: false, error: { code: "UNAUTHORIZED", message } }
Forbidden	403	{ success: false, error: { code: "FORBIDDEN", message } }
Server Error / Lỗi Server	500	{ success: false, error: { code: "INTERNAL_ERROR", message } }

Pattern DTO Thường Dùng

// DTO Tạo
const CreateDto = z.object({
  requiredField: z.string().min(1),
  optionalField: z.string().optional(),
});

// DTO Cập Nhật (tất cả fields tùy chọn)
const UpdateDto = z.object({
  field1: z.string().optional(),
  field2: z.number().optional(),
});

// DTO Query/Filter
const QueryDto = z.object({
  page: z.number().int().min(1).default(1),
  limit: z.number().int().min(1).max(100).default(20),
  search: z.string().optional(),
  sortBy: z.string().optional(),
  order: z.enum(['asc', 'desc']).default('desc'),
});

Skills Liên Quan

• Database Prisma: For database operations and repository patterns / Cho các thao tác database và repository patterns
• Security: For authentication, authorization, and security best practices / Cho xác thực, ủy quyền và thực hành bảo mật tốt nhất
• Testing Patterns: For testing API endpoints / Cho test API endpoints
• Documentation: For writing API documentation / Cho viết tài liệu API

Tài Nguyên

Tài Liệu Bên Ngoài

• REST API Design Best Practices
• HTTP Status Codes
• Zod Documentation
• OpenAPI Specification

Tài Liệu Nội Bộ

• API Reference
• Service Communication
• Project Rules