diff --git a/buds/05.md b/buds/05.md new file mode 100644 index 0000000..97d92b7 --- /dev/null +++ b/buds/05.md @@ -0,0 +1,87 @@ +BUD-05 +====== + +Media optimization endpoints + +`draft` `optional` + +Defines the `PUT /media`, `GET /media/` and `DELETE /media/` 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](./02.md#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](#task-object) or an [error response](./01.md#error-responses) + +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](./02.md#upload-authorization-required) to identify the uploader + +If a server requires an `upload` authorization event it MUST preform all the [checks](./02.md#upload-authorization-required) 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/` 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](#task-object) if a task with `` exists or an [error response](./01.md#error-responses) + +The `blob` field MUST be set to a [Blob Descriptor](./02.md#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/` endpoint to allow clients to cancel a processing request + +## Examples + +Upload image `PUT /media` +```json +{ + "id": "0e81bf11-eb84-49b8-a7f0-4c7c60254f2e", + "status": "running", + "progress": 0, + "message": "Resizing Image" +} +``` + +Example `GET /media/eb6e7ec1-b752-4740-91bb-9aaddf92bc57`: +```json +{ + "id": "eb6e7ec1-b752-4740-91bb-9aaddf92bc57", + "status": "running", + "progress": 24, + "message": "Resizing Video" +} +``` + +Example `GET /media/eb6e7ec1-b752-4740-91bb-9aaddf92bc57`: +```json +{ + "id": "eb6e7ec1-b752-4740-91bb-9aaddf92bc57", + "status": "complete", + "progress": 100, + "message": "Finished optimizing video", + "blob": { + "url": "https://cdn.example.com/b1674191a88ec5cdd733e4240a81803105dc412d6c6708d53ab94fc248f4f553.webm", + "sha256": "b1674191a88ec5cdd733e4240a81803105dc412d6c6708d53ab94fc248f4f553", + "size": 18431531, + "type": "video/webm", + "uploaded": 1722386093 + } +} +```