API Intro: từ zero hiểu "đối thoại giữa program"
Core
API là gì? Như: thiết kế menu nhà hàng sao khách nhìn hiểu? Phục vụ ghi order sao không sai? API giải "program đối thoại với program thế nào". Ngày đầu code bạn đã dùng API, chỉ là chưa nhận ra.
0. 3 confusion thường gặp
Confusion 1: API là thứ cao siêu?
API không khó. Bạn đã dùng:
python
len("hello") # API của Python
open("file.txt") # API
requests.get(url) # APIConfusion 2: Web API vs API thường khác gì?
| Type | Calling | Communication | Use |
|---|---|---|---|
| Function API | Local code | Function call | len(), open() |
| OS API | OS | System call | Read/write file, create process |
| Web API | Remote server | HTTP request | Call AI model, get weather |
Confusion 3: HTTP hay SDK?
python
# HTTP: tự xử mọi detail
import requests
response = requests.post(
"https://api.deepseek.com/v1/chat/completions",
headers={"Authorization": "Bearer sk-xxx"},
json={"model": "deepseek-chat", "messages": [...]}
)
result = response.json()["choices"][0]["message"]["content"]
# SDK: butler xử giúp
from openai import OpenAI
client = OpenAI(api_key="sk-xxx")
response = client.chat.completions.create(
model="deepseek-chat",
messages=[...]
)
result = response.choices[0].message.content1. Bản chất API: plug + outlet
API (Application Programming Interface) = "thoả thuận đối thoại giữa program".
1.1 Ẩn dụ thiết bị điện
| Concept | Thiết bị | API |
|---|---|---|
| Interface | Hình dáng outlet | Function signature / URL |
| Input | Dòng điện vào | Param / request body |
| Output | Thiết bị work | Return value / response body |
1.2 3 dạng API
调用对象本地代码库
通信方式函数调用
延迟纳秒级
典型场景数据处理、文件操作
函数 API 示例
len("hello") # 返回 5
max([1, 5, 3]) # 返回 5
open("file.txt").read() # 读取文件1.3 Function vs HTTP API
📚 函数 API vs HTTP API本地调用 vs 网络请求，文档怎么看？
函数 API
调用方式直接函数调用
参数传递括号内传参
返回值直接获得结果
错误处理异常/返回值
Python 示例
# 调用内置函数
length = len("hello") # 返回 5
# 调用库函数
import math
result = math.sqrt(16) # 返回 4.0
# 调用自定义函数
def add(a, b):
return a + b
sum = add(3, 5) # 返回 8VS
HTTP API
调用方式网络请求
参数传递URL/Body/Header
返回值JSON/XML 响应
错误处理状态码判断
HTTP 请求示例
POST /v1/chat/completions HTTP/1.1
Host: api.deepseek.com
Authorization: Bearer sk-xxx
Content-Type: application/json
{
"model": "deepseek-chat",
"messages": [
{"role": "user", "content": "你好"}
]
}核心要点：函数 API 是"本地办事"，HTTP API 是"远程通信"。看文档时，函数关注参数和返回值，HTTP API 关注 Endpoint、认证和请求/响应格式。
1.4 Đọc doc khác loại
📋 不同文档类型怎么看函数文档、REST API 文档、SDK 文档，各有侧重点
🔍 看文档时重点关注
文档示例
### json.loads(s, *, cls=None, object_hook=None...)
将 JSON 字符串解析为 Python 对象
**参数：**
- s (str): 要解析的 JSON 字符串
- cls (JSONDecoder): 自定义解码器类
- object_hook (callable): 可选的转换函数
**返回值：**
- dict | list: 解析后的 Python 对象
**异常：**
- JSONDecodeError: 字符串格式非法
**示例：**
>>> import json
>>> json.loads('{"name": "Alice"}')
{'name': 'Alice'}阅读技巧
- 先看函数签名，了解需要什么参数
- 注意参数的类型和是否必填
- 查看返回值类型，方便后续处理
- 关注可能抛出的异常，做好错误处理
三种文档快速对比
对比项
函数文档
REST API 文档
SDK 文档
核心关注
参数、返回值
Endpoint、请求体
初始化、方法链
代码示例
函数调用
HTTP 请求
对象方法
错误处理
异常/返回值
状态码
异常对象
先看什么
函数签名
Base URL + Auth
Quick Start
阅读建议：函数文档看签名，API 文档看请求格式，SDK 文档看示例。遇到不会的，先找「Quick Start」或「Getting Started」章节。
2. Full API call
// 点击下方按钮，模拟不同的 API 请求
> ▋
客户端发起请求
等待请求...
HTTP Request→服务器处理请求
等待中...
HTTP Response←响应返回结果
等待响应...
💡 点击命令按钮，观察一次完整的 API 请求-响应流程。
2.1 4 stage
| Stage | Xảy ra gì | Ẩn dụ điện |
|---|---|---|
| Request | Client gửi request | Bấm switch |
| Transmission | Request qua network | Điện qua dây |
| Processing | Server xử + return | Thiết bị work |
| Response | Client nhận + xử kết quả | Đèn sáng |
2.2 Ẩn dụ nhà hàng
| Role | API | Note |
|---|---|---|
| Menu | API doc | Cho biết "món" nào order được |
| Phục vụ | HTTP protocol | Cách "đối thoại" chuẩn |
| Bếp | Server | Theo "order" xử |
| Mang món | Response | Trả kết quả |
3. HTTP methods
| Scenario | Bạn nói gì? | HTTP method |
|---|---|---|
| Muốn biết hôm nay có món gì | "Cho menu xem" | GET - chỉ "hỏi", không đổi data |
| Muốn order gà xào | "Cho 1 phần gà xào" | POST - "làm" việc, tạo data |
| Muốn đổi món | "Đổi gà xào thành cá kho" | PUT - replace data |
| Muốn đổi vị | "Gà xào không bỏ ớt" | PATCH - update partial |
| Không muốn nữa | "Bỏ món đó" | DELETE - xoá data |
get
获取
查询数据
幂等
post
创建
新增数据
不幂等
put
全量更新
替换资源
幂等
patch
部分更新
修改字段
不幂等
delete
删除
删除资源
幂等
get获取 - 查询数据
从服务器获取资源,不会修改任何数据
餐厅类比:"服务员,菜单给我看看"
GET /api/users # 获取用户列表
GET /api/users/123 # 获取单个用户
GET /api/products?cat=phone # 查询手机商品Idempotent
Idempotent: execute nhiều lần kết quả giống nhau?
- Idempotent (GET/PUT/DELETE): 10 lần và 1 lần giống nhau
- Không idempotent (POST): 10 lần có thể tạo 10 order
Solution: POST dùng unique ID verify, tránh xử lặp.
| Method | Use | Idempotent | Safe | Use |
|---|---|---|---|---|
| GET | Get | Có | Có | Query list, detail |
| POST | Create | Không | Không | New user, submit order |
| PUT | Update full | Có | Không | Replace user profile |
| PATCH | Update partial | Không | Không | Sửa nickname |
| DELETE | Delete | Có | Không | Xoá user, cancel order |
4. HTTP status codes
2xx成功
请求被成功接收、理解并处理
200 OK201 Created204 No Content
3xx重定向
需要进一步操作才能完成请求
301 永久移动304 未修改307 临时重定向
4xx客户端错误
请求包含错误或无法完成
400 参数错误401 未认证403 无权限404 不存在
5xx服务器错误
服务器无法处理有效请求
500 内部错误502 网关错误503 服务不可用
记忆技巧:2️⃣ 成功 • 3️⃣ 重定向 • 4️⃣ 客户端错 • 5️⃣ 服务器错
| Code | Nghĩa | Use | Client xử |
|---|---|---|---|
| 200 OK | Success | Request OK | Hiện data |
| 201 Created | Created | POST OK | Jump resource mới |
| 400 Bad Request | Format sai | Param thiếu hoặc format sai | Check param |
| 401 Unauthorized | No auth | Không có API Key valid | Dẫn user login |
| 403 Forbidden | No permission | API Key không quyền | Báo no permission |
| 404 Not Found | Not exist | URL hoặc resource không có | Check URL |
| 429 Too Many Requests | Quá rate limit | Vượt limit | Wait retry |
| 500 Internal Server Error | Server error | Server crash | Báo user retry sau |
// 点击按钮查看不同状态码的含义
> ▋
2xx 成功
200OK请求成功
201Created创建成功
204No Content成功但无返回内容
4xx 客户端错误
400Bad Request请求格式错误
401Unauthorized未认证
403Forbidden无权限
404Not Found资源不存在
422Unprocessable语义错误
429Too Many请求过多
5xx 服务端错误
500Server Error服务器内部错误
502Bad Gateway网关错误
503Unavailable服务不可用
💡 点击命令按钮，了解常见的 HTTP 状态码。
5. HTTP vs SDK
| 🏃 HTTP API | 🤵 SDK | |
|---|---|---|
| Ẩn dụ | Tự chạy việc | Butler làm |
| Ưu | Mọi ngôn ngữ dùng được Control mọi detail Không depend extra | Code gọn Auto xử auth Built-in retry |
| Nhược | Phải xử mọi detail Code dài, dễ sai | Cần cài dep Có thể vấn đề version |
| Code | requests.post(url, json=..., headers={...}) | client.chat.completions.create(...) |
| Scenario | Recommend | Lý do |
|---|---|---|
| Dev nhanh | SDK | Auto xử auth, error, retry |
| Học nguyên lý | HTTP | Hiểu underlying |
| Ngôn ngữ không hỗ trợ | HTTP | Mọi ngôn ngữ dùng được |
| Cần custom | HTTP | Control mọi detail |
Khuyến nghị
Có SDK thì dùng SDK, để chuyện phiền cho lib, time cho mình.
6. Đọc API doc
API doc = manual + menu. Không cần đọc từ đầu cuối, học "tra từ điển".
6.1 Checklist đọc doc
📖API 文档翻译机
Base URL
https://api.deepseek.comEndpoint
POST /v1/chat/completionsHeaders
Authorization: Bearer sk-xxx Content-Type: application/json
Body 参数
model必填模型名称
messages必填对话消息
temperature可选0-2，默认1
翻译成代码
from openai import OpenAI
client = OpenAI(
api_key="sk-xxx",
base_url="https://api.deepseek.com"
)
response = client.chat.completions.create(
model="deepseek-chat",
messages=[{"role": "user", "content": "你好"}]
)核心思想：看文档找三样：地址（Base URL）、鉴权（Authorization）、参数（Parameters）。
| Item | Note | Vd |
|---|---|---|
| Base URL | Root API | https://api.deepseek.com |
| Authentication | Cách verify identity | Authorization: Bearer sk-xxx |
| Endpoints | List interface | /v1/chat/completions |
| Parameters | Required/optional | model (required), temperature (optional) |
| Response | Data structure | {"choices": [...]} |
6.2 Step đọc
- Tìm Base URL - prefix mọi request
- Hiểu auth - API Key ở Header hay Query?
- Tìm Endpoint cần - interface bạn call
- Xem param - required/optional?
- Hiểu response format - data tổ chức thế nào?
7. Thực hành: mock API
🧪API 练手场随便玩，坏了算我的
点击发送查看结果
快速尝试：
Thử trigger:
- Success: nhập đúng Endpoint + API Key
- 401: không nhập API Key, server reject thế nào?
- 404: nhập URL không tồn tại
8. Tổng kết
Key
- API = truyền tin, đưa lời từ code này → code khác / remote server
- Bạn đã dùng API, từ
len()đếnopen()đều là API - Web API = superpower, call super computer ngoài xa
- SDK = butler tốt, có SDK thì dùng
- Đọc doc tìm 3 thứ: address, auth, param
AI era, chỉ cần nhớ concept core. Detail thì IDE + AI assistant lo.
Glossary
| Term | Full | Note |
|---|---|---|
| API | Application Programming Interface | Define software interact thế nào |
| Web API | - | API based on HTTP |
| Endpoint | - | Address cụ thể của API |
| HTTP | HyperText Transfer Protocol | Web API protocol |
| SDK | Software Development Kit | Wrap underlying API call |
| URL | Uniform Resource Locator | Network address |
| JSON | JavaScript Object Notation | Common data format |
| Authentication | - | Verify identity |
| Status Code | - | HTTP response status |
| Request | - | Request |
| Response | - | Response |
| Header | - | HTTP header, metadata |
| Payload | - | Actual data |
| Rate Limit | - | Rate limit |
| Idempotent | - | Multi exec same result |
| REST | Representational State Transfer | API architecture style |
| RPC | Remote Procedure Call | Remote procedure call |
| GraphQL | - | Query language API |
| gRPC | - | Google high-perf RPC |
2026 cho VN dev
- LLM API standard: OpenAI format trở thành de-facto (Anthropic, DeepSeek, Qwen đều có endpoint OpenAI-compatible)
- API client tool: Bruno (open-source Postman), Hoppscotch (web-based), HTTPie
- API doc tool: Swagger/OpenAPI (chuẩn), Scalar (đẹp), Stoplight
- Type-safe API: tRPC (TS), Hono RPC, OpenAPI gen client
- VN API ecosystem: payment (VNPay, MoMo, ZaloPay), SMS (Esms, Viettel), eKYC (FPT.AI, VinID)