RESTful API Design: Hướng Dẫn Chi Tiết Với Ví Dụ Cho Người Mới¶

RESTful API là một kiểu thiết kế API web phổ biến, giúp các ứng dụng giao tiếp với nhau một cách chuẩn mực. Dưới đây là 8 nguyên tắc quan trọng với ví dụ cụ thể:

1. Thiết Kế Theo Mô Hình Domain (Domain Model Driven)¶

Khái niệm: Cấu trúc đường dẫn API nên phản ánh mô hình domain (các đối tượng nghiệp vụ) của ứng dụng.

Ví dụ thực tế: Ứng dụng quản lý thư viện

Domain model: User (người dùng), Book (sách), Author (tác giả)

✅ Đúng:
GET /users          # Lấy danh sách người dùng
GET /books          # Lấy danh sách sách
GET /authors        # Lấy danh sách tác giả
GET /users/123/books # Lấy sách của user ID 123

❌ Sai:
GET /getUserList
GET /getBookInfo
GET /showAllAuthors

2. Chọn HTTP Methods Phù Hợp¶

Khái niệm: Sử dụng đúng các phương thức HTTP cơ bản. Tránh dùng PATCH nếu team chưa hiểu rõ.

Ví dụ quản lý sản phẩm:

✅ Các methods cơ bản:
GET /products          # Lấy danh sách sản phẩm
POST /products         # Tạo sản phẩm mới
PUT /products/123      # Cập nhật toàn bộ sản phẩm ID 123
DELETE /products/123   # Xóa sản phẩm ID 123

⚠️ PATCH (nâng cao):
PATCH /products/123    # Cập nhật một phần sản phẩm
Body: {"price": 100}   # Chỉ cập nhật giá

Lưu ý: PATCH có thể gây nhầm lẫn vì cần định nghĩa rõ cập nhật từng phần như thế nào.

3. Triển Khai Idempotence Đúng Cách¶

Khái niệm: Idempotent có nghĩa là gọi API nhiều lần cho kết quả giống như gọi 1 lần.

Ví dụ:

✅ GET là idempotent tự nhiên:
GET /users/123  # Gọi 10 lần vẫn trả về thông tin user 123

✅ POST cần thiết kế để idempotent:
POST /orders
Body: {
  "idempotency_key": "order_2024_001", # Khóa duy nhất
  "product_id": 123,
  "quantity": 2
}

# Gọi lần 1: Tạo đơn hàng mới
# Gọi lần 2,3,4...: Trả về đơn hàng đã tạo (không tạo mới)

Lợi ích: Tránh tạo trùng dữ liệu khi có lỗi mạng, người dùng click nhiều lần.

4. Chọn HTTP Status Codes Phù Hợp¶

Khái niệm: Chỉ dùng một số mã status cơ bản để đơn giản hóa việc phát triển.

Ví dụ ứng dụng blog:

✅ Các mã status cơ bản:
200 OK                 # Thành công
201 Created           # Tạo mới thành công
400 Bad Request       # Dữ liệu đầu vào sai
401 Unauthorized      # Chưa đăng nhập
403 Forbidden         # Không có quyền
404 Not Found         # Không tìm thấy
500 Internal Error    # Lỗi server

Ví dụ:
GET /posts/999 → 404 (bài viết không tồn tại)
POST /posts → 201 (tạo bài viết thành công)
DELETE /posts/123 → 200 (xóa thành công)

5. Versioning - Quản Lý Phiên Bản¶

Khái niệm: Thiết kế cách đánh phiên bản API từ đầu để dễ nâng cấp sau này.

Ví dụ API e-commerce:

✅ Trong URL:
https://api.shop.com/v1/products
https://api.shop.com/v2/products

✅ Trong Header:
GET /products
Headers: Accept: application/vnd.shop.v1+json

✅ Trong Query Parameter:
GET /products?version=1

Ví dụ thực tế:
v1: Sản phẩm chỉ có tên, giá
v2: Sản phẩm có thêm mô tả, hình ảnh
v3: Sản phẩm có thêm đánh giá, số lượng tồn kho

6. Đường Dẫn Có Ý Nghĩa (Semantic Paths)¶

Khái niệm: Đường dẫn API phải dễ hiểu, có thể đoán được chức năng.

Ví dụ hệ thống quản lý trường học:

✅ Dễ hiểu:
GET /students                    # Danh sách học sinh
GET /students/123               # Thông tin học sinh ID 123
GET /students/123/courses       # Khóa học của học sinh 123
GET /teachers/456/students      # Học sinh của giáo viên 456

❌ Khó hiểu:
GET /data?type=std
GET /info/user/123
GET /fetch_student_course_data

7. Xử Lý Hàng Loạt (Batch Processing)¶

Khái niệm: Dùng từ khóa batch hoặc bulk và đặt ở cuối đường dẫn.

Ví dụ quản lý nhân viên:

✅ Tạo nhiều nhân viên cùng lúc:
POST /employees/batch
Body: [
  {"name": "Nguyen Van A", "department": "IT"},
  {"name": "Tran Thi B", "department": "HR"},
  {"name": "Le Van C", "department": "Finance"}
]

✅ Xóa nhiều sản phẩm:
DELETE /products/bulk
Body: {"ids": [123, 456, 789]}

✅ Cập nhật giá hàng loạt:
PATCH /products/batch
Body: [
  {"id": 123, "price": 100000},
  {"id": 456, "price": 200000}
]

8. Ngôn Ngữ Truy Vấn (Query Language)¶

Khái niệm: Thiết kế hệ thống query params để API linh hoạt hơn.

Ví dụ API sản phẩm e-commerce:

✅ Phân trang (Pagination):
GET /products?page=2&limit=20  # Trang 2, mỗi trang 20 sản phẩm

✅ Sắp xếp (Sorting):
GET /products?sort=price       # Sắp xếp theo giá tăng dần
GET /products?sort=-price      # Sắp xếp theo giá giảm dần
GET /products?sort=name,price  # Sắp xếp theo tên, rồi theo giá

✅ Lọc (Filtering):
GET /products?category=laptop&price_min=10000000
GET /products?in_stock=true&brand=apple
GET /products?search=macbook

✅ Chọn fields:
GET /products?fields=id,name,price  # Chỉ trả về id, name, price

Ví dụ kết hợp:
GET /products?category=phone&price_max=20000000&sort=-price&page=1&limit=10
# Lấy 10 điện thoại giá dưới 20 triệu, sắp xếp từ cao xuống thấp, trang đầu

Tóm Tắt Cho Người Mới:¶

Đặt tên theo đối tượng nghiệp vụ (users, products, orders...)
Dùng HTTP methods cơ bản (GET, POST, PUT, DELETE)
Thiết kế để gọi nhiều lần không ảnh hưởng (idempotent)
Dùng mã trạng thái HTTP chuẩn (200, 404, 500...)
Có phiên bản từ đầu (v1, v2...)
Đường dẫn dễ hiểu (/users/123/orders)
Xử lý hàng loạt với /batch hoặc /bulk
Hỗ trợ tìm kiếm, sắp xếp, phân trang qua query params

Ví dụ API hoàn chỉnh cho blog:

GET /v1/posts?category=tech&sort=-created_at&page=1&limit=10
POST /v1/posts/batch
PUT /v1/posts/123
DELETE /v1/posts/bulk

Những nguyên tắc này giúp API dễ sử dụng, dễ bảo trì và mở rộng!