REST API

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

Following ressources 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":"ipv4_informations",
  "ipv6":"ipv6_informations",
  "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}
HTTP/1.1 200 OK
Content-Type: application/json

{"data":"base64 of the data 2","id":"id 2","owner":"certificate","seq":0,"sig":"base64 of sig","type":3}
HTTP/1.1 200 OK
Content-Type: application/json

{"ok": 1}

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}
HTTP/1.1 200 OK
Content-Type: application/json

{"data":"base64 of the data 2","id":"id 2","owner":"certificate","seq":0,"sig":"base64 of sig","type":3}
HTTP/1.1 200 OK
Content-Type: application/json

(...)

Optional endpoints

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.

/{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 404 code or 400 (if the data given is malformed).