⭐ Python Developer · Chặng 9Bài 1/6Bài học~45 phút

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.

HTTP và REST cho backend developer: phương thức, mã trạng thái

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
  1. 1. Một request và một response trông thế nào
  2. 2. Các phương thức và ý nghĩa
  3. 3. Mã trạng thái: nói đúng chuyện gì đã xảy ra
  4. 4. Thiết kế REST: đường dẫn là danh từ
  5. 5. Phiên bản và tài liệu
  6. Tóm tắt
  7. Bài tập

Ở 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) /get và 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ĩaAn toànLặp lại cho cùng kết quả
GETĐọc dữ liệuCóCó
POSTTạo mới, hoặc hành động không thuộc loại khácKhôngKhông
PUTThay thế toàn bộ một tài nguyênKhôngCó
PATCHSửa một phần tài nguyênKhôngKhông nhất thiết
DELETEXóaKhôngCó

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 OKThành công, có dữ liệu trả về
201 CreatedĐã tạo tài nguyên mới (sau POST)
204 No ContentThành công, không có body (thường sau DELETE)
400 Bad RequestRequest sai cú pháp hoặc vi phạm quy tắc nghiệp vụ
401 UnauthorizedChư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 FoundKhông có tài nguyên
409 ConflictXung đột trạng thái, ví dụ email đã được đăng ký
422 Unprocessable ContentDữ 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 ErrorLỗ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ệcPhương thức + đường dẫnThành côngLỗi thường gặp
Liệt kê công việcGET /cong-viec?trang_thai=dang_lam&limit=20200422
Tạo công việcPOST /cong-viec201422
Xem một công việcGET /cong-viec/42200404
Sửa một phầnPATCH /cong-viec/42200404, 422
XóaDELETE /cong-viec/42204404
Bình luận của công việcGET /cong-viec/42/binh-luan200404
  • Tránh động từ trong đường dẫn: POST /tao-cong-viec, GET /xoa-cong-viec?id=42 là 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).

Công cụ thử APINgoài 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, POST tạo, PUT thay, PATCH sửa một phần, DELETE xóa; chỉ GET là 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ệcEndpointThành côngLỗi
Đăng kýPOST /auth/dang-ky201409 (trùng tên), 422
Đăng nhập lấy tokenPOST /auth/token200401
Người dùng hiện tạiGET /nguoi-dung/toi200401
Liệt kê, lọcGET /cong-viec?trang_thai=&skip=&limit=200401, 422
TạoPOST /cong-viec201401, 422
XemGET /cong-viec/{id}200401, 404
Sửa (kể cả giao việc, đổi trạng thái)PATCH /cong-viec/{id}200401, 403, 404, 422
XóaDELETE /cong-viec/{id}204401, 403, 404
Thống kêGET /cong-viec/thong-ke200401

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

  1. 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.
  2. 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.

Bài tiếp theo
Ban biên tập HocFree

Chúng tôi viết những bài hướng dẫn dễ hiểu, thực tế để ai cũng có thể tự học lập trình và AI, hoàn toàn miễn phí.