1  # Ethereum Beacon APIs
 2  
 3  ![CI](https://github.com/ethereum/beacon-APIs/workflows/CI/badge.svg)
 4  
 5  Collection of RESTful APIs provided by Ethereum Beacon nodes
 6  
 7  API browser: [https://ethereum.github.io/beacon-APIs/](https://ethereum.github.io/beacon-APIs/)
 8  
 9  ## Outline
10  
11  This document outlines an application programming interface (API) which is exposed by a beacon node implementation
12   which aims to facilitate [Phase 0](https://github.com/ethereum/eth2.0-specs#phase-0) of the Etheruem consensus layer.
13  
14  The API is a REST interface, accessed via HTTP. The API should not, unless protected by additional security layers, be exposed to the public Internet as the API includes multiple endpoints which could open your node to denial-of-service (DoS) attacks through endpoints triggering heavy processing.
15   Currently, the only supported return data type is JSON.
16  
17  The beacon node (BN) maintains the state of the beacon chain by communicating with other beacon nodes in the Ethereum network.
18  Conceptually, it does not maintain keypairs that participate with the beacon chain.
19  
20  The validator client (VC) is a conceptually separate entity which utilizes private keys 
21  to perform validator related tasks, called "duties", on the beacon chain.
22   These duties include the production of beacon blocks and signing of attestations.
23  
24  The goal of this specification is to promote interoperability between various beacon node implementations.
25  
26  ## Render 
27  To render spec in browser you will need any http server to load `index.html` file
28  in root of the repo.
29  
30  ##### Python
31  ```
32  python -m SimpleHTTPServer 8080
33  ```
34  And api spec will render on [http://localhost:8080](http://localhost:8080).
35  
36  ##### NodeJs
37  ```
38  npm install simplehttpserver -g
39  
40  # OR
41  
42  yarn global add simplehttpserver
43  
44  simplehttpserver
45  ```
46  And api spec will render on [http://localhost:8000](http://localhost:8000).
47  
48  ## Contributing
49  Api spec is checked for lint errors before merge. 
50  
51  To run lint locally, install linter with
52  ```
53  npm install -g @stoplight/spectral
54  
55  # OR
56  
57  yarn global add @stoplight/spectral
58  ```
59  and run lint with
60  ```
61  spectral lint beacon-node-oapi.yaml 
62  ```
63  
64  ## Implementations
65  
66  - [TypeScript Wrapper](https://www.npmjs.com/package/@chainsafe/eth2.0-api-wrapper)
67  
68  https://www.npmjs.com/package/@chainsafe/eth2.0-api-wrapper
69  ## Releasing
70  
71  1. Create and push tag
72  
73     - Make sure info.version in beacon-node-oapi.yaml file is updated before tagging.
74     - CD will create github release and upload bundled spec file
75     
76  2. Add release entrypoint in index.html
77  
78  In SwaggerUIBundle configuration (inside index.html file), add another entry in "urls" field (SwaggerUI will load first item as default).
79  Entry should be in following format(replace `<tag>` with real tag name from step 1.):
80  ```javascript
81           {url: "https://github.com/ethereum/beacon-APIs/releases/download/<tag>/beacon-node-oapi.yaml", name: "<tag>"},
82  ```