API Là Gì?

Level 7 — MCP, API & Connectors Bài 1/11

Thời gian đọc: 6-8 phút

API Là Gì?

Cơ chế cụ thể sau 'đường dây' API đã học ở L6 bài 55: 1 request gồm method/endpoint/headers/body, 1 response gồm status code/headers/body. 5 method HTTP (GET/POST/PUT/PATCH/DELETE) và cách đọc tài liệu API trước khi gọi.

🎯 Bản chất cốt lõi ⚡️ Thực chiến ứng dụng 🛠️ Quy trình chuẩn 💡 Tối ưu hiệu suất

Chế độ đọc:

📖 Đọc đầy đủ (7 phút) ⚡️ Tóm tắt nhanh (3 phút)

Tóm Tắt Nhanh Trong 3 Phút — Trọng Tâm Bài Học

1. Bản chất cốt lõi

Nắm vững nguyên lý và khái niệm nền tảng trước khi đi vào công cụ thực tế.

2. Thực thi chuẩn xác

Áp dụng quy trình từng bước, case study thực chiến và template mẫu có sẵn.

3. Tối ưu & Vận hành

Kiểm tra checklist hoàn thành, né tránh các sai lầm kinh điển để vận hành bền vững.

CHẶNG 1 · BẢN CHẤT & NGUYÊN LÝ

Phần 1: Bản chất & Nguyên lý

Nắm vững các khái niệm nền tảng, cơ chế hoạt động và mô hình tư duy cốt lõi.

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

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

🎯 BẢN CHẤT

Đọc và giải thích được 1 API request thật: endpoint, method, header, parameter.

🏗️ CẤU TRÚC

Đọc và giải thích được 1 API response thật: status code, body.

⚡️ NGUYÊN LÝ

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.

🛠️ THỰC CHIẾN

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

Điều bạn đã biết từ bài 55 (L6), 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ể?

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. 1 request (yêu cầu) gồm 4 phần:

• 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:

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: 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

Chu trình 1 API call (vẫn ở mức khái niệm phổ quát):

1. 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.
2. Client gửi request tới server qua mạng.
3. Server xử lý, thực hiện hành động tương ứng (đọc/tạo/sửa/xóa dữ liệu).
4. Server trả về response: status code + dữ liệu (nếu có).

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ệ”).

CHẶNG 2 · THỰC CHIẾN ỨNG DỤNG

Phần 2: Thực chiến ứng dụng

Quy trình thực thi từng bước, case study cụ thể và bộ prompt/template áp dụng ngay.

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

Checklist đọc hiểu 1 API documentation lần đầu:

1

Endpoint base là gì? (ví dụ: api.example.com)

2

Tài nguyên nào bạn cần thao tác có endpoint cụ thể nào? (ví dụ: /notes, /notes/{id})

3

Method nào tương ứng với việc bạn muốn làm?

4

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)

5

Body cần những trường (field) nào, định dạng gì? (thường JSON)

6

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ế

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 (tạo issue mới, dùng method POST tới /repos/{owner}/{repo}/issues).

8. Prompt/template/workflow

Đâ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 — 1 request đầy đủ 4 phần (method/endpoint/header/body) bay từ client sang server, và 1 response bay ngược lại.

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

1. 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.
2. Xác định: để lấy dữ liệu 1 tài nguyên cụ thể, bạn cần method và endpoint nào?
3. 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.
4. 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)?

CHẶNG 3 · TỐI ƯU & BẢO TRÌ

Phần 3: Tối ưu & Checklist

Checklist kiểm tra mức độ sẵn sàng, nhận diện các bẫy sai lầm và nguyên tắc vàng vận hành.

11. Checklist

Đặt lại 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, không phải quan sát độc lập.)

⚠️ LƯU Ý QUAN TRỌNG

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).

⚠️ LƯU Ý QUAN TRỌNG

Quên header Authorization khi API yêu cầu xác thực — dẫn tới lỗi 401.

⚠️ LƯU Ý QUAN TRỌNG

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.

⚠️ LƯU Ý QUAN TRỌNG

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.

15. Best practices

Nguyên tắc 1

Luôn đọc tài liệu API trước khi gọi, không đoán mò cấu trúc.

Nguyên tắc 2

Dùng đúng method cho đúng mục đích (GET để đọc, không tạo tác dụng phụ).

Nguyên tắc 3

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.

Nguyên tắc 4

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.

Thông tin chuyên sâu & Nguồn tham khảo

⚠️ 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.

📚 17. Nguồn tham khảo

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 (không trích dẫn mới): bài 55 (mô hình 4 lớp, L6); bài 62 (nguyên tắc secrets, L6); bài 64 (kinh nghiệm gọi API AI đầu tiên, L6).