Number: 118
Author: hottuna
Created: 2016-01-23
Thread: http://zzz.i2p/topics/2030
Last updated: 2018-03-22
Status: Rejected

Overview

This proposal outlines API2 for I2PControl.

This proposal was rejected and will not be implemented, because it breaks backwards compatibility. See the discussion thread link for details.

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 Specification

{
  "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"
}

Parameters

"id"

The id number or the request.

Used to identify which reply was spawn by which request.

"method_name"

The name of the RPC that is being invoked.

"auth_token"

The session authentication token.

Needs to be supplied with every RPC except for the 'authenticate' call.

"method_parameter_value"

The method parameter.

Used to offer a different flavors of a method. Like 'get', 'set' and flavors like that.

"result_value"

The value that the RPC returns. Its type and contents depends on the method and which method.

Prefixes

The RPC naming scheme is 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 is to allow for some wiggle room and let implementations innovate without having to wait for every other implementation to catch up. If a RPC is implemented by all implementations its multiple prefixes can be removed and it can be included as a core RPC in the next API version.

Method reading guide

rpc.method

parameter [type of parameter]: [null], [number], [string], [boolean], [array] or [object]. [object] being a {key:value} map.

"return_value" [string] // This is the value returned by the RPC call

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.
}
```
control. - Control i2p
- control.reseed - Start reseeding
  - [nil]: No parameter needed
```
[nil]
```
- control.restart - Restart i2p instance
  - [nil]: No parameter needed
```
[nil]
```
- control.restart.graceful - Restart i2p instance gracefully
  - [nil]: No parameter needed
```
[nil]
```
- control.shutdown - Shut down i2p instance
  - [nil]: No parameter needed
```
[nil]
```
- control.shutdown.graceful - Shut down i2p instance gracefully
  - [nil]: No parameter needed
```
[nil]
```
- control.update.find - BLOCKING Search for signed updates
  - [nil]: No parameter needed
```
true [boolean] // True iff signed update is available
```
- control.update.start - Start update process
  - [nil]: No parameter needed
```
[nil]
```
i2pcontrol. - Configure i2pcontrol
- i2pcontrol.address - Get/Set the ip address that i2pcontrol listens to.
  - get [null]: This parameter does not need to be set.
```
"0.0.0.0" [string]
```
  - set [string]: This will be an ip address like "0.0.0.0" or "192.168.0.1"
```
[nil]
```
- i2pcontrol.password - Change the i2pcontrol password.
  - set [string]: Set the new password to this string
```
[nil]
```
- i2pcontrol.port - Get/Set the port that i2pcontrol listens to.
  - get [null]: This parameter does not need to be set.
```
7650 [number]
```
  - set [number]: Change the port that i2pcontrol listens to to this port
```
[nil]
```
settings. - Get/Set i2p instance settings
- settings.advanced - Advanced settings
  - get [string]: Get the value of this setting
```
"setting-value" [string]
```
  - getAll [null]:
```
[object]
{
  "setting-name" : "setting-value", [string]
  ".." : ".."
}
```
  - set [string]: Set the value of this setting
  - setAll [object] {"setting-name" : "setting-value", ".." : ".." }
```
[nil]
```
- settings.bandwidth.in - Inbound bandwidth settings
- settings.bandwidth.out - Outbound bandwidth settings
  - get [nil]: This parameter does not need to be set.
```
0 [number]
```
  - set [number]: Set the bandwidth limit
```
[nil]
```
- settings.ntcp.autoip - Get IP auto detection setting for NTCP
  - get [null]: This parameter does not need to be set.
```
true [boolean]
```
- settings.ntcp.hostname - Get NTCP hostname
  - get [null]: This parameter does not need to be set.
```
"0.0.0.0" [string]
```
  - set [string]: Set new hostname
```
[nil]
```
- settings.ntcp.port - NTCP port
  - get [null]: This parameter does not need to be set.
```
0 [number]
```
  - set [number]: Set new NTCP port.
```
[nil]
```
  - set [boolean]: Set NTCP IP auto detection
```
[nil]
```
- settings.ssu.autoip - Configure IP auto detection setting for SSU
  - get [nil]: This parameter does not need to be set.
```
true [boolean]
```
- settings.ssu.hostname - Configure SSU hostname
  - get [null]: This parameter does not need to be set.
```
"0.0.0.0" [string]
```
  - set [string]: Set new SSU hostname
```
[nil]
```
- settings.ssu.port - SSU port
  - get [null]: This parameter does not need to be set.
```
0 [number]
```
  - set [number]: Set new SSU port.
```
[nil]
```
  - set [boolean]: Set SSU IP auto detection
```
[nil]
```
- settings.share - Get bandwidth share percentage
  - get [null]: This parameter does not need to be set.
```
0 [number] // Bandwidth share percentage (0-100)
```
  - set [number]: Set bandwidth share percentage (0-100)
- settings.upnp - Enable or disable UPNP
  - get [nil]: This parameter does not need to be set.
```
true [boolean]
```
  - set [boolean]: Set SSU IP auto detection
```
[nil]
```
stats. - Get stats from the i2p 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.in.total - Returns the number of bytes received since last restart
- stats.bandwidth.out - Returns the outbound bandwidth (ideally for the last second)'
- stats.bandwidth.out.total - Returns the number of bytes sent since last restart'
- 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
  - get [null]: This parameter does not need to be set.
```
0.0 [number]
```

status. - Get i2p instance status

status.router - Get router status
- get [null]: This parameter does not need to be set.
```
"status" [string]
```

status.net - Get router network status

get [null]: This parameter does not need to be set.

0 [number]
/**
 *    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
 */

status.isfloodfill - Is the i2p instance currently a floodfill
- get [null]: This parameter does not need to be set.
```
true [boolean]
```
status.isreseeding - Is the i2p instance currently reseeding
- get [null]: This parameter does not need to be set.
```
true [boolean]
```
status.ip - Public IP detected of this i2p instance
- get [null]: This parameter does not need to be set.
```
"0.0.0.0" [string]
```

I2PControl API 2