Paano maglisensya at mag-download ng resource nang ligtas

Ang paglikha ng lisensya at ang paglikha ng orihinal na URL ay hiwalay, kaya ligtas ang mga retry at hindi na muling sisingilin ang mga sariwang URL.

1. Lumikha ng lisensya

POST /api/v2/licenses
Authorization: Bearer ACCESS_TOKEN
Content-Type: application/json
Idempotency-Key: 2bd25ec7-12da-45fc-9daa-67593b510932

{"media_id":123}

Gumamit ng natatanging key na 8 hanggang 160 printable ASCII characters para sa lohikal na pagtatangkang pagpili at panatilihin ito kapag nagre-retry. Ang bagong lisensya ay nagbabalik ng 201; ang idempotent na replay ay nagbabalik ng 200 na may parehong license ID.

Unang beripikahin ng Cathopic ang orihinal. Sa isang transaksyon, i-lock nito ang indibidwal o subscription ng team, tinitingnan ang access sa media at ang mga kasalukuyang shared entitlements, kumokonsumo ng hanggang isang download, at itinatala ang entitlement, history, at lisensya.

2. Humiling ng orihinal na URL

POST /api/v2/licenses/LICENSE_UUID/download-url
Authorization: Bearer ACCESS_TOKEN

Nag-e-expire ang URL pagkatapos ng limang minuto. Humiling ng bagong URL para sa muling pag-download; huwag gumawa ng isa pang lisensya. Iniuugnay ng Cathopic ang storage path at hindi kailanman tumatanggap ng arbitrary na path.

Mga mahahalagang error

• subscription_required: walang aktibong bayad na access.

• media_type_not_in_plan: ang uri ay hindi kasama.

• download_balance_exhausted: walang natitirang download para sa limited-plan.

• file_unavailable: nawawala ang orihinal; walang sisingil.

• idempotency_key_conflict: ang key ay ginamit para sa ibang media ID.

Itago ang X-Request-Id para sa suporta, ngunit huwag kailanman mag-log ng mga token, secret, o signed URLs. Mag-back off na may jitter pagkatapos ng 429 o pansamantalang tugon na 5xx.