Lesson 2.3: HTTP Semantics

Thời lượng: 25 phút
Level: Beginner
Yêu cầu: Kiến thức cơ bản về giao thức HTTP.

Mục tiêu bài học

Sau bài học này, bạn sẽ:

• Sử dụng đúng các HTTP Methods (GET, POST, PUT, PATCH, DELETE).
• Phân biệt và sử dụng đúng các HTTP Status Codes phổ biến.
• Hiểu khái niệm An toàn (Safety) và Idempotency trong thiết kế API.

Nội dung chính

1. HTTP Methods: Động từ của API

Trong RESTful API, tài nguyên (Resource) là danh từ, còn HTTP Method là động từ.

• Safe (An toàn): Không làm thay đổi trạng thái server (chỉ đọc).
• Idempotent (Tuần hoàn): Gửi yêu cầu 1 lần hay 10 lần thì kết quả cuối cùng trên server vẫn giống hụt nhau.

2. HTTP Status Codes: Câu trả lời của Server

Đừng bao giờ trả về 200 OK cho mọi yêu cầu rồi kèm theo lỗi bên trong body. Hãy sử dụng Status Codes đúng nghĩa của nó.

Nhóm 2xx (Thành công)

• 200 OK: Thành công chung.
• 201 Created: Tạo mới thành công (thường dùng cho POST).
• 204 No Content: Thành công nhưng không có dữ liệu trả về (thường dùng cho DELETE).

Nhóm 4xx (Lỗi từ Client)

• 400 Bad Request: Dữ liệu client gửi lên sai định dạng hoặc thiếu.
• 401 Unauthorized: Chưa đăng nhập hoặc Token hết hạn.
• 403 Forbidden: Đã đăng nhập nhưng không có quyền truy cập tài nguyên này.
• 404 Not Found: Tài nguyên không tồn tại.

Nhóm 5xx (Lỗi từ Server)

• 500 Internal Server Error: Lỗi code, crash, database down...
• 503 Service Unavailable: Server quá tải hoặc đang bảo trì.

3. Nguyên tắc phối hợp (Best Practice)

Khi API trả về lỗi, sự kết hợp giữa Status Code và Response Envelope là chìa khóa:

1. Status Code: Cho Browser/Mobile App biết lỗi ở lớp vận chuyển (VD: 401 thì tự động chuyển hướng ra trang Signin).
2. Error Body: Cho lập trình viên biết lỗi cụ thể là gì để hiển thị cho người dùng.

Nguyên tắc then chốt

"Đừng bao giờ sử dụng GET để thay đổi dữ liệu."

Các hệ thống như Web Crawler, Proxy hay Browser có thể thực hiện GET tự động để tối ưu (caching). Nếu bạn viết GET /users/delete?id=1, tài khoản người dùng có thể bị xóa "một cách bí ẩn".

Thực hành

Bài tập 1: Chọn HTTP Method và Status Code phù hợp

Hãy điền thông tin phù hợp cho các hành động sau:

1. Đổi tên user: ____ /users/1 -> Trả về ____
2. Lấy danh sách sản phẩm: ____ /products -> Trả về ____
3. Đăng ký tài khoản: ____ /register -> Trả về ____ (khi thành công)
4. Xóa bài viết: ____ /posts/1 -> Trả về ____

Gợi ý:

Tình huống thực tế

Scenario 1: Lỗi 401 hay 403?

Bối cảnh: Bạn đang viết chức năng "Xóa bình luận".

• User A vào xóa bình luận của chính mình. (Thành công)
• User B (không đăng nhập) vào xóa bình luận của User A. -> Trả về lỗi gì?
• User C (đã đăng nhập, không có quyền admin) vào xóa bình luận của User A. -> Trả về lỗi gì?

Giải quyết:

• User B: Trả về 401 Unauthorized (Vì server chưa biết bạn là ai).
• User C: Trả về 403 Forbidden (Server biết bạn là C, nhưng C không có quyền xóa bài của A).

Câu hỏi phỏng vấn

Senior Level

1. Q: Phân biệt PUT và PATCH? Khi nào dùng cái nào? A: PUT dùng để thay thế hoàn toàn tài nguyên. Nếu bạn thiếu một trường trong payload, trường đó có thể bị set về null hoặc default. PATCH dùng để cập nhật một phần. Trong thực tế, PATCH thường được ưa chuộng hơn vì tiết kiệm băng thông và an toàn hơn khi cập nhật các object lớn.

Tóm tắt

Những điều cần nhớ

• Dùng đúng động từ (Method).
• Trả về đúng mã trạng thái (Status Code).
• GET và HEAD tuyệt đối không được làm thay đổi dữ liệu trên Server.
• Một API Design tốt là API mà lập trình viên chỉ cần nhìn Status Code là biết hướng xử lý sơ bộ.

Bước tiếp theo

🎉 Chúc mừng! Bạn đã hoàn thành Module 2: API Contracts.

Giờ bạn đã nắm vững:

• Cách thiết kế Contract trước khi code.
• Cách bọc dữ liệu (Envelope) nhất quán.
• Cách giao tiếp chuẩn xác thông qua HTTP Semantics.

Module tiếp theo: Module 3: REST Design Patterns - Đi sâu vào cách đặt tên tài nguyên, xử lý quan hệ cha-con và các hành động phức tạp.

Bắt đầu Module 2 →