Version 3 (modified by 5 years ago) (diff) | ,
---|
This page will outline the API2 for i2pcontrol
Developer headsup!
- All RPC paramters will now be lower case. This *will* break backwards compatibility with API1 implementations. The reasons for this is to provide users of ≥API2 with simplest most coherent possible API.
API 2
{ "id": **id**, "method": **method_name**, "params": { "token": "**auth_token**" "method_param": **method_parameter_value**, }, "jsonrpc": "2.0" } { "id": **id**, "result": **result_value**, "jsonrpc": "2.0" }
- id - The id number or the request, it's used to identify which reply was spawn by which request
- method_name - The method name is the name of the RPC that is being invoked
- auth_token - This is the session authentication token, it needs to be supplied with every RPC except for the 'authenticate' call
- method_parameter_value - This is the method parameter. It is used to offer a different flavors of a method. Like 'get', 'set' and flavors like that.
- result_value - This is the value that RPC returns. Its type and contents depends on the method and which method
Prefixes
The naming for will be done similar to how it's done in CSS, with vendor prefixes for the different API implementations (i2p, kovri, i2pd).
XXX.YYY.ZZZ i2p.XXX.YYY.ZZZ i2pd.XXX.YYY.ZZZ kovri.XXX.YYY.ZZZ
The overall idea with vendor specific prefixes to allow for some wiggle room and let vendors innovate without having to wait for every other implementation to catch up. If is implemented by all implementations it can be moved under the umbrella of the next API version
Method reading guide
- rpc.method
- parameter [type of parameter]: [null], [nubmer], [string], [boolean], [array] or [object]. [object] being a {key:value} map.
[string] "return_value" // This is the value returned by the RPC call
- parameter [type of parameter]: [null], [nubmer], [string], [boolean], [array] or [object]. [object] being a {key:value} map.
Methods
- authenticate - Given that a correct password is provided, this method provides you with a token for further access and a list of supported API levels.
- password [string]: The password for this i2pcontrol implementation
[object] { "token" : [string], // The token to be used be supplied with all other RPC methods "api" : [[int],[int], ...] // A list of supported API levels. }
- password [string]: The password for this i2pcontrol implementation
- stats. - This group of methods provide access to all stats kept within the instance.
- stats.advanced - This method provides access to all stats kept within the instance.
- get [string]: Name of the advanced stat to be provided
- Optional: period [number]: The period for the requested stat
- stats.knownpeers - Returns the number of known peers
- stats.uptime - Returns the time in ms since the router started
- stats.bandwidth.in - Returns the inbound bandwidth (ideally for the last second)
- stats.bandwidth.out - Returns the outbound bandwidth (ideally for the last second)'
- stats.tunnels.participating - Returns the number of tunnels participated in currently
- stats.netdb.peers.active - Returns the number of peers we've recently communicated with
- stats.netdb.peers.fast - Returns the number of 'fast' peers
- stats.netdb.peers.highcapacity - Returns the number of 'high capacity' peers
- stats.netdb.peers.known - Returns the number of known peers
- ' [nil]: No parameter is needed
[number] 0.0
- ' [nil]: No parameter is needed
- stats.advanced - This method provides access to all stats kept within the instance.
- stats.???? - Given that a correct password is provided, this method provides you with a token for further access and a list of supported API levels.
- get [null]: This parameter does not need to be set.
[number] 0.0
- get [null]: This parameter does not need to be set.
- i2pcontrol.address - Get/Set? the ip address that i2pcontrol listens to.
- get [nil]: This parameter does not need to be set.
[string] "0.0.0.0"
- set [string]: This will be an ip address like "0.0.0.0" or "192.168.0.1"
[nil]
- get [nil]: This parameter does not need to be set.
- i2pcontrol.password - Change the i2pcontrol password.
- set [string]: Set the new password to this string
[nil]
- set [string]: Set the new password to this string
- i2pcontrol.port - Get/Set? the port that i2pcontrol listens to.
- get [nil]: This parameter does not need to be set.
[number] 7650
- set [number]: Change the port that i2pcontrol listens to to this port
[nil]
- get [nil]: This parameter does not need to be set.
*i2p.router.status - Returns the number of known peers *i2p.router.net.status – [long] What the current network status is. According to the below enum:
0 – OK 1 – TESTING 2 – FIREWALLED 3 – HIDDEN 4 – WARN_FIREWALLED_AND_FAST 5 – WARN_FIREWALLED_AND_FLOODFILL 6 – WARN_FIREWALLED_WITH_INBOUND_TCP 7 – WARN_FIREWALLED_WITH_UDP_DISABLED 8 – ERROR_I2CP 9 – ERROR_CLOCK_SKEW 10 – ERROR_PRIVATE_TCP_ADDRESS 11 – ERROR_SYMMETRIC_NAT 12 – ERROR_UDP_PORT_IN_USE 13 – ERROR_NO_ACTIVE_PEERS_CHECK_CONNECTION_AND_FIREWALL 14 – ERROR_UDP_DISABLED_AND_TCP_UNSET
*i2p.router.netdb.isreseeding – [boolean] Is the router reseeding hosts to its NetDB?