API là gì theo cách hiểu đơn giản?

API (Application Programming Interface) ở ngữ cảnh web thường là cách hai chương trình nói chuyện qua HTTP: client gửi request, server trả response. Bạn không 'vào website bằng mắt' mà gửi yêu cầu có cấu trúc (URL, method, header, body) và nhận dữ liệu (thường JSON).

Request và response khác nhau thế nào?

Request = những gì client gửi đi (method, URL, headers, body). Response = những gì server trả về (status code, headers, body). Debug API luôn cần nhìn cả hai phía — chỉ nhìn UI lỗi không đủ.

Có cần học Postman trước khi hiểu API không?

Không. Postman chỉ là công cụ gửi request thủ công. Nếu chưa hiểu method, status, JSON thì collection Postman sẽ thành copy-paste. Nên nắm request/response trên DevTools Network trước, rồi mới dùng Postman để lặp lại và chia sẻ.

JSON trong API dùng để làm gì?

JSON là định dạng text phổ biến để đóng gói dữ liệu trong body request/response: object {}, mảng [], chuỗi, số, boolean, null. Frontend parse JSON thành object JavaScript; backend serialize object thành JSON. Sai dấu phẩy hoặc nhận HTML thay JSON là lỗi junior hay gặp.

GET và POST khác nhau ra sao?

GET thường lấy dữ liệu, tham số trên query (?id=1), không nên có body nghiệp vụ nặng. POST thường tạo/gửi dữ liệu, body JSON. Ngoài ra còn PUT/PATCH (cập nhật), DELETE (xóa). Method sai là nguyên nhân 404/405 phổ biến khi copy URL từ trình duyệt sang tool.

Làm sao xem API thật trong trình duyệt?

Mở DevTools → tab Network → tái hiện thao tác trên web → click request → xem Headers (URL, method, status) và Response (JSON). Đây là cách học API rẻ nhất trước khi cài Postman.

API là gì? Request, response & JSON cho

Kết luận

API web = hợp đồng request/response qua HTTP. Junior VN nên nắm bốn thứ trước Postman: URL + method, header (đặc biệt Content-Type, Authorization), body JSON, status code. Biết đọc tab Network là đã debug được 70% lỗi “API không chạy”. Postman hữu ích để lặp lại và chia sẻ — không thay thế việc hiểu request đang gửi gì.

Nhiều bạn năm nhất hoặc intern outsourcing được giao “làm UI gọi API” và tải Postman ngay. Collection có sẵn, bấm Send, thấy 401 — rồi không biết sửa ở đâu. Bài này dành cho giai đoạn trước Postman: API là gì, request/response trông ra sao, JSON đọc thế nào, và checklist để tự tin mở DevTools.

Ai nên đọc

Sinh viên / bootcamp lần đầu nghe “REST API”
Frontend junior nhận Swagger/OpenAPI mà chưa biết nhìn field nào
Freelance nhận project WordPress/React + “backend bên khách đã có API”
QA muốn mô tả lỗi đúng (không chỉ “bấm nút không được”)

Bạn không cần thuộc toàn bộ RFC. Cần một mental model đủ để đọc tài liệu và hỏi backend đúng câu.

API là gì (không dùng định nghĩa sách giáo khoa dài)

API ở ngữ cảnh web app thường nghĩa: máy khách (browser, app mobile, script) gửi yêu cầu HTTP tới máy chủ; máy chủ xử lý và trả kết quả.

Ví dụ đời thường trong team VN:

App giao đồ ăn cần danh sách món → GET /api/menus
Form đăng ký → POST /api/auth/register kèm JSON email/password
Dashboard admin xóa user → DELETE /api/users/42

Bạn không mở HTML trang /menus để “xem nguồn”. Bạn gọi endpoint và nhận dữ liệu (thường JSON) để UI tự render.

Không nhầm:

Khái niệm	Là gì	Không phải
API	Giao diện giữa chương trình	Chỉ riêng Postman
REST API	Phong cách thiết kế HTTP phổ biến	”Cái gì có URL cũng REST chuẩn 100%“
Endpoint	Một URL + method cụ thể	Toàn bộ server
Backend	Code xử lý request	Bắt buộc phải là “microservices”

Bốn phần của một request

Mỗi lần gọi API, client gửi tối thiểu:

Method — GET, POST, PUT, PATCH, DELETE…
URL — https://api.example.com/v1/orders?status=open
Headers — metadata: Content-Type: application/json, Authorization: Bearer …
Body (tùy method) — dữ liệu gửi kèm, hay là JSON

