Câu 1Trong hướng dẫn, "gọi API thời tiết" nghĩa là chương trình làm gì?
API là gì — quy ước trao đổi dữ liệu giữa các chương trình và JSON
Bài viết này nằm trong khóa Kiến thức nền tảng về CNTT, xây dựng từ đầu những kiến thức CNTT thực tế tối thiểu mà bạn cần để lập trình và vibe coding.
Gọi API nghĩa là gửi request tới một URL đã định và nhận về response. Các sơ đồ cho thấy cách đọc JSON và mã trạng thái.
Bài viết này nói về API.
API là quy ước để các chương trình trao đổi dữ liệu với nhau.
Bài viết đi qua ba thành phần của một lời gọi và JSON, định dạng chữ được trả về.
- Thực tế "gọi API" là gửi cái gì và gửi tới đâu
- Ba thành phần của một lời gọi — URL, method, response
- Cách đọc key và value của JSON được trả về
- Mã trạng thái cho biết thành công hay thất bại, và bước tiếp theo ứng với từng con số
"Gọi API" là gửi request tới một URL đã định và nhận về response
Dữ liệu thời tiết không nằm ở chương trình của bạn mà ở server của một dịch vụ bên ngoài.
API được gọi bằng request và response của HTTP gọi là Web API, và mỗi URL mà nó tiếp nhận là một endpoint.
Dịch vụ bên ngoài có thể là bên cung cấp, và server của my-app cũng vậy.
Và một màn hình cũng không nhất thiết chỉ gọi một endpoint.
Trước khi trang hiện ra đã có ba lượt gửi request và nhận response.
Thứ duy nhất trình duyệt kết nối trực tiếp là server của my-app.
Cùng một server đó là bên cung cấp khi nhìn từ trình duyệt, và là bên gọi khi nhìn từ API thời tiết.
Gọi API là gửi đi rồi nhận về
Gọi API là gửi request tới một URL đã định và nhận về response trả lại.
Mỗi URL như vậy là một endpoint; bên gọi có thể là trình duyệt hoặc server của chính bạn, và bên cung cấp cũng không nhất thiết là dịch vụ bên ngoài.
Ba thành phần của một lời gọi — URL, method, response
Tài liệu hướng dẫn và tài liệu kỹ thuật chỉ cho bạn ba thứ.
Gửi tới đâu (URL), bạn muốn làm gì (method), và cái gì được trả về (response).
Thứ nhất là URL, và vai trò của nó tách làm hai phần, trước và sau dấu ?.
https://api.example.com/weather?city=tokyo&units=metric
https://api.example.com/weather
- Phần trước dấu ?. Endpoint tiếp nhận request
- Đổi /weather thành /forecast là một endpoint khác
?city=tokyo&units=metric
- Phần sau dấu ?. Viết điều kiện cho dữ liệu bạn muốn ở đây
city=tokyo
- Điều kiện thứ nhất. Viết theo dạng tên=giá trị
units=metric
- Điều kiện thứ hai. Nối với điều kiện trước bằng dấu &
Phần sau dấu ? là tham số (query parameter — điều kiện cho dữ liệu bạn muốn, gắn vào cuối URL theo dạng tên=giá trị), cũng được gọi là tham số truy vấn.
Thành phần thứ hai là method (HTTP method — từ đã quy định như GET hay POST, cho biết request "muốn làm gì").
Bạn viết nó ở đầu dòng, và dù gửi tới cùng một URL thì hành vi vẫn khác đi.
GET không làm thay đổi dữ liệu bên kia, còn POST thì thay đổi ngay khi được gửi.
Tài liệu hướng dẫn ghi việc này theo dạng method đứng trước, URL đứng sau.
Dòng bắt đầu bằng # là phần giải thích, dòng ngay dưới nó là cách gọi.
# Lấy thời tiết. Đầu dòng là method, phía sau là URL (cuối là tham số)
GET https://api.example.com/weather?city=tokyo
# Đăng ký một đơn đặt chỗ. Cùng URL nhưng khác method thì hành vi khác
POST https://example.com/reservations
Tài liệu tập hợp cách gọi và hình dạng response trả về là tài liệu API (API reference).
Khi hướng dẫn nói "hãy xem tài liệu API", đó là nơi bạn tra ba thành phần.
Trước khi gửi, bạn chỉ tự quyết hai thứ
Trước khi gửi, bạn chỉ tự quyết hai thứ: gửi tới đâu và bạn muốn làm gì.
Gửi tới đâu là URL, phần trước dấu ? là endpoint; bạn muốn làm gì là method. Riêng thành phần thứ ba là response thì bạn không tự quyết được, mà đọc thứ trả về.
JSON là định dạng chữ ghi dữ liệu theo cặp key và value
"JSON trả về" trong hướng dẫn chính là phần thân của response.
JSON (JavaScript Object Notation — định dạng chỉ gồm chữ, ghi dữ liệu theo cặp key và value) là định dạng tiêu biểu dùng cho phần thân của Web API.
JSON mà API thời tiết trả về có dạng như sau.
{
"city": "Tokyo",
"temp": 23.5,
"rain": false,
"forecast": [
{ "day": "mon", "high": 25 },
{ "day": "tue", "high": 22 }
]
}
Những thứ xếp trong đó là các cặp key và value (key / value — tên đặt cho một giá trị là key, còn nội dung mà tên đó trỏ tới là value).
Với "temp": 23.5 thì temp là key, 23.5 là value; key và value nối với nhau bằng :, còn các cặp ngăn cách bằng ,.
Các cặp xếp bên trong { }, và value của chúng có khi lại là [ ] hoặc { }.
Một JSON (từ { đến })
"city": "Tokyo"
- Key là city, value là chuỗi Tokyo
"temp": 23.5
- Key là temp, value là số 23.5 (không bọc trong " ")
"rain": false
- Key là rain, value là false (một trong hai: true hoặc false)
"forecast": [ … ]
- Key là forecast, value là một mảng
{ "day": "mon", "high": 25 }
- Mục thứ nhất của mảng. Nội dung lại là các cặp key và value
{ "day": "tue", "high": 22 }
- Mục thứ hai của mảng. Có cùng các key với mục thứ nhất
Value thứ tư là mảng (array — nhiều giá trị xếp theo thứ tự bên trong [ ]), và từng mục lại được bọc trong { }.
{ } và [ ] lồng vào nhau bao nhiêu tầng cũng được.
Khi lấy một mục ra khỏi mảng, bạn trỏ tới nó bằng số như [0], và số đếm bắt đầu từ 0 chứ không phải từ 1.
Những value không phải [ ] hay { } được viết theo 3 kiểu, và bạn phân biệt bằng việc có dùng " " hay không.
Phần thân nhận về nguyên trạng là một chuỗi dài, nên dù có chỉ định key cũng không lấy được value.
Trong sách nhập môn, bạn đổi nó sang dạng đọc được theo key bằng một dòng như JSON.parse, rồi trỏ tới value bằng tên key như data.city.
| Dòng bạn đã viết | Nó tìm ở đâu trong JSON | Value lấy được |
|---|---|---|
| data.city | Key city ở ngoài | Tokyo |
| data.temp | Key temp ở ngoài | 23.5 |
| data.forecast[0].high | Key high trong mục đầu [0] của mảng | 25 |
| data.tmp | Không có key nào mang tên đó | undefined |
Chỉ riêng dòng dưới cùng là cố tình viết sai chính tả key một ký tự.
Viết sai chính tả không làm phát sinh lỗi, nên khi nhận được undefined, trước tiên hãy đối chiếu chính tả với JSON.
Trong tên có chữ JavaScript, nhưng nó được dùng cho response của API vì ngôn ngữ nào cũng đọc và ghi được.
JSON chỉ là dãy các cặp tên và nội dung
JSON chỉ là một dãy chữ ghi ra các cặp gồm một cái tên và nội dung của nó.
Tên là key, nội dung là value; khi nhận về nguyên trạng thì nó là một chuỗi dài, nên bạn đổi sang dạng đọc được theo key rồi mới lấy value ra.
Response không phải lúc nào cũng thành công — mã trạng thái quyết định việc bạn làm
API thời tiết chạy bên ngoài chương trình của bạn, nên lời gọi có thể thất bại.
Vì vậy response không chỉ gồm mỗi phần thân.
Hãy tách thứ trả về thành từng phần để xem.
Một response
Con số ba chữ số ở đầu
- 200 là thành công, 404 là thất bại
- Xem ở đây trước khi đọc phần thân
Phần thân (JSON)
- Cùng một API thời tiết nhưng nội dung đổi khác giữa thành công và thất bại
Phần thân khi thành công
- { "city": "Tokyo", "temp": 23.5 }
- Đọc được nhiệt độ từ key temp
Phần thân khi thất bại
- { "error": "city not found" }
- Không có key temp, chỉ có lý do
Ba chữ số ở đầu là mã trạng thái (status code — con số cho biết thành công hay thất bại và thuộc loại nào).
Hãy xem con số trước, và chỉ đọc key từ phần thân khi thành công.
Bạn không cần học thuộc cả ba chữ số; chữ số đầu tiên quyết định việc làm tiếp theo.
Cùng một API thời tiết, nhưng con số trả về thay đổi tùy nội dung bạn gửi và tình trạng của bên cung cấp.
Ngoài 404, khi bên cung cấp gặp sự cố thì API trả về 500.
404 không chỉ là con số cho "không có trang đó": với API, nó còn trả về khi không có dữ liệu nào khớp với điều kiện của tham số.
Khi gọi đúng hướng dẫn mà nhận 404, hãy đối chiếu chính tả và tham số với tài liệu API.
Trong các con số bắt đầu bằng 4, 401 là con số cho trường hợp không có thứ nào cho biết bên gọi là ai, hoặc thứ đó không đúng.
Thứ bạn gắn vào request để cho biết điều đó là API key.
Xem con số trước rồi mới đọc phần thân
Khi response trả về, hãy xem con số trước rồi mới đọc phần thân.
Bắt đầu bằng 2 thì phần thân có key bạn cần; bắt đầu bằng 4 thì sửa URL và điều kiện đã gửi; bắt đầu bằng 5 thì đợi một lát rồi gọi lại.
QUIZ
Kiểm tra kiến thức
Hãy trả lời từng câu hỏi một.
Câu 2Trong đoạn JSON "temp": 23.5, temp là gì?
Câu 3Khi bạn gọi API thời tiết và nhận về mã trạng thái 404, bạn kiểm tra điều gì đầu tiên?