Authentication/token (khái niệm cơ bản)
API thường cần token để xác thực và giới hạn quyền truy cập. Khuyến nghị:- Token theo môi trường (dev/test/prod)
- Xoay token định kỳ (rotation)
- Không hardcode token trong client public (frontend)
Endpoint patterns (mẫu endpoint thường dùng)
Read (GET)
- Lọc theo trạng thái/thời gian/owner
- Phân trang khi dữ liệu lớn
Create (POST)
- Map payload vào field cho phép
- Trả về ID/mã record để theo dõi
Update (PUT/PATCH)
- Cập nhật theo record ID hoặc External ID
- Chỉ mở field cần thiết, tránh cập nhật vượt ownership
Upload (tệp đính kèm)
- Giới hạn loại file/dung lượng
- Chỉ định record đích rõ ràng
Ví dụ
Ví dụ 1 — Hệ thống ngoài tạo ticket vào app
- POST tạo record Ticket
- Workflow phân công người xử lý và gửi thông báo
Ví dụ 2 — Hệ thống ngoài pull danh sách record theo filter
- GET trả về record theo trạng thái và thời gian
- Client lưu External ID để đối chiếu
Error handling (xử lý lỗi)
- Chuẩn hoá lỗi: thiếu field, sai định dạng, không đủ quyền
- Retry có kiểm soát để tránh tạo trùng (dựa trên External ID hoặc idempotency key)
- Log requestId/correlationId để truy vết (nếu có)
Guardrails
- Chỉ mở endpoint và field cần thiết
- Thiết lập filter để giới hạn phạm vi dữ liệu được đọc
- Tách token read-only và write