From bd6bef6562d3cb5db8c18cb65a739599397ece74 Mon Sep 17 00:00:00 2001 From: Jim McDonald Date: Tue, 1 Mar 2022 16:06:37 +0000 Subject: [PATCH 1/4] Additioinal information about API endpoint versions, data and metadata. --- beacon-node-oapi.yaml | 22 ++++++++++++++++++---- 1 file changed, 18 insertions(+), 4 deletions(-) diff --git a/beacon-node-oapi.yaml b/beacon-node-oapi.yaml index 95aae8b3..3162f8dd 100644 --- a/beacon-node-oapi.yaml +++ b/beacon-node-oapi.yaml @@ -6,10 +6,24 @@ 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 request 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 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. + + 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. The rules that require an increase in version number are as follows: + + - no field that is listed in an endpoint shall be removed without an increase in the version number + - no field that is listed in an endpoint shall be altered terms of format (_e.g._ from a string to an array) without an + increase in the version number + + Note that it is possible for a field to be added to an endpoint without an increase in the version number. + + All JSON responses return the requested data under a "data" key in the top level of their response. Additional metadata may or + may not be present in other keys at the top level of the response. Metadata's presence or absence can be dependent on the type + and version of the beacon node, the state of the chain, and other conditions. Metadata is not versioned, and as such the same + version of an API endpoint may return different metadata at different times. + version: "Dev - Eth2Spec v1.1.0" contact: name: Ethereum Github From 56d7e799e5b63e73370de1ab85be3a646b5d3940 Mon Sep 17 00:00:00 2001 From: Jim McDonald Date: Mon, 7 Mar 2022 12:41:43 +0000 Subject: [PATCH 2/4] Update beacon-node-oapi.yaml MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Co-authored-by: Radosław Kapka --- 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 3162f8dd..12ddc3e5 100644 --- a/beacon-node-oapi.yaml +++ b/beacon-node-oapi.yaml @@ -14,7 +14,7 @@ info: _etc._ and no such relationship should be inferred. The rules that require an increase in version number are as follows: - no field that is listed in an endpoint shall be removed without an increase in the version number - - no field that is listed in an endpoint shall be altered terms of format (_e.g._ from a string to an array) without an + - no field that is listed in an endpoint shall be altered in terms of format (_e.g._ from a string to an array) without an increase in the version number Note that it is possible for a field to be added to an endpoint without an increase in the version number. From c7bc83e9788db21d6e7197d629fbcfdd6329fc56 Mon Sep 17 00:00:00 2001 From: Jim McDonald Date: Mon, 7 Mar 2022 12:42:01 +0000 Subject: [PATCH 3/4] Update beacon-node-oapi.yaml MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Co-authored-by: Radosław Kapka --- 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 12ddc3e5..c1ab3597 100644 --- a/beacon-node-oapi.yaml +++ b/beacon-node-oapi.yaml @@ -19,7 +19,7 @@ info: Note that it is possible for a field to be added to an endpoint without an increase in the version number. - All JSON responses return the requested data under a "data" key in the top level of their response. Additional metadata may or + All JSON responses return the requested data under a `data` key in the top level of their response. Additional metadata may or may not be present in other keys at the top level of the response. Metadata's presence or absence can be dependent on the type and version of the beacon node, the state of the chain, and other conditions. Metadata is not versioned, and as such the same version of an API endpoint may return different metadata at different times. From c7b18acf6b28d8ee95eb1bb9d06e9ba27226bba8 Mon Sep 17 00:00:00 2001 From: Jim McDonald Date: Mon, 14 Mar 2022 19:19:23 +0000 Subject: [PATCH 4/4] Update rules. --- beacon-node-oapi.yaml | 11 ++++------- 1 file changed, 4 insertions(+), 7 deletions(-) diff --git a/beacon-node-oapi.yaml b/beacon-node-oapi.yaml index c1ab3597..2e45021a 100644 --- a/beacon-node-oapi.yaml +++ b/beacon-node-oapi.yaml @@ -11,18 +11,15 @@ info: of requests can respond with data in SSZ format; these are noted in each individual request. 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. The rules that require an increase in version number are as follows: + _etc._ and no such relationship should be inferred. All JSON responses return the requested data under a `data` key in the top + level of their response. Additional metadata may or may not be present in other keys at the top level of the response, dependent + on the endpoint. The rules that require an increase in version number are as follows: - no field that is listed in an endpoint shall be removed without an increase in the version number - no field that is listed in an endpoint shall be altered in terms of format (_e.g._ from a string to an array) without an increase in the version number - Note that it is possible for a field to be added to an endpoint without an increase in the version number. - - All JSON responses return the requested data under a `data` key in the top level of their response. Additional metadata may or - may not be present in other keys at the top level of the response. Metadata's presence or absence can be dependent on the type - and version of the beacon node, the state of the chain, and other conditions. Metadata is not versioned, and as such the same - version of an API endpoint may return different metadata at different times. + Note that it is possible for a field to be added to an endpoint's data or metadata without an increase in the version number. version: "Dev - Eth2Spec v1.1.0" contact: