HTTP và REST cho backend developer: phương thức, mã trạng thái
Nền tảng trước khi viết API: request, response, GET, POST, PUT, PATCH, DELETE, mã trạng thái, header, JSON và thiết kế REST.
Học xong bài này, bạn sẽ
- Hiểu phương thức, đường dẫn, header, body, mã trạng thái
- Thiết kế endpoint REST theo tài nguyên
- Đọc request, response bằng công cụ của trình duyệt và curl
Nên học trước: Thực hành: phân tích dữ liệu bán hàng từ SQLite
Nội dung bài viết
Ở chặng 7 bạn đã gọi Web API của người khác. Từ chặng này, bạn xây API cho người khác gọi: ứng dụng di động, trang web, hệ thống khác trong công ty. Trước khi viết dòng FastAPI đầu tiên, cần hiểu rõ ngôn ngữ chung của mọi API: giao thức HTTP và phong cách thiết kế REST. Phần lớn lỗi thiết kế API của người mới đến từ việc bỏ qua bài này.
1. Một request và một response trông thế nào
$ curl -i "https://httpbin.org/get?thanh_pho=hue" -H "Accept: application/json"
HTTP/1.1 200 OK
content-type: application/json
content-length: 255
date: Thu, 29 Oct 2026 09:35:42 GMT
{
"args": {
"thanh_pho": "hue"
},
"headers": {
"Accept": "application/json",
"Host": "httpbin.org",
"User-Agent": "curl/8.1.2"
},
"method": "GET",
"origin": "203.0.113.7",
"url": "https://httpbin.org/get?thanh_pho=hue"
}
curl có sẵn trên Windows 10 trở lên, macOS và Linux; -i in cả phần đầu của response. Request mà curl đã gửi gồm:
- Phương thức (method):
GET. - Đường dẫn (path)
/getvà chuỗi truy vấn (query string)?thanh_pho=hue. - Header: cặp khóa – giá trị mô tả request, như
Accept: application/json(muốn nhận JSON),Authorization(thông tin đăng nhập). - Body: dữ liệu gửi kèm (với
POST,PUT,PATCH); request này không có.
Response gồm mã trạng thái (200 OK), header (content-type: application/json) và body. HTTP là giao thức không trạng thái: mỗi request độc lập, máy chủ không tự nhớ request trước; muốn biết "ai đang gọi" thì mỗi request phải tự mang thông tin xác thực (bài JWT).
2. Các phương thức và ý nghĩa
| Phương thức | Ý nghĩa | An toàn | Lặp lại cho cùng kết quả |
|---|---|---|---|
GET | Đọc dữ liệu | Có | Có |
POST | Tạo mới, hoặc hành động không thuộc loại khác | Không | Không |
PUT | Thay thế toàn bộ một tài nguyên | Không | Có |
PATCH | Sửa một phần tài nguyên | Không | Không nhất thiết |
DELETE | Xóa | Không | Có |
An toàn: không làm thay đổi dữ liệu. Lặp lại cho cùng kết quả (idempotent): gửi một lần hay mười lần thì trạng thái cuối giống nhau. Đây là lý do ở chặng 7 ta chỉ tự thử lại GET: thử lại POST /don-hang có thể tạo hai đơn. Không bao giờ dùng GET để xóa hay sửa dữ liệu: trình duyệt, công cụ quét và bộ nhớ đệm có thể tự gọi GET bất cứ lúc nào.
3. Mã trạng thái: nói đúng chuyện gì đã xảy ra
| Mã | Khi nào trả |
|---|---|
200 OK | Thành công, có dữ liệu trả về |
201 Created | Đã tạo tài nguyên mới (sau POST) |
204 No Content | Thành công, không có body (thường sau DELETE) |
400 Bad Request | Request sai cú pháp hoặc vi phạm quy tắc nghiệp vụ |
401 Unauthorized | Chưa đăng nhập hoặc token không hợp lệ |
403 Forbidden | Đã đăng nhập nhưng không có quyền |
404 Not Found | Không có tài nguyên |
409 Conflict | Xung đột trạng thái, ví dụ email đã được đăng ký |
422 Unprocessable Content | Dữ liệu sai định dạng, thiếu trường (FastAPI dùng mã này khi kiểm tra dữ liệu thất bại) |
500 Internal Server Error | Lỗi trong code của máy chủ |
Quy tắc dễ nhớ: 2xx thành công, 4xx lỗi do client (client phải sửa request), 5xx lỗi do máy chủ (bạn phải sửa code). Trả 200 kèm body {"loi": "không tìm thấy"} là lỗi thiết kế phổ biến: client, công cụ giám sát và bộ nhớ đệm đều tưởng mọi thứ ổn.
4. Thiết kế REST: đường dẫn là danh từ
REST tổ chức API quanh tài nguyên (danh từ: công việc, người dùng, đơn hàng), còn hành động thể hiện qua phương thức HTTP:
| Việc | Phương thức + đường dẫn | Thành công | Lỗi thường gặp |
|---|---|---|---|
| Liệt kê công việc | GET /cong-viec?trang_thai=dang_lam&limit=20 | 200 | 422 |
| Tạo công việc | POST /cong-viec | 201 | 422 |
| Xem một công việc | GET /cong-viec/42 | 200 | 404 |
| Sửa một phần | PATCH /cong-viec/42 | 200 | 404, 422 |
| Xóa | DELETE /cong-viec/42 | 204 | 404 |
| Bình luận của công việc | GET /cong-viec/42/binh-luan | 200 | 404 |
- Tránh động từ trong đường dẫn:
POST /tao-cong-viec,GET /xoa-cong-viec?id=42là phong cách sai. - Dùng danh từ số nhiều hoặc thống nhất một kiểu, chữ thường, gạch ngang giữa các từ.
- Path parameter (
/cong-viec/42) xác định tài nguyên nào; query parameter (?trang_thai=...) để lọc, sắp xếp, phân trang. - Body request và response dùng JSON; tên trường thống nhất một kiểu (bài này dùng
chu_thuong_gach_duoi, giống tên biến Python).
5. Phiên bản và tài liệu
Khi đã có người dùng API, đổi tên trường hay xóa endpoint sẽ làm hỏng ứng dụng của họ. Cách phổ biến: đặt tiền tố phiên bản /api/v1/..., thay đổi phá vỡ thì ra /api/v2 và giữ v1 một thời gian. API cũng cần tài liệu chính xác; chuẩn OpenAPI mô tả mọi endpoint, tham số, kiểu dữ liệu bằng JSON, và FastAPI tự sinh tài liệu này từ code của bạn (bài sau).
curl, bạn có thể dùng trang /docs mà FastAPI tự tạo, extension REST Client hoặc Thunder Client trong VS Code, hoặc các ứng dụng như Bruno, Postman, Insomnia. Thử bằng công cụ trước, viết test tự động sau (bài kiểm thử API).Tóm tắt
- Request: phương thức, đường dẫn, query, header, body; response: mã trạng thái, header, body. HTTP không trạng thái.
GETđọc,POSTtạo,PUTthay,PATCHsửa một phần,DELETExóa; chỉGETlà an toàn.- 2xx thành công, 4xx lỗi client, 5xx lỗi máy chủ; trả đúng mã, đừng trả 200 cho lỗi.
- REST: đường dẫn là danh từ, hành động là phương thức; path xác định tài nguyên, query để lọc và phân trang.
Bài tập
Bài 1. Thiết kế API quản lý công việc
Nhóm 5 người cần API quản lý công việc: người dùng đăng ký, đăng nhập; tạo, xem, sửa, xóa công việc; lọc theo trạng thái; giao việc cho thành viên; thống kê số việc theo trạng thái. Lập bảng endpoint: phương thức, đường dẫn, mã thành công, mã lỗi chính.
Xem đáp án
| Việc | Endpoint | Thành công | Lỗi |
|---|---|---|---|
| Đăng ký | POST /auth/dang-ky | 201 | 409 (trùng tên), 422 |
| Đăng nhập lấy token | POST /auth/token | 200 | 401 |
| Người dùng hiện tại | GET /nguoi-dung/toi | 200 | 401 |
| Liệt kê, lọc | GET /cong-viec?trang_thai=&skip=&limit= | 200 | 401, 422 |
| Tạo | POST /cong-viec | 201 | 401, 422 |
| Xem | GET /cong-viec/{id} | 200 | 401, 404 |
| Sửa (kể cả giao việc, đổi trạng thái) | PATCH /cong-viec/{id} | 200 | 401, 403, 404, 422 |
| Xóa | DELETE /cong-viec/{id} | 204 | 401, 403, 404 |
| Thống kê | GET /cong-viec/thong-ke | 200 | 401 |
Giao việc là sửa trường nguoi_nhan_id qua PATCH, không cần endpoint riêng kiểu POST /giao-viec. Đây chính là đặc tả của dự án cuối chặng 9.
Bài 2. Đọc response bằng curl
Dùng curl gọi https://httpbin.org/status/404 và https://api.frankfurter.dev/v2/currencies, đọc mã trạng thái và content-type của mỗi response.
Xem đáp án
$ curl -s -o /dev/null -w "%{http_code} %{content_type}\n" https://httpbin.org/status/404
404 text/html; charset=utf-8
$ curl -s -o /dev/null -w "%{http_code} %{content_type}\n" https://api.frankfurter.dev/v2/currencies
200 application/json; charset=utf-8
-o /dev/null bỏ body (trên Windows PowerShell dùng -o NUL), -w in các thông tin chọn lọc. Đây là cách nhanh để kiểm tra một endpoint còn sống, rất hay dùng trong script giám sát.
Nguồn tham khảo: MDN: An overview of HTTP; MDN: HTTP response status codes; RFC 9110: HTTP Semantics; OpenAPI Initiative.
Bài tập thực hành
- Thiết kế bảng endpoint cho API quản lý công việc: phương thức, đường dẫn, mã trạng thái thành công và lỗi.
- Dùng curl gọi một API công khai, đọc header và mã trạng thái trả về.
Làm xong bài tập mới chuyển sang bài tiếp theo: tự viết code là cách duy nhất để nhớ lâu.


