BUD-05

Media optimization endpoints

draft optional

Defines the PUT /media, GET /media/<task> and DELETE /media/<task> endpoints for processing and optimizing media

Task Object

The task object defines a long running media processing task on the server. A task MUST have the following fields

id A unique id for the task (required)
status The status of the job, either running, complete, or canceled (required)
message A human-readable description of what is happening or the current status (optional)
progress A number from 0 to 100 representing the percentage of the task that is complete (optional)
blob A full Blob Descriptor (required when complete)

PUT /media

The PUT /media endpoint MUST accept binary data in the body of the request and MAY use the Content-Type and Content-Length headers to get the MIME type and size of the media

The server should preform any optimizations or conversions it deems necessary in order to make the media more suitable for distribution

The endpoint MUST return a status code of 202 with Content-Type: application/json and a task object or an error response

Servers MAY reject a media upload for any reason and should respond with the appropriate HTTP 4xx status code and an error message explaining the reason for the rejection

Upload Authorization

Servers may require an upload authorization event to identify the uploader

If a server requires an upload authorization event it MUST preform all the checks that the /upload endpoint does, including that the x tag value matches the sha256 hash of the uploaded blob

GET /media/task

Servers may expose a GET /media/<task id> endpoint to allow clients to get the results or check on the progress of a task

The endpoint MUST return a 2xx status code and a task object if a task with <task id> exists or an error response

The blob field MUST be set to a Blob Descriptor when the task status is complete

Servers may delete (or forget) tasks after a self determined amount of time after the task status is complete

DELETE /media/task

Servers may expose a DELETE /media/<task id> endpoint to allow clients to cancel a processing request

Examples

Upload image PUT /media

{
	"id": "0e81bf11-eb84-49b8-a7f0-4c7c60254f2e",
	"status": "running",
	"progress": 0,
	"message": "Resizing Image"
}

Example GET /media/eb6e7ec1-b752-4740-91bb-9aaddf92bc57:

{
	"id": "eb6e7ec1-b752-4740-91bb-9aaddf92bc57",
	"status": "running",
	"progress": 24,
	"message": "Resizing Video"
}