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