REST API

OpenDHT offers an optional HTTP REST API allowing to use an OpenDHT node as a proxy to the distributed network.

Following resources are exposed through HTTP REST:

/

Represents the DHT node itself.

GET

Will retreive basic node information with the following JSON structure:

{
  "id":"public key id",
  "ipv4":{
    "good":12,
    "dubious":6,
    ...
  },
  "ipv6":{
    "good":12,
    "dubious":6,
    ...
  },
  "node_id":"node_id"
}

/{infohash}

Represents the key {infohash} in the distributed map.

GET

Will perform a get operation on the given key on the distributed map and return a list of JSON serialized values. Because we want the ability to have a callback when a Value is get, we send values one by one.

For example, if someone put 2 Values for hash 2346ad27d7568ba9896f1b7da6b5991251debdf2, curl http://ipProxy:portProxy/2346ad27d7568ba9896f1b7da6b5991251debdf2 will give something like:

{"data":"base64 of the data 1","id":"id 1","owner":"certificate","seq":0,"sig":"base64 of sig","type":3}
{"data":"base64 of the data 2","id":"id 2","owner":"certificate","seq":0,"sig":"base64 of sig","type":3}

Note: if the value is encrypted, data will be replaced by cypher.

POST

Will perform a put operation on the given key on the distributed map.

For example, if you want to put a Value for hash 2346ad27d7568ba9896f1b7da6b5991251debdf2, curl -X POST -d "@DATA" http://ipProxy:portProxy/2346ad27d7568ba9896f1b7da6b5991251debdf2 with @DATA a JSON serialized Value.

LISTEN

Will perform a listen operation on the given key on the distributed map. Because we want the ability to have a callback when a Value is get, we send values one by one.

For example, if someone put Values for hash 2346ad27d7568ba9896f1b7da6b5991251debdf2, curl -X LISTEN http://ipProxy:portProxy/2346ad27d7568ba9896f1b7da6b5991251debdf2 will give something like:

{"data":"base64 of the data 1","id":"id 1","owner":"certificate","seq":0,"sig":"base64 of sig","type":3}
{"data":"base64 of the data 2","id":"id 2","owner":"certificate","seq":0,"sig":"base64 of sig","type":3}
(...)

NOTE: The connection has no timeout. It will perform a LISTEN on the DHT until the connection is closed

IDENTITY

The proxy can have the ability to sign or encrypt values. If this ability is activated, it will result in two endpoints:

SIGN

Will perform a putSigned operation on the given JSON serialized value.

ENCRYPT

Will perform a putSigned operation on the given JSON serialized value.

example:

1. Run a server with its own identity: ./tools/dhtnode --proxyserver 8000 -i
2. Run a destination node with its own identity:

./tools/dhtnode -D -i
OpenDHT node 0fc83d530726b15b08094b79f835a9a9ec4b6633 running on IPv4 port 39838, IPv6 port 59777
Public key ID 01b6579b7746827f380c17700ce231436214ca71

3. Write a file DATA:

{
  "to":"01b6579b7746827f380c17700ce231436214ca71",
  "data":"ZW5jb2RlCg=="
}

4. Use it to do your query

curl -X ENCRYPT -d "@DATA" http://localhost:8000/opendht
{"data":"ZW5jb2RlCg==","id":"0","type":0}

5. The destination node can now get the data:

>> g opendht
Using h(opendht) = 5a1e0310bd25f4775637cd51b5a378b404b116fc
>> Get: found 1 value(s) after 58.288695 ms
	Value[id:8762cf334c38d1eb signed (v0) decrypted Data (type: 0 ): 656e636f64650a]
Get: completed, took 2.433854 s

Note: If you run another node with another identity, you will not be able to see encrypted data (just signed one)

./tools/dhtnode -D -i                                     
OpenDHT node 21e3701a94a79d5f3de3c1b2458dfc68aff8f54c running on IPv4 port 46274, IPv6 port 38043
Public key ID b0cd21eb000f9e49bf7e34b202ddd3a68401eb1b
 (type 'h' or 'help' for a list of possible commands)

>> g opendht
Using h(opendht) = 5a1e0310bd25f4775637cd51b5a378b404b116fc
>> Get: completed, took 2.355259 s

PUSH NOTIFICATIONS

SUBSCRIBE

Will perform a listen during six hours without the need to maintain the connection. Send push notifications through the gateway. See the page on push notifications to get the description of this endpoint.

UNSUBSCRIBE

Will cancel a listen previously done.

/{infohash}/{value_id}

Represents a specific value on the distributed map.

GET

Will perform a get operation on the given key and value id on the distributed map and return the result or 404. The returned content is like the /{infohash}.

Errors

when an error occurs, the request to the API should give a JSON like:

{"err": "the detail"}

with a code 503 if the proxy is not connected to a DHT, 400 if the data given is malformed, 502 if an error occurs (when putting a value for example).

New API

In order to avoid custom HTTP methods in future, we decided to design a new API with a standard REST design.

We kept the past routes active if you compile with http_parser fork. Here are the new routes, we added:

GET /node/info
GET /node/stats
GET /key/{infohash}
POST /key/{infohash}
GET /key/{infohash}/options
GET /key/{infohash}/listen
SUBSCRIBE /key/{infohash}
UNSUBSCRIBE /key/{infohash}
POST /key/{infohash}/sign
POST /key/{infohash}/encrypt