Additioinal information about API endpoint versions, data and metadata.

ethereum · Mar 1, 2022 · 9acbbb3 · 9acbbb3
1 parent 4a88ce7
commit 9acbbb3
Showing 1 changed file with 18 additions and 4 deletions.
diff --git 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