Skip to content

Latest commit

 

History

History
353 lines (282 loc) · 8.51 KB

API_GUIDE.md

File metadata and controls

353 lines (282 loc) · 8.51 KB

API Quản lý Người dùng - Hướng dẫn sử dụng

📋 Tổng quan

API RESTful để quản lý người dùng với đầy đủ tính năng:

  • ✅ Phân trang (Pagination)
  • ✅ Tìm kiếm (Search)
  • ✅ Lọc (Filter)
  • ✅ Sắp xếp (Sort)
  • ✅ Response tiếng Việt
  • ✅ Không trả về thông tin nhạy cảm (password)

🚀 API Endpoints

1. Lấy danh sách người dùng (GET)

Endpoint: GET /api/users

Query Parameters:

Tham số Kiểu Mặc định Mô tả
page int 0 Số trang (bắt đầu từ 0)
limit int 10 Số bản ghi mỗi trang
search string null Tìm kiếm theo tên hoặc email
userType string null Lọc theo loại: student hoặc staff
isActive boolean null Lọc theo trạng thái: true hoặc false
sortBy string createdAt Trường sắp xếp
sortDirection string desc Hướng sắp xếp: asc hoặc desc

Ví dụ Request:

# Lấy trang đầu tiên với 10 bản ghi
GET http://localhost:8080/api/users?page=0&limit=10

# Tìm kiếm người dùng có tên chứa "Nguyễn"
GET http://localhost:8080/api/users?search=Nguyễn

# Lọc sinh viên đang hoạt động
GET http://localhost:8080/api/users?userType=student&isActive=true

# Kết hợp nhiều điều kiện
GET http://localhost:8080/api/users?page=0&limit=20&search=Nguyễn&userType=student&isActive=true&sortBy=fullName&sortDirection=asc

Response (Success):

{
  "success": true,
  "message": "Danh sách người dùng đã được truy xuất thành công",
  "data": [
    {
      "userId": "550e8400-e29b-41d4-a716-446655440000",
      "email": "nguyen.van.a@example.com",
      "fullName": "Nguyễn Văn A",
      "userType": "student",
      "phoneNumber": "0123456789",
      "isActive": true,
      "createdAt": "2025-12-07T10:30:00",
      "updatedAt": "2025-12-07T10:30:00"
    }
  ],
  "pagination": {
    "page": 0,
    "limit": 10,
    "totalItems": 1,
    "totalPages": 1,
    "first": true,
    "last": true
  },
  "timestamp": "2025-12-07T10:35:00"
}

Response (Không tìm thấy):

{
  "success": true,
  "message": "Không tìm thấy người dùng phù hợp với điều kiện",
  "data": [],
  "pagination": {
    "page": 0,
    "limit": 10,
    "totalItems": 0,
    "totalPages": 0,
    "first": true,
    "last": true
  },
  "timestamp": "2025-12-07T10:35:00"
}

2. Lấy thông tin người dùng theo ID (GET)

Endpoint: GET /api/users/{id}

Ví dụ Request:

GET http://localhost:8080/api/users/550e8400-e29b-41d4-a716-446655440000

Response (Success):

{
  "success": true,
  "message": "Thông tin người dùng đã được truy xuất thành công",
  "data": {
    "userId": "550e8400-e29b-41d4-a716-446655440000",
    "email": "nguyen.van.a@example.com",
    "fullName": "Nguyễn Văn A",
    "userType": "student",
    "phoneNumber": "0123456789",
    "isActive": true,
    "createdAt": "2025-12-07T10:30:00",
    "updatedAt": "2025-12-07T10:30:00"
  },
  "timestamp": "2025-12-07T10:35:00"
}

Response (Lỗi - Không tìm thấy):

{
  "success": false,
  "message": "Không tìm thấy Người dùng với id: '550e8400-e29b-41d4-a716-446655440000'",
  "timestamp": "2025-12-07T10:35:00"
}

3. Tạo người dùng mới (POST)

Endpoint: POST /api/users

Request Body:

{
  "email": "nguyen.van.b@example.com",
  "fullName": "Nguyễn Văn B",
  "passwordHash": "hashed_password_here",
  "passwordSalt": "salt_here",
  "userType": "student",
  "phoneNumber": "0987654321",
  "isActive": true
}

Response (Success):

{
  "success": true,
  "message": "Người dùng đã được tạo thành công",
  "data": {
    "userId": "660e8400-e29b-41d4-a716-446655440001",
    "email": "nguyen.van.b@example.com",
    "fullName": "Nguyễn Văn B",
    "userType": "student",
    "phoneNumber": "0987654321",
    "isActive": true,
    "createdAt": "2025-12-07T10:40:00",
    "updatedAt": "2025-12-07T10:40:00"
  },
  "timestamp": "2025-12-07T10:40:00"
}

