gitlab.com/SiaPrime/SiaPrime@v1.4.1/doc/api/Gateway.md (about) 1 Gateway API 2 =========== 3 4 The Sia API documentation can be found here: 5 [Sia API](https://sia.tech/docs/ "Sia API") 6 7 <<<<<<< HEAD 8 Updates to the API documentation can be made here: 9 [Sia API markdown](./index.html.md "Sia API markdown") 10 ======= 11 There may be functional API calls which are not documented. These are not 12 guaranteed to be supported beyond the current release, and should not be used 13 in production. 14 15 Overview 16 -------- 17 18 The gateway maintains a peer to peer connection to the network and provides a 19 method for calling RPCs on connected peers. The gateway's API endpoints expose 20 methods for viewing the connected peers, manually connecting to peers, and 21 manually disconnecting from peers. The gateway may connect or disconnect from 22 peers on its own. 23 24 Index 25 ----- 26 27 | Route | HTTP verb | Examples | 28 | ---------------------------------------------------------------------------------- | --------- | ------------------------------------------------------- | 29 | [/gateway](#gateway-get-example) | GET | [Gateway info](#gateway-info) | 30 | [/gateway/connect/___:netaddress___](#gatewayconnectnetaddress-post-example) | POST | [Connecting to a peer](#connecting-to-a-peer) | 31 | [/gateway/disconnect/___:netaddress___](#gatewaydisconnectnetaddress-post-example) | POST | [Disconnecting from a peer](#disconnecting-from-a-peer) | 32 33 #### /gateway [GET] [(example)](#gateway-info) 34 35 returns information about the gateway, including the list of connected peers. 36 37 ###### JSON Response 38 ```javascript 39 { 40 // netaddress is the network address of the gateway as seen by the rest of 41 // the network. The address consists of the external IP address and the 42 // port SiaPrime is listening on. It represents a `modules.NetAddress`. 43 "netaddress": String, 44 45 // peers is an array of peers the gateway is connected to. It represents 46 // an array of `modules.Peer`s. 47 "peers": []{ 48 // netaddress is the address of the peer. It represents a 49 // `modules.NetAddress`. 50 "netaddress": String, 51 52 // version is the version number of the peer. 53 "version": String, 54 55 // inbound is true when the peer initiated the connection. This field 56 // is exposed as outbound peers are generally trusted more than inbound 57 // peers, as inbound peers are easily manipulated by an adversary. 58 "inbound": Boolean, 59 60 // local is true if the peer's IP address belongs to a local address 61 // range such as 192.168.x.x or 127.x.x.x 62 "local": Boolean 63 } 64 } 65 ``` 66 67 #### /gateway/connect/{netaddress} [POST] [(example)](#connecting-to-a-peer) 68 69 connects the gateway to a peer. The peer is added to the node list if it is not 70 already present. The node list is the list of all nodes the gateway knows 71 about, but is not necessarily connected to. 72 73 ###### Path Parameters 74 ``` 75 // netaddress is the address of the peer to connect to. It should be a 76 // reachable ip address and port number, of the form 'IP:port'. IPV6 addresses 77 // must be enclosed in square brackets. 78 // 79 // Example IPV4 address: 123.456.789.0:123 80 // Example IPV6 address: [123::456]:789 81 :netaddress 82 ``` 83 84 ###### Response 85 standard success or error response. See 86 [API.md#standard-responses](/doc/API.md#standard-responses). 87 88 #### /gateway/disconnect/{netaddress} [POST] [(example)](#disconnecting-from-a-peer) 89 90 disconnects the gateway from a peer. The peer remains in the node list. 91 Disconnecting from a peer does not prevent the gateway from automatically 92 connecting to the peer in the future. 93 94 ###### Path Parameters 95 ``` 96 // netaddress is the address of the peer to connect to. It should be a 97 // reachable ip address and port number, of the form 'IP:port'. IPV6 addresses 98 // must be enclosed in square brackets. 99 // 100 // Example IPV4 address: 123.456.789.0:123 101 // Example IPV6 address: [123::456]:789 102 :netaddress 103 ``` 104 105 ###### Response 106 standard success or error response. See 107 [API.md#standard-responses](/doc/API.md#standard-responses). 108 109 Examples 110 -------- 111 112 #### Gateway info 113 114 ###### Request 115 ``` 116 /gateway 117 ``` 118 119 ###### Expected Response Code 120 ``` 121 200 OK 122 ``` 123 124 ###### Example JSON Response 125 ```json 126 { 127 "netaddress":"333.333.333.333:4281", 128 "peers":[ 129 { 130 "netaddress":"222.222.222.222:4281", 131 "version":"1.0.0", 132 "inbound":false 133 }, 134 { 135 "netaddress":"111.111.111.111:4281", 136 "version":"0.6.0", 137 "inbound":true 138 } 139 ] 140 } 141 ``` 142 143 #### Connecting to a peer 144 145 ###### Request 146 ``` 147 /gateway/connect/123.456.789.0:123 148 ``` 149 150 ###### Expected Response Code 151 ``` 152 204 No Content 153 ``` 154 155 #### Disconnecting from a peer 156 157 ###### Request 158 ``` 159 /gateway/disconnect/123.456.789.0:123 160 ``` 161 162 ###### Expected Response Code 163 ``` 164 204 No Content 165 ``` 166 >>>>>>> siaprime/master