POST /v1/orders HTTP/1.1
Host: api.shop.vn
Content-Type: application/json
Authorization: Bearer eyJhbGciOi...

{
  "productId": "sku-91",
  "qty": 2,
  "note": "Giao sau 18h"
}

Đọc từng dòng:

POST = tạo đơn, không phải lấy danh sách
/v1/orders = resource “orders”, version v1
Content-Type bảo server: body là JSON (thiếu header này dễ 415 hoặc parse fail)
Authorization = bạn là ai (thiếu → thường 401)
Body = payload nghiệp vụ

Junior hay copy URL từ thanh địa chỉ trình duyệt (luôn là GET trang HTML) rồi dán vào Postman — sai method/path ngay từ đầu.

Response: status + body

Server trả về:

Status code — 200, 201, 400, 401, 404, 500…
Headers — ví dụ Content-Type: application/json
Body — JSON thành công hoặc object lỗi

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

{
  "id": "ord_8f2a",
  "status": "pending",
  "qty": 2
}

Nhóm status code cần nhớ trước Postman

Nhóm	Ý nghĩa	Việc làm của junior
2xx	Thành công	Đọc body — 200 vẫn có thể data rỗng
4xx	Request/client sai	Sửa URL, method, auth, JSON
5xx	Server/upstream lỗi	Thu thập log, đừng 'sửa frontend cho xong'

Chi tiết từng mã: xem cheat sheet HTTP status code. Ở giai đoạn này chỉ cần thuộc nhánh 4xx vs 5xx.

JSON: ngôn ngữ chung của hầu hết API hiện đại

JSON (JavaScript Object Notation) là text:

{
  "user": {
    "id": 15,
    "name": "An",
    "roles": ["editor", "viewer"],
    "active": true,
    "meta": null
  }
}

Quy tắc hay vấp:

Key gần như luôn là chuỗi trong dấu " "
Không được dấu phẩy thừa cuối cùng ở nhiều parser strict
null khác "" và khác field thiếu
Số không bọc ngoặc; chuỗi thì có

Lỗi kinh điển: API trả HTML trang login (<!DOCTYPE html>…) nhưng code gọi response.json() → Unexpected token <. Nguyên nhân thường 401/302 về trang login, không phải “JSON hỏng ngẫu nhiên”.

Khi body dài hoặc minify, dùng JSON Formatter trên trình duyệt (không cần đăng ký) để đọc field cho dễ — vẫn hiểu rằng formatter không thay API.

Ví dụ `fetch` tối thiểu (nhìn request thật)

const res = await fetch("https://api.example.com/v1/users/me", {
  method: "GET",
  headers: {
    Accept: "application/json",
    Authorization: `Bearer ${token}`,
  },
});

if (!res.ok) {
  // res.status: 401, 403, 500...
  const errText = await res.text();
  console.error(res.status, errText);
  throw new Error(`API ${res.status}`);
}

const data = await res.json();
console.log(data.name);

Điểm dạy cho junior:

fetch = gửi request; res = response
res.ok false với hầu hết 4xx/5xx — phải đọc status
Parse JSON chỉ khi chắc Content-Type là JSON
Token nằm header, không nhét vào query công khai nếu có thể tránh

POST kèm body:

await fetch("https://api.example.com/v1/notes", {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
    Authorization: `Bearer ${token}`,
  },
  body: JSON.stringify({ title: "Họp sprint", done: false }),
});

JSON.stringify biến object JS → chuỗi JSON trong body. Quên bước này là gửi "[object Object]" — backend validate fail (400/422).

Method: chọn đúng “động từ”

Method	Thường dùng khi	Body?
GET	Đọc danh sách / chi tiết	Hiếm (query trên URL)
POST	Tạo mới / hành động	Thường có JSON
PUT	Thay thế resource	Thường có
PATCH	Sửa một phần	Thường có
DELETE	Xóa	Tùy API

Case freelance VN: khách gửi “link API” là URL mở bằng trình duyệt được (GET + JSON). Bạn thử POST cùng path vì form UI là “tạo” → 405 Method Not Allowed. Đọc tài liệu method trước khi đoán.

Header quan trọng (chưa cần thuộc hết)

Content-Type: application/json — body request là JSON
Accept: application/json — muốn nhận JSON (một số API content negotiation)
Authorization: Bearer <token> — xác thực
X-Request-Id / correlation id — hữu ích khi escalate cho backend

