Developer Guide

Xác thực và bảo mật

• Gửi token trong header Authorization, không đưa vào URL.
• Luôn dùng HTTPS cho mọi request.
• Không chia sẻ token với bên thứ ba.
• Đổi token định kỳ và thu hồi ngay khi nghi ngờ lộ.

Giới hạn tốc độ

• Giới hạn cụ thể do hợp đồng tích hợp quy định.
• Dùng cache để giảm số request lặp lại.
• Xử lý mã lỗi 429 (Too Many Requests).
• Thử lại với khoảng chờ tăng dần (exponential backoff).

Xử lý lỗi

• Luôn kiểm tra HTTP status code.
• Xử lý lỗi có kiểm soát, không để ứng dụng dừng đột ngột.
• Ghi log chi tiết để truy vết.
• Cân nhắc circuit breaker khi phụ thuộc nhiều dịch vụ.

Phân trang

Dùng cursor khi dữ liệu lớn để kết quả ổn định giữa các trang.

GET /api/v1/products?limit=10&cursor=eyJpZCI6MTAwfQ==

{
  "data": [...],
  "next_cursor": "eyJpZCI6MTEwfQ==",
  "has_more": true
}

Lọc dữ liệu

Dùng query parameter để lọc theo nhiều tiêu chí.

GET /api/v1/orders?status=processing&from=2024-01-01&to=2024-12-31

GET /api/v1/products?category[]=electronics&category[]=accessories

Thao tác hàng loạt

Gộp nhiều bản ghi vào một request khi cần xử lý số lượng lớn.

POST /api/v1/products/bulk
{
  "items": [
    { "name": "Product 1", "price": 100 },
    { "name": "Product 2", "price": 200 }
  ]
}