Hành vi chuẩn của API

TL;DR — Trang này là hợp đồng. Mọi con số và quy tắc mà nhiều trang cùng dựa vào đều nằm ở đây, đúng một lần: xác thực, phân trang, thời hạn và cách tái sử dụng vé, độ mới của từng câu trả lời, chính sách retry, lỗi, rate limit và phiên bản. Các trang khác giải thích và link về đây; nếu hai trang nói khác nhau, trang này thắng.

Xác thực#

Header Wandura-Version sai bị trả 400 trước cả khi key được xem tới. Key mà Wandura không kiểm tra kịp sẽ trả 503 service_unavailable: key vẫn ổn, hãy retry. Thời gian tạo, xoay vòng và thu hồi key nằm ở Bảo mật.

Phân trang#

Ba endpoint trả về theo trang. Cả ba theo cùng quy tắc: cursor là opaque (chép nguyên, không bao giờ tự dựng hay giải mã), và bạn dừng khi cursor kế tiếp là null, không bao giờ dừng vì một trang ngắn hay rỗng.

Các trang catalog không phải một ảnh chụp duy nhất#

Mỗi trang catalog được cắt ra từ catalog đúng ở thời điểm trang đó được trả. Nếu Wandura publish hoặc rút một phim, hoặc một giấy phép bắt đầu hay kết thúc, trong lúc bạn duyệt các trang, một phim có thể bị bỏ sót hoặc xuất hiện hai lần giữa các trang. Đồng bộ an toàn như sau:

1. Nếu catalog của bạn chỉ vài trăm phim trở xuống, hãy gọi GET /catalog không có limit: một response là một ảnh chụp nhất quán.
2. Nếu phân trang, hãy loại trùng theo id của phim (bản sau thắng).
3. Chỉ áp dụng việc rút phim sau một lượt duyệt trọn vẹn: mọi trang đều trả 200. Lượt duyệt hỏng giữa chừng không thay đổi gì.
4. Chỉ đánh dấu một phim không khả dụng khi nó vắng mặt trong hai lượt duyệt trọn vẹn liên tiếp. Phim bị bỏ sót một lần do catalog đang thay đổi sẽ quay lại ở lượt sau.

Hướng dẫn đồng bộ catalog cài đặt đúng như vậy.

Feed creative không có khoảng hở này với các bản ghi không đổi: nó được sắp theo thời điểm cập nhật rồi theo ID, nên các bản cập nhật mới rơi vào sau những trang bạn đã đọc. Bản ghi được cập nhật trong lúc bạn duyệt sẽ xuất hiện lại ở lần đồng bộ sau.

Vé playback#

Thời hạn#

Vé không bao giờ được gia hạn, và một khi đã cấp thì không thu hồi được: nó phát đến expires_at kể cả khi giấy phép kết thúc hay key bị thu hồi một giây sau đó. GET /config cho biết cả hai thời hạn với key của bạn (playback.grant_ttl_seconds, playback.manifest_url_ttl_seconds).

Mỗi vé một thiết bị#

Vé gắn với các giá trị thiết bị mà nó được cấp cho (union_info và drm_kek). Nó chỉ giải mã được trên thiết bị đó. Không bao giờ đưa vé sang thiết bị khác, và không bao giờ cache vé dưới một khoá không chứa thiết bị.

Tái sử dụng#

Tái sử dụng vé là được phép và nên làm, theo các quy tắc sau:

Lượt xem được đếm từ các request play. Khi người xem bắt đầu một tập, luôn gửi một request có "intent": "play" cho tập đó, kể cả khi app khởi động player bằng một vé đã prefetch trước. Vé prefetch không phải lượt xem.

Batch#

Một request có thể xin tối đa 3 vé: episodes (1–3 mục) hoặc một tập neo kèm next (0–2). Mỗi vé tính 1 vào giới hạn playback. Mỗi mục có status riêng; các mục được nhận lần lượt từng cái, mục prefetch sau cùng. Cả request chỉ bị 429 khi không mục nào được cấp. Chi tiết: Xin playback.

