From bb60e92b39c8e8aa54a66244a4598a08c808ce76 Mon Sep 17 00:00:00 2001 From: Nico Flaig Date: Wed, 11 Sep 2024 01:55:17 +0100 Subject: [PATCH] Clarify server behavior if content type is not supported (#457) Co-authored-by: Paul Harris --- apis/beacon/blob_sidecars/blob_sidecars.yaml | 2 ++ apis/beacon/blocks/blinded_block.yaml | 2 ++ apis/beacon/blocks/block.v2.yaml | 3 ++- apis/beacon/deposit_snapshot.yaml | 4 ++- apis/beacon/light_client/bootstrap.yaml | 9 +------ apis/beacon/light_client/finality_update.yaml | 9 +------ .../light_client/optimistic_update.yaml | 9 +------ apis/beacon/light_client/updates.yaml | 9 +------ apis/builder/states/expected_withdrawals.yaml | 2 ++ apis/debug/state.v2.yaml | 2 ++ apis/validator/blinded_block.yaml | 2 ++ apis/validator/block.v2.yaml | 2 ++ apis/validator/block.v3.yaml | 2 ++ beacon-node-oapi.yaml | 14 +++++++--- types/http.yaml | 27 +++++++++++++++++-- 15 files changed, 59 insertions(+), 39 deletions(-) diff --git a/apis/beacon/blob_sidecars/blob_sidecars.yaml b/apis/beacon/blob_sidecars/blob_sidecars.yaml index 40321774..92b4e853 100644 --- a/apis/beacon/blob_sidecars/blob_sidecars.yaml +++ b/apis/beacon/blob_sidecars/blob_sidecars.yaml @@ -68,5 +68,7 @@ get: example: code: 404 message: "Block not found" + "406": + $ref: "../../../beacon-node-oapi.yaml#/components/responses/NotAcceptable" "500": $ref: "../../../beacon-node-oapi.yaml#/components/responses/InternalError" diff --git a/apis/beacon/blocks/blinded_block.yaml b/apis/beacon/blocks/blinded_block.yaml index 35e89e7a..d85bce32 100644 --- a/apis/beacon/blocks/blinded_block.yaml +++ b/apis/beacon/blocks/blinded_block.yaml @@ -60,5 +60,7 @@ get: example: code: 404 message: "Block not found" + "406": + $ref: "../../../beacon-node-oapi.yaml#/components/responses/NotAcceptable" "500": $ref: "../../../beacon-node-oapi.yaml#/components/responses/InternalError" diff --git a/apis/beacon/blocks/block.v2.yaml b/apis/beacon/blocks/block.v2.yaml index f1ef818d..9f2322de 100644 --- a/apis/beacon/blocks/block.v2.yaml +++ b/apis/beacon/blocks/block.v2.yaml @@ -41,7 +41,6 @@ get: - $ref: "../../../beacon-node-oapi.yaml#/components/schemas/Deneb.SignedBeaconBlock" application/octet-stream: schema: - description: "SSZ serialized block bytes. Use Accept header to choose this response type" "400": description: "The block ID supplied could not be parsed" @@ -61,5 +60,7 @@ get: example: code: 404 message: "Block not found" + "406": + $ref: "../../../beacon-node-oapi.yaml#/components/responses/NotAcceptable" "500": $ref: "../../../beacon-node-oapi.yaml#/components/responses/InternalError" diff --git a/apis/beacon/deposit_snapshot.yaml b/apis/beacon/deposit_snapshot.yaml index 67f26cda..b1c55062 100644 --- a/apis/beacon/deposit_snapshot.yaml +++ b/apis/beacon/deposit_snapshot.yaml @@ -3,7 +3,7 @@ summary: "Get Deposit Tree Snapshot" description: | Retrieve [EIP-4881](https://eips.ethereum.org/EIPS/eip-4881) Deposit Tree Snapshot. - Depending on `Accept` header it can be returned either as json or as bytes serialzed by SSZ + Depending on `Accept` header it can be returned either as json or as bytes serialized by SSZ tags: - Beacon responses: @@ -30,5 +30,7 @@ example: code: 404 message: "No Finalized Snapshot Available" + "406": + $ref: "../../beacon-node-oapi.yaml#/components/responses/NotAcceptable" "500": $ref: '../../beacon-node-oapi.yaml#/components/responses/InternalError' diff --git a/apis/beacon/light_client/bootstrap.yaml b/apis/beacon/light_client/bootstrap.yaml index 89b7f1fd..b535f088 100644 --- a/apis/beacon/light_client/bootstrap.yaml +++ b/apis/beacon/light_client/bootstrap.yaml @@ -54,13 +54,6 @@ get: code: 404 message: "LC bootstrap unavailable" "406": - description: Unacceptable media type - content: - application/json: - schema: - $ref: "../../../beacon-node-oapi.yaml#/components/schemas/ErrorMessage" - example: - code: 406 - message: "Accepted media type not supported" + $ref: "../../../beacon-node-oapi.yaml#/components/responses/NotAcceptable" "500": $ref: "../../../beacon-node-oapi.yaml#/components/responses/InternalError" diff --git a/apis/beacon/light_client/finality_update.yaml b/apis/beacon/light_client/finality_update.yaml index c1a395d3..298480d7 100644 --- a/apis/beacon/light_client/finality_update.yaml +++ b/apis/beacon/light_client/finality_update.yaml @@ -40,13 +40,6 @@ get: code: 404 message: "LC finality update unavailable" "406": - description: Unacceptable media type - content: - application/json: - schema: - $ref: "../../../beacon-node-oapi.yaml#/components/schemas/ErrorMessage" - example: - code: 406 - message: "Accepted media type not supported" + $ref: "../../../beacon-node-oapi.yaml#/components/responses/NotAcceptable" "500": $ref: "../../../beacon-node-oapi.yaml#/components/responses/InternalError" diff --git a/apis/beacon/light_client/optimistic_update.yaml b/apis/beacon/light_client/optimistic_update.yaml index dea560e5..16cb2208 100644 --- a/apis/beacon/light_client/optimistic_update.yaml +++ b/apis/beacon/light_client/optimistic_update.yaml @@ -40,13 +40,6 @@ get: code: 404 message: "LC optimistic update unavailable" "406": - description: Unacceptable media type - content: - application/json: - schema: - $ref: "../../../beacon-node-oapi.yaml#/components/schemas/ErrorMessage" - example: - code: 406 - message: "Accepted media type not supported" + $ref: "../../../beacon-node-oapi.yaml#/components/responses/NotAcceptable" "500": $ref: "../../../beacon-node-oapi.yaml#/components/responses/InternalError" diff --git a/apis/beacon/light_client/updates.yaml b/apis/beacon/light_client/updates.yaml index 4823d071..ec40d0d7 100644 --- a/apis/beacon/light_client/updates.yaml +++ b/apis/beacon/light_client/updates.yaml @@ -85,13 +85,6 @@ get: code: 400 message: "Missing `count` value" "406": - description: Unacceptable media type - content: - application/json: - schema: - $ref: "../../../beacon-node-oapi.yaml#/components/schemas/ErrorMessage" - example: - code: 406 - message: "Accepted media type not supported" + $ref: "../../../beacon-node-oapi.yaml#/components/responses/NotAcceptable" "500": $ref: "../../../beacon-node-oapi.yaml#/components/responses/InternalError" diff --git a/apis/builder/states/expected_withdrawals.yaml b/apis/builder/states/expected_withdrawals.yaml index a89475c0..1c11b367 100644 --- a/apis/builder/states/expected_withdrawals.yaml +++ b/apis/builder/states/expected_withdrawals.yaml @@ -56,5 +56,7 @@ get: example: code: 404 message: "State not found" + "406": + $ref: "../../../beacon-node-oapi.yaml#/components/responses/NotAcceptable" "500": $ref: '../../../beacon-node-oapi.yaml#/components/responses/InternalError' \ No newline at end of file diff --git a/apis/debug/state.v2.yaml b/apis/debug/state.v2.yaml index d58ed771..d413af1c 100644 --- a/apis/debug/state.v2.yaml +++ b/apis/debug/state.v2.yaml @@ -60,6 +60,8 @@ get: example: code: 404 message: "State not found" + "406": + $ref: "../../beacon-node-oapi.yaml#/components/responses/NotAcceptable" "500": $ref: '../../beacon-node-oapi.yaml#/components/responses/InternalError' diff --git a/apis/validator/blinded_block.yaml b/apis/validator/blinded_block.yaml index d8a6e6a8..90ca5659 100644 --- a/apis/validator/blinded_block.yaml +++ b/apis/validator/blinded_block.yaml @@ -72,6 +72,8 @@ get: value: code: 400 message: "Invalid request to produce a block" + "406": + $ref: "../../beacon-node-oapi.yaml#/components/responses/NotAcceptable" "500": $ref: '../../beacon-node-oapi.yaml#/components/responses/InternalError' "503": diff --git a/apis/validator/block.v2.yaml b/apis/validator/block.v2.yaml index ff3fc8cb..00ad2fc8 100644 --- a/apis/validator/block.v2.yaml +++ b/apis/validator/block.v2.yaml @@ -69,6 +69,8 @@ get: value: code: 400 message: "Invalid request to produce a block" + "406": + $ref: "../../beacon-node-oapi.yaml#/components/responses/NotAcceptable" "500": $ref: '../../beacon-node-oapi.yaml#/components/responses/InternalError' "503": diff --git a/apis/validator/block.v3.yaml b/apis/validator/block.v3.yaml index b5f4d858..f2adf9fe 100644 --- a/apis/validator/block.v3.yaml +++ b/apis/validator/block.v3.yaml @@ -125,6 +125,8 @@ get: value: code: 400 message: "Invalid request to produce a block" + "406": + $ref: "../../beacon-node-oapi.yaml#/components/responses/NotAcceptable" "500": $ref: '../../beacon-node-oapi.yaml#/components/responses/InternalError' "503": diff --git a/beacon-node-oapi.yaml b/beacon-node-oapi.yaml index c3608a84..3068d98d 100644 --- a/beacon-node-oapi.yaml +++ b/beacon-node-oapi.yaml @@ -6,9 +6,15 @@ info: API specification for the beacon node, which enables users to query and participate in Ethereum 2.0 phase 0 beacon chain. All requests by default send and receive JSON, and as such should have either or both of the "Content-Type: application/json" - and "Accept: application/json" headers. In addition, some requests can return data in the SSZ format. To indicate that SSZ - data is required in response to a request the header "Accept: application/octet-stream" should be sent. Note that only a subset - of requests can respond with data in SSZ format; these are noted in each individual request. + and "Accept: application/json" headers. In addition, some requests can send and receive data in the SSZ format. The header + "Content-Type: application/octet-stream" should be set in requests that contain SSZ data; a preference to receive SSZ data in + response can be indicated by setting the "Accept: application/octet-stream;q=1.0,application/json;q=0.9" header. Note that + only a subset of requests can respond with data in SSZ format; these are noted in each individual request. + + When handling requests, the server should return a 415 status code if the "Content-Type" header in the request specifies a format + that is not supported. Similarly, it should return a 406 status code if it cannot produce a response in the format accepted by + the client as specified in the "Accept" header; if no "Accept" header is provided then it is assumed to be "application/json". + In any case, the server should indicate the format of the response by setting the corresponding "Content-Type" header. API endpoints are individually versioned. As such, there is no direct relationship between all v1 endpoints, all v2 endpoints, _etc._ and no such relationship should be inferred. All JSON responses return the requested data under a `data` key in the top @@ -413,6 +419,8 @@ components: $ref: './types/http.yaml#/InvalidRequest' NotFound: $ref: './types/http.yaml#/NotFound' + NotAcceptable: + $ref: './types/http.yaml#/NotAcceptable' UnsupportedMediaType: $ref: './types/http.yaml#/UnsupportedMediaType' InternalError: diff --git a/types/http.yaml b/types/http.yaml index 60ec9a33..a0bee7aa 100644 --- a/types/http.yaml +++ b/types/http.yaml @@ -110,8 +110,31 @@ NotFound: example: code: 404 message: "Requested item not found" +NotAcceptable: + description: "Accepted media type is not supported." + content: + application/json: + schema: + type: object + required: [code, message] + properties: + code: + description: "The media type in \"Accept\" header is unsupported, and the request has been rejected. This occurs when the server cannot produce a response in the format accepted by the client." + type: number + example: 406 + message: + description: "Message describing error" + type: string + stacktraces: + description: "Optional stacktraces, sent when node is in debug mode" + type: array + items: + type: string + example: + code: 406 + message: "Accepted media type not supported" UnsupportedMediaType: - description: "The supplied content-type is not supported." + description: "Supplied content-type is not supported." content: application/json: schema: @@ -119,7 +142,7 @@ UnsupportedMediaType: required: [code, message] properties: code: - description: "The media type supplied is unsupported, and the request has been rejected. This occurs when a HTTP request supplies a payload in a content-type that the service is not able to accept." + description: "The media type in \"Content-Type\" header is unsupported, and the request has been rejected. This occurs when a HTTP request supplies a payload in a content-type that the server is not able to handle." type: number example: 415 message: