Nén và bộ nhớ đệm

Các lượt đọc công khai lớn như GET /markets có dung lượng hàng megabyte JSON. Hãy yêu cầu nén và để header Cache-Control trên mỗi phản hồi cho bạn biết dữ liệu mới đến mức nào.

Nén

Gửi Accept-Encoding: gzip và API sẽ trả về phần thân được nén gzip kèm Content-Encoding: gzip. GET /markets giảm từ khoảng 4 MB xuống khoảng 0,6 MB.

• Trình duyệt và fetch của Node.js gửi header này và tự động giải nén.
• Rust hypercall-client bật gzip trong HTTP client của nó, vì vậy mọi lệnh gọi REST đều yêu cầu nén và giải mã một cách trong suốt.
• Python requests và httpx mặc định gửi header và giải nén. urllib thuần không làm cả hai, nên bạn sẽ nhận phần thân chưa nén.
• curl cần tùy chọn --compressed.

Các phản hồi dưới khoảng 1 KB được gửi ở dạng không nén. Khung WebSocket không bị ảnh hưởng; xem Nén WebSocket.

Cache-Control

Mọi lượt đọc đều cho bạn biết liệu bộ nhớ đệm dùng chung có được phép lưu giữ nó hay không.

Header phản hồi	Nơi bạn thấy nó	Ý nghĩa
public, max-age=N	Dữ liệu thị trường công khai: /markets, /instruments, /instrument-specs, /exchange-info, greeks, tóm tắt quyền chọn và ngày đáo hạn, giá trị lý thuyết lịch sử, lượt đọc pool, /version	Bất kỳ bộ nhớ đệm nào cũng có thể tái sử dụng phần thân trong tối đa N giây. Phần lớn là từ 1 đến 15 giây; dữ liệu lịch sử có thể lâu hơn.
public, max-age=N, stale-while-revalidate=M	Một số lượt đọc ở trên	Sau N giây, bộ nhớ đệm có thể tiếp tục phục vụ phần thân cũ thêm tối đa M giây trong khi tải bản mới ở chế độ nền.
no-store	Lượt đọc theo phạm vi ví và đã xác thực: danh mục, lệnh đang mở, khớp lệnh, giao dịch lọc theo ví, cấu hình MMP và tương tự	Không bao giờ được lưu bởi bất kỳ bộ nhớ đệm nào. Mọi yêu cầu đều đến API.
không có	Mọi thứ khác, bao gồm /orderbook và tất cả thao tác ghi	Không được lưu đệm.

Hãy coi một lượt đọc public có thể cũ tới max-age giây (cộng thêm stale-while-revalidate nếu có). Khi bạn cần trạng thái mới nhất cho quyết định giao dịch, hãy đọc từ các kênh WebSocket hoặc từ lượt đọc theo phạm vi ví, vốn không bao giờ được lưu đệm.

Phản hồi lỗi (4xx, 5xx) không bao giờ mang public và không bao giờ được lưu đệm. Bộ nhớ đệm không tiếp tục phục vụ phần thân đã hết hạn khi API đang trả về lỗi; bạn sẽ nhận được lỗi.

Các yêu cầu luôn đến API

Phần thân đã lưu đệm không bao giờ được trả về cho yêu cầu mang bất kỳ mục nào sau đây, và không có gì mà yêu cầu đó nhận được được lưu lại:

• Authorization hoặc Cookie
• X-Hypercall-Signature hoặc X-Hypercall-Expires-At-Ms (lượt đọc có chữ ký như cấu hình MMP)
• X-Hypercall-Fence hoặc X-Hypercall-Fence-Wait (nhất quán đọc-sau-ghi, xem Bảo vệ nhà tạo lập thị trường)
• X-Hypercall-Gateway-Token hoặc X-Admin-Key
• bất kỳ phương thức nào khác ngoài GET hoặc HEAD, và các yêu cầu nâng cấp WebSocket

Fence đọc-sau-ghi và bộ nhớ đệm không bao giờ kết hợp với nhau. Route nào tuân theo X-Hypercall-Fence đều là no-store, và route public không bao giờ chờ fence.

X-Cache-Status

Các phản hồi đi qua bộ nhớ đệm biên (edge cache) của Hypercall mang header X-Cache-Status:

Giá trị	Ý nghĩa
HIT	Được phục vụ từ bộ nhớ đệm biên, trong khoảng max-age.
MISS	Được tải từ API. Nếu phản hồi là public, giờ nó đã được lưu đệm.
BYPASS	Yêu cầu mang một header trong danh sách ở trên, nên đi thẳng đến API và không có gì được lưu.
EXPIRED	Bản sao lưu đệm đã quá thời hạn, nên API được hỏi lại.
STALE hoặc UPDATING	Được phục vụ từ bộ nhớ đệm trong khoảng stale-while-revalidate trong khi bản mới đang được tải.

Thao tác ghi và các yêu cầu không phải GET khác không có X-Cache-Status. Header này chỉ mang tính thông tin: đừng phân nhánh logic giao dịch dựa trên nó. Không phải môi trường nào cũng đã có bộ nhớ đệm biên. Phản hồi không có header này đến thẳng từ API.