Độ mới: một câu trả lời có thể cũ đến đâu#

Wandura phục vụ từ các cache ngắn hạn, nên một thay đổi phía Wandura đến tay bạn sau một độ trễ có giới hạn. Đây là các giới hạn trên.

• Nhiều server. Mỗi server của Wandura giữ cache riêng, nên hai lệnh gọi cách nhau vài giây có thể trả về ảnh chụp hơi khác nhau. Điều đó là bình thường.
• Khi cơ sở dữ liệu của Wandura gặp sự cố, việc kiểm tra catalog và giấy phép được phục vụ từ câu trả lời tốt gần nhất trong tối đa 5 phút (stale-if-error), thay vì báo lỗi. Một thay đổi Wandura đã thấy (rút phim, tạm ngưng) không bao giờ bị hoàn tác vì cơ chế này.
• Vé đã cấp không bao giờ bị thu hồi: chúng phát đến expires_at (≤ 30 phút).

Nên cache gì ở phía bạn, và trong bao lâu: Caching.

Retry#

Chính sách retry duy nhất cho mọi lệnh gọi tới Wandura. Các ví dụ cài đặt đúng chính sách này.

Backoff. Khi có Retry-After, chờ đúng số giây đó cộng thêm ngẫu nhiên 0–1 giây. Nếu không, chờ một khoảng ngẫu nhiên từ 0 đến min(cap, base × 2^attempt) (full jitter).

Ngân sách retry. Trong một tiến trình, số retry tối đa là 10 % số request của phút vừa qua (không bao giờ dưới 10 mỗi phút). Khi hết ngân sách, hãy báo lỗi ngay thay vì dồn thêm tải.

Đồng thời. Duyệt từng trang một, không bao giờ song song. Chỉ retry các mục lỗi của một batch, mỗi mục sau retry_after của riêng nó. Request xin vé được retry với cùng viewer_ref và giá trị thiết bị thường trả về cùng vé, nên không bị tính hai lần.

Lỗi#

• Hai định dạng: object phẳng { "error", "error_code" } ở catalog, playback, config và videos; envelope { "code", "message", "server_time" } (không có data) ở lỗi của creatives. 429 và 400 unsupported_version của creatives dùng định dạng phẳng.

• Rẽ nhánh theo error_code (creatives: code). Mã lạ: quyết định theo nhóm status, như trong bảng retry ở trên.

• Retry-After đi kèm 429 và các 503 nên retry.

• Mọi response đều mang header Wandura-Request-Id, và mọi body lỗi JSON đều có trường request_id. Hãy dẫn nó khi liên hệ hỗ trợ.

Mọi status và mã lỗi, theo từng endpoint, kèm cách xử lý: Lỗi.

Rate limit#

Giới hạn tính theo tổ chức (không theo key), theo từng bộ đếm, với đơn vị như trong bảng.

• Chỉ request có key hợp lệ mới bị đếm.
• Việc đếm là xấp xỉ, có thể cao hơn thực tế tới khoảng 2,5 %.
• Khi gần chạm giới hạn playback, vé prefetch bị từ chối trước (429, "reason": "prefetch_shed", khi còn dưới khoảng 20 % hạn mức), và một request play có thể bị giữ tới 0,5 giây thay vì bị từ chối.
• GET /config báo giới hạn hiện tại của bạn cho mọi bộ đếm trừ video.
• Wandura có thể nâng bất kỳ giới hạn nào cho tổ chức của bạn khi bạn yêu cầu.

Hành vi khi tải cao, và cách xử lý: Rate limit.

Phiên bản#

Chính sách và các header báo ngừng hỗ trợ: Phiên bản và tiến hoá API.

Header về caching#

Mọi response của Delivery API, kể cả vé, đều mang Cache-Control: no-store và không đặt cookie nào. Không bao giờ lưu chúng trong cache dùng chung (CDN hay proxy): vé, link đã ký và catalog của bạn chỉ thuộc về tổ chức của bạn.

Liên quan#

• Tổng quan tài liệu tham chiếu API
• Lỗi
• Bảo mật