From 57f992f37fbb7c358ab87af2dbd5c048669ed25f Mon Sep 17 00:00:00 2001 From: Nico Flaig Date: Mon, 8 Jul 2024 11:12:24 +0100 Subject: [PATCH 1/8] Clarify server behavior if content type is not supported --- beacon-node-oapi.yaml | 8 ++++++-- 1 file changed, 6 insertions(+), 2 deletions(-) diff --git a/beacon-node-oapi.yaml b/beacon-node-oapi.yaml index f90691d1..edfb5573 100644 --- a/beacon-node-oapi.yaml +++ b/beacon-node-oapi.yaml @@ -7,8 +7,12 @@ info: 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. + data is preferred in response to a request the header "Accept: application/octet-stream;q=1.0,application/json;q=0.9" should + be sent. 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 none of the content types specified in the "Accept" header + of the request are supported or alternatively, default to return data in JSON format. 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 From de4405c124b1aecf74ff10605e2768d10d26298d Mon Sep 17 00:00:00 2001 From: Nico Flaig Date: Mon, 8 Jul 2024 12:26:37 +0100 Subject: [PATCH 2/8] Tweak note about default behavior if no Accept header --- beacon-node-oapi.yaml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/beacon-node-oapi.yaml b/beacon-node-oapi.yaml index edfb5573..98e3811d 100644 --- a/beacon-node-oapi.yaml +++ b/beacon-node-oapi.yaml @@ -12,7 +12,7 @@ info: 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 none of the content types specified in the "Accept" header - of the request are supported or alternatively, default to return data in JSON format. + of the request are supported; if no "Accept" header is provided then it is assumed to be "application/json". 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 From 509b72110260aefd8abbb54ddf4819f53e881fbc Mon Sep 17 00:00:00 2001 From: Nico Flaig Date: Mon, 8 Jul 2024 14:11:53 +0100 Subject: [PATCH 3/8] Conistenly add 406 to error responses --- 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 | 2 ++ types/http.yaml | 27 +++++++++++++++++-- 15 files changed, 50 insertions(+), 36 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 98e3811d..83e5b049 100644 --- a/beacon-node-oapi.yaml +++ b/beacon-node-oapi.yaml @@ -413,6 +413,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: From ba6a6ef1cfcb8a587587527b80c4db8471a5b70a Mon Sep 17 00:00:00 2001 From: Nico Flaig Date: Mon, 8 Jul 2024 14:21:56 +0100 Subject: [PATCH 4/8] Wording --- beacon-node-oapi.yaml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/beacon-node-oapi.yaml b/beacon-node-oapi.yaml index 83e5b049..db6235eb 100644 --- a/beacon-node-oapi.yaml +++ b/beacon-node-oapi.yaml @@ -11,7 +11,7 @@ info: be sent. 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 none of the content types specified in the "Accept" header + that is not supported. Similarly, it should return a 406 status code if none of the formats specified in the "Accept" header of the request are supported; if no "Accept" header is provided then it is assumed to be "application/json". API endpoints are individually versioned. As such, there is no direct relationship between all v1 endpoints, all v2 endpoints, From d0cf81235ebd80131a68da5a407ffc1742b2281e Mon Sep 17 00:00:00 2001 From: Nico Flaig Date: Mon, 8 Jul 2024 14:47:46 +0100 Subject: [PATCH 5/8] Rephrase 406 server handling --- beacon-node-oapi.yaml | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/beacon-node-oapi.yaml b/beacon-node-oapi.yaml index db6235eb..a77f61f8 100644 --- a/beacon-node-oapi.yaml +++ b/beacon-node-oapi.yaml @@ -11,8 +11,8 @@ info: be sent. 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 none of the formats specified in the "Accept" header - of the request are supported; if no "Accept" header is provided then it is assumed to be "application/json". + 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". 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 From 9b67dd52c1a5b181f68fc5996b10d40d272ed5a5 Mon Sep 17 00:00:00 2001 From: Nico Flaig Date: Mon, 8 Jul 2024 16:53:12 +0100 Subject: [PATCH 6/8] Add note about server setting conten-type header --- beacon-node-oapi.yaml | 1 + 1 file changed, 1 insertion(+) diff --git a/beacon-node-oapi.yaml b/beacon-node-oapi.yaml index a77f61f8..6f738d4c 100644 --- a/beacon-node-oapi.yaml +++ b/beacon-node-oapi.yaml @@ -13,6 +13,7 @@ info: 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 From 43cedb7109e62d2cdb26151fd7a590d0af43ca94 Mon Sep 17 00:00:00 2001 From: Nico Flaig Date: Mon, 8 Jul 2024 17:06:19 +0100 Subject: [PATCH 7/8] Add note about content-type header in requests with ssz data --- beacon-node-oapi.yaml | 7 ++++--- 1 file changed, 4 insertions(+), 3 deletions(-) diff --git a/beacon-node-oapi.yaml b/beacon-node-oapi.yaml index 6f738d4c..35ef2ff5 100644 --- a/beacon-node-oapi.yaml +++ b/beacon-node-oapi.yaml @@ -6,9 +6,10 @@ 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 preferred in response to a request the header "Accept: application/octet-stream;q=1.0,application/json;q=0.9" 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 header "Accept: application/octet-stream;q=1.0,application/json;q=0.9" in the request. + 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 From 280b2278b0cde335067cbf540703e13ac5745d52 Mon Sep 17 00:00:00 2001 From: Nico Flaig Date: Mon, 8 Jul 2024 17:11:36 +0100 Subject: [PATCH 8/8] Tweak wording --- beacon-node-oapi.yaml | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/beacon-node-oapi.yaml b/beacon-node-oapi.yaml index 35ef2ff5..eb1d691a 100644 --- a/beacon-node-oapi.yaml +++ b/beacon-node-oapi.yaml @@ -8,8 +8,8 @@ info: 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 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 header "Accept: application/octet-stream;q=1.0,application/json;q=0.9" in the request. - Note that only a subset of requests can respond with data in SSZ format; these are noted in each individual request. + 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