From c746be27e350ec0078d00d63955994c7e500f124 Mon Sep 17 00:00:00 2001 From: fiatjaf Date: Tue, 29 Oct 2024 13:11:34 -0300 Subject: [PATCH 1/2] X-Reason, a header for all user-facing error messages to go. --- buds/01.md | 4 ++++ buds/06.md | 17 ++++++++--------- 2 files changed, 12 insertions(+), 9 deletions(-) diff --git a/buds/01.md b/buds/01.md index 146717f..f3bed29 100644 --- a/buds/01.md +++ b/buds/01.md @@ -10,6 +10,10 @@ _All pubkeys MUST be in hex format_ Servers MUST set the `Access-Control-Allow-Origin: *`, `Access-Control-Allow-Headers: Authorization,*` and `Access-Control-Allow-Methods: GET, PUT, DELETE` headers on all endpoints to ensure compatibility with apps hosted on other domains +## Error responses + +Every time a server sends an error response (HTTP status codes >=400), it may include a human-readable header `X-Reason` that can be displayed to the user. + ## Authorization events Authorization events are used to identify the users to the server diff --git a/buds/06.md b/buds/06.md index c587032..739404b 100644 --- a/buds/06.md +++ b/buds/06.md @@ -8,14 +8,13 @@ Defines how clients can verify if the upload can be completed before sending the ## HEAD /upload - Upload requirements -The `HEAD /upload` endpoint `MUST` use the `X-SHA-256`, `X-Content-Type` and `X-Content-Length` headers sent by client to get the SHA-256 hash, MIME type and size of the blob that will be uploaded, returning a HTTP status code and a custom header `X-Upload-Message` to indicate some human readable message about the upload requirements. +The `HEAD /upload` endpoint `MUST` use the `X-SHA-256`, `X-Content-Type` and `X-Content-Length` headers sent by client to get the SHA-256 hash, MIME type and size of the blob that will be uploaded, returning a HTTP status code and a custom header `X-Reason` to indicate some human readable message about the upload requirements. ### Headers - `X-SHA-256`: A string that represents the blob's SHA-256 hash. - `X-Content-Length`: An integer that represents the blob size in bytes. - `X-Content-Type`: A string that specifies the blob's MIME type, like `application/pdf` or `image/png`. -- `X-Upload-Message`: A human readable message that explains the reason why the upload cannot proceed. ### Upload Authorization @@ -39,36 +38,36 @@ Example response from the server if the upload can be done: HTTP/1.1 200 OK ``` -If the upload cannot proceed, the server `MUST` return an appropriate `4xx` HTTP status code and a custom header `X-Upload-Message` with a human readable error message. +If the upload cannot proceed, the server `MUST` return an appropriate `4xx` HTTP status code and a custom header `X-Reason` with a human readable error message. Some examples of error messages: ```http HTTP/1.1 400 Bad Request -X-Upload-Message: Invalid X-SHA-256 header format. Expected a string. +X-Reason: Invalid X-SHA-256 header format. Expected a string. ``` ```http HTTP/1.1 401 Unauthorized -X-Upload-Message: Authorization required for uploading video files. +X-Reason: Authorization required for uploading video files. ``` ```http HTTP/1.1 403 Forbidden -X-Upload-Message: SHA-256 hash banned. +X-Reason: SHA-256 hash banned. ``` ```http HTTP/1.1 411 Length Required -X-Upload-Message: Missing X-Content-Length header. +X-Reason: Missing X-Content-Length header. ``` ```http HTTP/1.1 413 Content Too Large -X-Upload-Message: File too large. Max allowed size is 100MB. +X-Reason: File too large. Max allowed size is 100MB. ``` ```http HTTP/1.1 415 Unsupported Media Type -X-Upload-Message: Unsupported file type. +X-Reason: Unsupported file type. ``` From b7e4e96ed597351fc17855620b4c50249ac74d97 Mon Sep 17 00:00:00 2001 From: fiatjaf Date: Mon, 11 Nov 2024 13:03:56 -0300 Subject: [PATCH 2/2] remove old Error Responses section. --- buds/01.md | 20 -------------------- 1 file changed, 20 deletions(-) diff --git a/buds/01.md b/buds/01.md index f3bed29..d78415d 100644 --- a/buds/01.md +++ b/buds/01.md @@ -67,26 +67,6 @@ Authorization: Nostr eyJpZCI6IjhlY2JkY2RkNTMyOTIwMDEwNTUyNGExNDI4NzkxMzg4MWIzOWQ All endpoints MUST be served from the root path (eg. `https://cdn.example.com/upload`, etc). This allows clients to talk to servers interchangeably when uploading or retrieving blobs -## Error Responses - -For HTTP `4xx` and `5xx` status codes servers MUST repond with `Content-Type: application/json` and a JSON object containing `message` - -The `message` field MUST be human readable and should explain the reason for the error. Optionally servers may include other fields for the client with more information about the error - -Example Error response: - -``` -HTTP/2 401 -content-type: application/json; charset=utf-8 -content-length: 32 -access-control-allow-origin: * -access-control-expose-headers: * -access-control-allow-headers: authorization,* -access-control-allow-methods: get, put, delete - -{"message":"Missing Auth event"} -``` - ## GET /sha256 - Get Blob The `GET /` endpoint MUST return the contents of the blob with the `Content-Type` header set to the appropriate MIME type