Merge pull request #195 from mcdee/metadata

Additioinal information about API endpoint versions, data and metadata.

beacon-node-oapi.yaml

@@ -6,10 +6,21 @@ 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.  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's data or metadata without an increase in the version number.
+
   version: "Dev - Eth2Spec v1.1.0"
   contact:
     name: Ethereum Github