CORS là lớp trình duyệt: gọi API domain khác từ frontend local có thể bị chặn dù Postman (không phải browser same-origin) vẫn 200. Junior tưởng “API die” — thật ra Postman thành công vì không áp CORS như Chrome. Khi đó cần proxy dev, cấu hình CORS phía server, hoặc test đúng origin.

Quy trình học: Network trước, Postman sau

DevTools Network vs Postman

Tiêu chí	Network tab	Postman / Insomnia
Thấy request app thật gửi	Có — đúng header cookie/token app	Phải tự dựng lại
Cần cài app	Không	Có (hoặc web)
Lặp lại & chia team	Khó hơn	Mạnh — collection, env staging/prod
Học khái niệm lần đầu	Nên bắt đầu đây	Dễ bấm Send mà không hiểu

Checklist 10 phút (lab / intern day-1)

Mở web app mẫu → DevTools → Network → lọc Fetch/XHR
Bấm một nút (login, load list) → click request xuất hiện
Ghi: method, URL, status
Tab Payload/Request: có JSON không? field nào?
Tab Response: JSON thành công hay message lỗi?
Đổi cố ý token sai (nếu được) → quan sát 401 — gắn status với nguyên nhân
Sau đó mới import cùng request vào Postman để gọi lại không cần UI

Cách này khớp thực tế outsourcing: bạn thường debug trên staging có UI trước, ít khi có collection đẹp từ ngày đầu.

Case study: “API lỗi” mà chưa mở Postman

Bối cảnh: Intern frontend, form tạo note gọi POST /api/notes, UI hiện toast đỏ.

Bước đọc Network:

Quan sát	Ý nghĩa
Status 401	Thiếu/sai token — kiểm tra login & header Authorization
Status 400 + `"title is required"`	Body JSON thiếu field — so với docs
Status 200 nhưng UI lỗi	Có thể parse sai field (`data.item` vs `data`) — không phải “API down”
Status 500	Thu thập URL + thời điểm + body lỗi, hỏi backend; đừng đoán sửa CSS

Intern gửi Slack: “POST /api/notes 401, chưa có Authorization trong request” — backend giúp trong 2 phút. Nếu chỉ gửi “API không chạy”, mất cả buổi.

Lỗi tư duy cần tránh

Tưởng Postman = API — Postman chỉ là client thủ công
Chỉ nhìn UI — luôn đối chiếu Network
Coi mọi lỗi là backend — 4xx thường do request
Dán token vào chat công khai — dùng env local, che PII khi hỏi mentor
Parse JSON khi body là HTML — đọc Content-Type và 10 ký tự đầu response
Nhầm query và body — GET ?id=1 khác POST { "id": 1 }

Thuật ngữ tối thiểu để đọc Swagger

Path / route — /users/{id}
Path param — id trong URL
Query param — sau ? (page=2&limit=20)
Schema — hình dạng JSON (field, type, required)
Auth — bearer, API key, cookie session…

Khi mentor gửi OpenAPI: tìm endpoint → method → Request body schema → Responses 200/4xx. Không cần generate code ngay ngày đầu.

Bước tiếp theo (sau bài này)

Đọc HTTP status code cheat sheet khi gặp 401/403/422
Luyện đọc JSON minify bằng JSON Formatter
Khi đã vững request/response: học Postman environments (staging vs prod)
Rồi mới tới JWT, rate limit, pagination — từng lớp một

Công cụ Kawa chạy local trên trình duyệt — phù hợp lab trường không muốn tạo tài khoản SaaS chỉ để format JSON hay tra status.

Câu hỏi thường gặp

REST khác GraphQL thế nào (một câu)?
REST thường nhiều URL theo resource; GraphQL thường một endpoint, client mô tả field cần lấy. Junior hầu hết gặp REST trước — nắm HTTP + JSON vẫn nền tảng cho cả hai.

API private và public khác gì?
Public: có docs, key, rate limit rõ. Private: chỉ app của công ty, thường cần VPN/cookie đăng nhập. Cách đọc request/response giống nhau.

Có phải lúc nào cũng JSON?
Không — vẫn còn form-urlencoded, multipart upload file, XML legacy. Nhưng JSON là mặc định bạn sẽ gặp trên job fresher 2026.

Localhost gọi API production được không?
Về HTTP có thể; về CORS, auth, IP allowlist có thể không. Staging riêng vẫn an toàn hơn khi học.

Liên kết liên quan

HTTP status code 4xx/5xx
JSON Formatter
So sánh công cụ debug API (khi đã sẵn sàng tool workflow)
Danh sách công cụ
Lộ trình học

Công cụ