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}
(...)

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.

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).