Using OpenVibe.Zone

A zone is an S3 bucket of one project environment. You make zones here or with the API, issue access keys, and point any S3 tool at https://s3.openvibe.media.

The S3 endpoint

• Endpoint: https://s3.openvibe.media, path style (/<zone>/<key>), region us-east-1, Signature Version 4.
• Operations:
  • objects: PutObject, GetObject (ranges), HeadObject, DeleteObject, DeleteObjects;
  • listing: ListObjectsV2 and ListObjects (prefix, delimiter, pages), ListBuckets, HeadBucket;
  • presigned GET and PUT URLs, valid for 7 days at most.
• Multipart uploads: CreateMultipartUpload, UploadPart, CompleteMultipartUpload, AbortMultipartUpload, ListParts and ListMultipartUploads, with S3's rules (every part but the last at least 5 MiB). An unfinished upload expires after a day.
• Server-side copies: CopyObject and UploadPartCopy, within a zone or from another zone of the same environment the key may read, so aws s3 cp s3://a/x s3://b/x and rclone's server-side moves never download the bytes.
• Not supported: ACLs and bucket policies (zones are private; access is the key's), versioning (a zone keeps the current object), and deleting a zone over S3 (do that here).
• Size: one request carries at most 256 MB, so larger files go up in parts (the AWS CLI, the SDKs and rclone do this by default); an object is at most 20 GB.
• Privacy: zones are private. Every request is signed. A presigned URL reaches only its own key, until it expires or its key is revoked.

Access keys

A key belongs to one project environment.

• It may read, write or both.
• It may be limited to some zones; with none named, it reaches every zone of the environment.
• Its secret is shown once, when it is issued. Revoking a key takes effect at once.
• A key limited to one zone is revoked when that zone is deleted.

The API

Base address: https://openvibe.zone/api/v1. Authenticate with a Network token: a developer app of the project (audience openvibe.zone, holding the route's capability; a sandbox app reaches only the sandbox), or a person who is a member of the project. Errors are RFC 9457 problem+json with a stable code.

• POST /projects/:project_id/zones (zone.zone.create): { env, name, description?, quota_bytes? } with an Idempotency-Key header. Answers 201 with the zone, or 409 with zone.name_taken or zone.name_retired.
• GET /projects/:project_id/zones?env=&include_deleted=&cursor=&limit= (zone.zone.list).
• GET /zones/:zone_id (zone.zone.read): the zone with its stored bytes and objects.
• PATCH /zones/:zone_id (zone.zone.manage): { description?, quota_bytes? }.
• DELETE /zones/:zone_id?recursive=true (zone.zone.delete). Without recursive, a zone that still holds objects answers zone.not_empty. A zone holding an object under a retention hold answers zone.held.
• GET /zones/:zone_id/usage (zone.usage.read): Media's live snapshot, and this month's metered series (requests, egress, byte-hours) as Media reports each closed hour.

The objects of a zone are OpenVibe.Media objects. Media's own API (/api/v2/:project_id/objects, with namespace set to the zone's id) reads and writes the same objects.