Response (Lỗi - Email đã tồn tại):

{
  "success": false,
  "message": "Người dùng đã tồn tại với email: 'nguyen.van.b@example.com'",
  "timestamp": "2025-12-07T10:40:00"
}

4. Cập nhật người dùng (PUT)

Endpoint: PUT /api/users/{id}

Request Body:

{
  "email": "nguyen.van.b.updated@example.com",
  "fullName": "Nguyễn Văn B (Đã cập nhật)",
  "passwordHash": "new_hashed_password",
  "passwordSalt": "new_salt",
  "userType": "staff",
  "phoneNumber": "0999999999",
  "isActive": true
}

Response (Success):

{
  "success": true,
  "message": "Thông tin người dùng đã được cập nhật thành công",
  "data": {
    "userId": "660e8400-e29b-41d4-a716-446655440001",
    "email": "nguyen.van.b.updated@example.com",
    "fullName": "Nguyễn Văn B (Đã cập nhật)",
    "userType": "staff",
    "phoneNumber": "0999999999",
    "isActive": true,
    "createdAt": "2025-12-07T10:40:00",
    "updatedAt": "2025-12-07T10:45:00"
  },
  "timestamp": "2025-12-07T10:45:00"
}

5. Xóa người dùng (DELETE)

Endpoint: DELETE /api/users/{id}

Ví dụ Request:

DELETE http://localhost:8080/api/users/660e8400-e29b-41d4-a716-446655440001

Response (Success):

{
  "success": true,
  "message": "Người dùng đã được xóa thành công",
  "data": null,
  "timestamp": "2025-12-07T10:50:00"
}

🔧 Test với PowerShell

Lấy danh sách người dùng

Invoke-RestMethod -Uri "http://localhost:8080/api/users?page=0&limit=10" -Method Get | ConvertTo-Json -Depth 10

Tìm kiếm người dùng

Invoke-RestMethod -Uri "http://localhost:8080/api/users?search=Nguyễn&userType=student" -Method Get | ConvertTo-Json -Depth 10

Tạo người dùng mới

$body = @{
    email = "test@example.com"
    fullName = "Người Dùng Test"
    passwordHash = "hashed_password"
    passwordSalt = "salt"
    userType = "student"
    phoneNumber = "0123456789"
    isActive = $true
} | ConvertTo-Json

Invoke-RestMethod -Uri "http://localhost:8080/api/users" -Method Post -Body $body -ContentType "application/json" | ConvertTo-Json -Depth 10

📚 Swagger UI

Truy cập Swagger UI để test API trực tiếp:

http://localhost:8080/swagger-ui.html

🎯 Các tính năng chính

1. Phân trang (Pagination)

  • Hỗ trợ page và limit
  • Trả về thông tin chi tiết: totalItems, totalPages, first, last

2. Tìm kiếm (Search)

  • Tìm kiếm không phân biệt chữ hoa/thường
  • Tìm theo tên (fullName) hoặc email
  • Sử dụng pattern matching với LIKE

3. Lọc (Filter)

  • Lọc theo userType: student hoặc staff
  • Lọc theo isActive: true hoặc false
  • Kết hợp nhiều điều kiện lọc

4. Sắp xếp (Sort)

  • Sắp xếp theo bất kỳ trường nào: createdAt, fullName, email, v.v.
  • Hỗ trợ cả asc (tăng dần) và desc (giảm dần)

5. Bảo mật

  • Không trả về passwordHash và passwordSalt trong response
  • Sử dụng DTO để kiểm soát dữ liệu trả về

6. Message tiếng Việt

  • Tất cả message đều bằng tiếng Việt
  • Rõ ràng, dễ hiểu cho người dùng Việt Nam

🛠️ Cấu trúc Response chuẩn

Response không phân trang (ApiResponse)

{
  "success": boolean,
  "message": "string (tiếng Việt)",
  "data": object | array | null,
  "timestamp": "ISO 8601 datetime"
}

Response có phân trang (PaginatedApiResponse)

{
  "success": boolean,
  "message": "string (tiếng Việt)",
  "data": array,
  "pagination": {
    "page": int,
    "limit": int,
    "totalItems": long,
    "totalPages": int,
    "first": boolean,
    "last": boolean
  },
  "timestamp": "ISO 8601 datetime"
}

⚠️ Lưu ý

  1. Database Connection: Đảm bảo Azure SQL Database đã được cấu hình đúng và có thể kết nối
  2. Firewall: Thêm IP của bạn vào Azure SQL Server firewall rules
  3. Validation: Các trường bắt buộc phải có giá trị hợp lệ
  4. UUID Format: ID phải đúng định dạng UUID

📞 Liên hệ

Nếu có vấn đề, vui lòng kiểm tra:

  1. Logs trong console
  2. Swagger UI để xem API documentation chi tiết
  3. Database connection trong application.properties