diff --git a/buds/02.md b/buds/02.md index 22a4566..0a21ef9 100644 --- a/buds/02.md +++ b/buds/02.md @@ -38,18 +38,18 @@ Example: The `PUT /upload` 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 data -The endpoint MUST NOT modify the blob in any way and should return the exact same sha256 that was uploaded. This is critical to allow users to re-upload their blobs to new servers +The endpoint MUST NOT modify the blob in any way and SHOULD return the exact same sha256 that was uploaded. This is critical to allow users to re-upload their blobs to new servers The endpoint MUST return a [Blob Descriptor](#blob-descriptor) if the upload was successful or an error object if it was not -Servers MAY reject an upload for any reason and should respond with the appropriate HTTP `4xx` status code and an error message explaining the reason for the rejection +Servers MAY reject an 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 (Optional) -Servers MAY accept an authorization event when uploading blobs and should perform additional checks +Servers MAY accept an authorization event when uploading blobs and SHOULD perform additional checks 1. The `t` tag MUST be set to `upload` -2. MUST contain at least one `x` tag matching the sha256 hash of the body of the request +2. The authorization event MUST contain at least one `x` tag matching the sha256 hash of the body of the request Example Authorization event: @@ -71,21 +71,21 @@ Example Authorization event: ## GET /list/pubkey - List Blobs (Optional) -The `/list/` endpoint MUST return a JSON array of [Blob Descriptor](#blob-descriptor) that where uploaded by the specified pubkey +The `/list/` endpoint MUST return a JSON array of [Blob Descriptor](#blob-descriptor) that were uploaded by the specified pubkey -The endpoint MUST support `cursor` and`limit` query parameters for cursor based pagination. The `cursor` parameter MUST be the `sha256` hash of the last blob in the previous page. The returned array of blob descriptors MUST be sorted by the `uploaded` date in descending order and should not include the blob at the cursor +The endpoint MUST support `cursor` and `limit` query parameters for cursor based pagination. The `cursor` parameter MUST be the `sha256` hash of the last blob in the previous page, or omitted to request the first page. The `limit` parameter specifies the maximum number of results to return. The returned array of blob descriptors MUST be sorted by the `uploaded` date in descending order and MUST NOT include the blob at the cursor -The endpoint MUST support `since` and `until` query parameters to filter the list of blobs by their `uploaded` date, although it is not recommended for clients to use these parameters for pagination. +The endpoint MAY support `since` and `until` query parameters to filter the list of blobs by their `uploaded` date. These parameters are deprecated for pagination purposes as they do not preserve server resources -Servers may reject a list request for any reason and MUST respond with the appropriate HTTP `4xx` status code and an error message explaining the reason for the rejection +Servers MAY reject a list request for any reason and MUST respond with the appropriate HTTP `4xx` status code and an error message explaining the reason for the rejection ### List Authorization (optional) -The server may optionally require Authorization when listing blobs uploaded by the pubkey +The server MAY optionally require Authorization when listing blobs uploaded by the pubkey -In this case the server must perform additional checks on the authorization event +In this case the server MUST perform additional checks on the authorization event -1. The `t` tag must be set to `list` +1. The `t` tag MUST be set to `list` Example Authorization event: @@ -108,16 +108,16 @@ Example Authorization event: Servers MUST accept `DELETE` requests to the `/` endpoint -Servers may reject a delete request for any reason and should respond with the appropriate HTTP `4xx` status code and an error message explaining the reason for the rejection +Servers MAY reject a delete request for any reason and SHOULD respond with the appropriate HTTP `4xx` status code and an error message explaining the reason for the rejection ### Delete Authorization (required) Servers MUST accept an authorization event when deleting blobs -Servers should perform additional checks on the authorization event +Servers SHOULD perform additional checks on the authorization event -1. The `t` tag must be set to `delete` -2. MUST contain at least one `x` tag matching the sha256 hash of the blob being deleted +1. The `t` tag MUST be set to `delete` +2. The authorization event MUST contain at least one `x` tag matching the sha256 hash of the blob being deleted When multiple `x` tags are present on the authorization event the server MUST only delete the blob listed in the URL.