API Là Gì?

Level: L7 — MCP, API & Connectors (Bài 3/11 theo thứ tự sản xuất — · Đối tượng: Người đã học bài 55 (L6) — hiểu API là “đường dây” nối

1. Mục tiêu học tập

Sau bài này, bạn có thể:

Đọc và giải thích được 1 API request thật: endpoint, method, header, parameter.
Đọc và giải thích được 1 API response thật: status code, body.
Phân biệt 5 method HTTP phổ biến (GET/POST/PUT/DELETE/PATCH) và biết khi nào dùng cái nào.
Biết cách tìm và đọc tài liệu (documentation) của 1 API thật trước khi dùng nó.

2. Khái niệm cốt lõi

Bước 1 — Concept (điều bạn đã biết từ bài 55, dẫn chiếu không giải thích lại): API là “đường dây” giữa 2 hệ thống. Câu hỏi bài này trả lời: tờ đơn gửi qua đường dây đó trông như thế nào, cụ thể?

Bước 2 — Open standard (chuẩn HTTP, nền tảng phổ quát của phần lớn API web hiện nay, không gắn 1 hãng nào): phần lớn API hiện đại giao tiếp qua giao thức HTTP — cùng giao thức trình duyệt dùng để tải trang web [S102]. 1 request (yêu cầu) gồm 4 phần [S102]:

Method — động từ mô tả hành động muốn thực hiện.
Endpoint (path) — địa chỉ cụ thể của tài nguyên muốn thao tác (ví dụ: /users/123, không phải cả website).
Headers — thông tin bổ sung, bao gồm Authorization (credential xác thực, ví dụ API key — đào sâu ở bài 74).
Body/Parameters — dữ liệu gửi kèm (dùng ở 1 số method).

5 method HTTP phổ biến và mục đích [S102]:

Method	Mục đích
GET	Lấy dữ liệu, không thay đổi gì
POST	Tạo mới 1 tài nguyên
PUT	Thay thế toàn bộ 1 tài nguyên bằng dữ liệu mới
PATCH	Cập nhật 1 phần tài nguyên
DELETE	Xóa 1 tài nguyên

1 response (phản hồi) gồm [S102]: Status code (số cho biết request có thành công không — 200=thành công, 404=không tìm thấy, 401=chưa xác thực đúng), Headers, và Body (dữ liệu thực tế trả về, thường dạng JSON).

3. Tại sao nội dung này quan trọng

Bài 64 (L6) bạn đã tự tay gọi 1 API AI thật — nhưng lúc đó chưa hiểu cơ chế bên dưới. Từ bài này trở đi, mọi bài trong Level 7 (webhook, tool calling, MCP, các tích hợp thật 70-73) đều xây trên đúng 4 khái niệm vừa học: endpoint, method, header, body/response. Không hiểu đúng những khái niệm này, các bài sau sẽ chỉ là “làm theo hướng dẫn” mà không hiểu vì sao.

4. Cơ chế hoạt động

Bước 3 — Architecture (chu trình 1 API call, vẫn ở mức khái niệm phổ quát):

Client tạo 1 request: chọn đúng method, đúng endpoint, đính kèm header (bao gồm xác thực) và body nếu cần.
Client gửi request tới server qua mạng.
Server xử lý, thực hiện hành động tương ứng (đọc/tạo/sửa/xóa dữ liệu).
Server trả về response: status code + dữ liệu (nếu có).

Bước 4 — Real implementation (ví dụ cụ thể, cấu trúc chung của 1 API call thật, tổng hợp dựa trên S102):

POST /users HTTP/1.1
Host: api.example.com
Content-Type: application/json
Authorization: Bearer <api-key-cua-ban>

{
  "name": "Nguyễn Văn A",
  "email": "a@example.com"
}

Response trả về:

HTTP/1.1 201 Created
Content-Type: application/json

{
  "id": 42,
  "name": "Nguyễn Văn A",
  "email": "a@example.com"
}

5. Mental model

Tiếp nối ẩn dụ “mạng lưới nhà cung cấp” (mở đầu Level 7): endpoint là địa chỉ cụ thể của nhà cung cấp (không phải cả tòa nhà — 1 phòng ban cụ thể); method là loại yêu cầu bạn gửi (“tôi muốn xem” = GET, “tôi muốn đặt mới” = POST, “tôi muốn hủy” = DELETE); header Authorization là giấy tờ chứng minh bạn là khách hàng hợp lệ; status code là câu trả lời ngắn gọn của nhà cung cấp (“200 = đã xử lý xong,” “404 = không tìm thấy thứ bạn hỏi,” “401 = giấy tờ của bạn không hợp lệ”).

6. Hướng dẫn từng bước

Checklist đọc hiểu 1 API documentation lần đầu (tổng hợp của người viết):

Endpoint base là gì? (ví dụ: api.example.com)
Tài nguyên nào bạn cần thao tác có endpoint cụ thể nào? (ví dụ: /notes, /notes/{id})
Method nào tương ứng với việc bạn muốn làm? (xem bảng mục 2)
Header nào bắt buộc? Đặc biệt: có cần Authorization không, và định dạng thế nào? (đào sâu ở bài 74)
Body cần những trường (field) nào, định dạng gì? (thường JSON)
Response trả về status code và cấu trúc dữ liệu gì khi thành công? Khi lỗi?

7. Ví dụ thực tế

Bước 5 — Vendor example (dùng GitHub, đã quen từ bài 54, L6): GitHub cung cấp REST API công khai — ví dụ endpoint lấy thông tin 1 repository là GET /repos/{owner}/{repo}. Method GET vì chỉ đọc dữ liệu, không thay đổi gì. Không cần xác thực cho dữ liệu công khai, nhưng cần Authorization nếu muốn đọc dữ liệu riêng tư hoặc thực hiện thao tác ghi (ví dụ tạo issue mới, dùng method POST tới /repos/{owner}/{repo}/issues).

8. Prompt/template/workflow

Khung yêu cầu AI giải thích 1 API documentation lạ (tái sử dụng):

Đây là tài liệu API của [tên dịch vụ]: [dán link hoặc đoạn docs].
Giải thích cho tôi:
1. Endpoint nào tôi cần dùng để [mục tiêu cụ thể]?
2. Method là gì?
3. Header/xác thực nào bắt buộc?
4. Body cần những trường gì?
5. Response thành công trông như thế nào?

9. Visual hoặc diagram cần thiết

Hình 7.1 — API: cấu trúc đầy đủ request và response giữa client-server.

10. Bài tập thực hành

Chọn 1 API công khai bạn quan tâm (có thể dùng GitHub REST API). Đọc tài liệu của nó theo checklist mục 6.
Xác định: để lấy dữ liệu 1 tài nguyên cụ thể, bạn cần method và endpoint nào?
Dùng khung ở mục 8, nhờ AI giải thích lại đúng 4 phần của 1 API call cụ thể từ tài liệu bạn chọn.
Viết ra: nếu muốn dự án Notes App (dự án tích lũy) sau này gọi API này, request sẽ trông như thế nào (endpoint/method/header/body)?

11. Checklist

Đọc và giải thích được 4 phần của 1 API request thật.
Đọc và giải thích được cấu trúc của 1 API response thật.
Phân biệt được 5 method HTTP và biết khi nào dùng cái nào.
Biết cách tra cứu và đọc tài liệu API trước khi dùng.
Không nhầm nội dung bài này với mô hình 4 lớp kiến trúc (bài 55).

12. Lỗi thường gặp

(Suy luận từ nguyên tắc [S102], không phải quan sát độc lập.)

Dùng sai method — ví dụ dùng GET để gửi dữ liệu thay đổi (GET không nên có tác dụng phụ, chỉ nên đọc).
Quên header Authorization khi API yêu cầu xác thực — dẫn tới lỗi 401.
Không đọc tài liệu trước khi gọi — đoán mò cấu trúc endpoint/body, dễ gọi sai và nhận lỗi khó hiểu.
Nhầm status code 4xx (lỗi phía bạn — request sai) với 5xx (lỗi phía server) — 2 loại lỗi cần cách xử lý khác nhau.

13. Giới hạn & khi nào KHÔNG nên áp dụng

Bài này không dạy lại mô hình 4 lớp kiến trúc hay vai trò API nội bộ — xem bài 55 (L6) nếu cần ôn lại.
Không dạy cách xác thực chi tiết (API key vs OAuth, vòng đời credential) — đó là bài 74.
Không dạy cơ chế server chủ động gửi dữ liệu (không cần client hỏi trước) — đó là bài 66 (Webhook), hướng ngược lại với những gì bài này dạy.
Không phải mọi API đều theo đúng chuẩn REST/HTTP mô tả ở đây (có API dùng GraphQL, gRPC…) — bài này dạy kiểu phổ biến nhất, không phải duy nhất.

14. An toàn & quản trị (Safety/Governance)

Header Authorization chính là nơi API key/token của bạn xuất hiện — nguyên tắc “secrets không bao giờ nằm trong code” (bài 62, L6) áp dụng trực tiếp: API key gửi qua header không nên bị viết cứng (hardcode) trong code, và không nên commit lên Git (bài 54). Đây là lần đầu tiên trong Level 7 nguyên tắc đó xuất hiện lại trong ngữ cảnh cụ thể — sẽ được đào sâu đầy đủ ở bài 74.

15. Best practices

Luôn đọc tài liệu API trước khi gọi, không đoán mò cấu trúc.
Dùng đúng method cho đúng mục đích (GET để đọc, không tạo tác dụng phụ).
Kiểm tra status code của response trước khi xử lý body — status code 2xx mới nên coi là thành công.
Không bao giờ đặt API key/token trực tiếp trong code (dẫn chiếu bài 62/74).

16. Nội dung nâng cao (không bắt buộc)

Ngoài REST (kiểu API mô tả trong bài này — phổ biến nhất), còn có các kiểu API khác như GraphQL (client tự chọn chính xác trường dữ liệu cần, thay vì nhận toàn bộ response cố định) hay gRPC (hiệu năng cao, dùng nội bộ giữa các service) — vượt phạm vi người mới bắt đầu của Level 7, nhưng nếu gặp 1 API không theo cấu trúc REST như đã học, đây là lý do tại sao.

17. Nguồn tham khảo

[S102] An Overview of HTTP, MDN — developer.mozilla.org — cấu trúc request/response, 5 method HTTP, headers, status code.
GitHub REST API documentation — dùng làm ví dụ minh họa (dẫn chiếu, đã quen thuộc từ bài 54/L6).
Dẫn chiếu (không trích dẫn mới): bài 55 (mô hình 4 lớp, vai trò API nội bộ); bài 62 (nguyên tắc secrets, L6); bài 64 (kinh nghiệm gọi API AI đầu tiên, L6).

18. Ngày kiểm chứng

Nội dung kiểm chứng qua nguồn Tier 1 (S102) ngày 2026-07-13. Chuẩn HTTP/REST là kiến thức nền tảng rất ổn định, rủi ro lỗi thời thấp — khác các bài phụ thuộc 1 sản phẩm cụ thể sau này trong Level 7 (70-73).