OrbitDB HTTP API Server

An HTTP API Server for the OrbitDB distributed peer-to-peer database.

Table of Contents

• Install
• Setup
• API
  • GET /dbs
  • GET /db/:dbname
  • GET /db/:dbname/value
  • GET /db/:dbname/:item
  • GET /db/:dbname/iterator
  • GET /db/:dbname/index
  • GET /identity
  • POST /db/:dbname
  • POST /db/:dbname/query
    • Modulus Query
    • Range Query
  • POST|PUT /db/:dbname/add
  • POST|PUT /db/:dbname/put
  • POST|PUT /db/:dbname/inc
  • POST|PUT /db/:dbname/inc/:val
  • POST|PUT /db/:dbname/access/write
  • DELETE /db/:dbname
  • DELETE /db/:dbname/:item
• Contribute
• License

Install

To install the OrbitDB HTTP Client:

git clone https://github.com/orbitdb/orbit-db-http-api.git
cd orbit-db-http-api
npm install

Setup

The OrbitDB HTTP Client can be run in two modes; local or api.

In local mode, OrbitDB HTTP Client will launch its own IPFS node to replicate the OrbitDB peer:

node src/cli.js local --orbitdb-dir /path/to/orbitdb --https-cert ./my.crt --https-key my.key

where --orbitdb-dir is the path to your OrbitDB peer.

In api mode, OrbitDB HTTP Client will connect to an existing IPFS node to replicate the OrbitDB peer:

node src/cli.js api --ipfs-host localhost --orbitdb-dir /path/to/orbitdb --https-cert ./my.crt --https-key my.key

where --ipfs-host is an external IPFS node and --orbitdb-dir is the path to your OrbitDB peer.

In both modes, you will also need to specify an SSL certifcate and private key:

--https-cert will be the path to your certificate. --https-key will be the path to your associated private key.

You can generate an SSL certificate using an SSL certificate authority such as Let's Encrypt. Alternatively, you can create your own self-signed certificate although this is highly discouraged for production environments.

When using a self-signed SSL certificate you will either need to add your certificate to your CA list or pass the -k option to curl, telling curl to ignore the the insecure connection.

API

GET /dbs

Lists all databases on the current peer.

curl https://localhost:3000/dbs

{"docstore":{"address":{"root":"zdpuAmnfJZ6UTssG5Ns3o8ALXZJXVx5eTLTxf7gfFzHxurbJq","path":"docstore"},"dbname":"docstore","id":"/orbitdb/zdpuAmnfJZ6UTssG5Ns3o8ALXZJXVx5eTLTxf7gfFzHxurbJq/docstore","options":{"create":"true","indexBy":"_id","localOnly":false,"maxHistory":-1,"overwrite":true,"replicate":true},"type":"docstore"},"feed":{"address":{"root":"zdpuAo6DwafMiyuzhfEojXJThFPdv4Eu9hLfaWrKD6GSVzyjj","path":"feed"},"dbname":"feed","id":"/orbitdb/zdpuAo6DwafMiyuzhfEojXJThFPdv4Eu9hLfaWrKD6GSVzyjj/feed","options":{"create":"true","localOnly":false,"maxHistory":-1,"overwrite":true,"replicate":true},"type":"feed"}}

GET /db/:dbname

Gets the details of a database with name :dbname.

Returns information about the database as a JSON object.

curl https://localhost:3000/db/docstore

{"address":{"root":"zdpuAmnfJZ6UTssG5Ns3o8ALXZJXVx5eTLTxf7gfFzHxurbJq","path":"docstore"},"dbname":"docstore","id":"/orbitdb/zdpuAmnfJZ6UTssG5Ns3o8ALXZJXVx5eTLTxf7gfFzHxurbJq/docstore","options":{"create":"true","indexBy":"_id","localOnly":false,"maxHistory":-1,"overwrite":true,"replicate":true},"type":"docstore"}

GET /db/:dbname/value

Gets the current value from counter database :dbname.

Returns the current counter value.

Can only be used on counter.

curl -X GET https://localhost:3000/db/counter/value

1

GET /db/:dbname/:item

Gets a record identified by :item from the database :dbname.

Returns a list of found items as a JSON array.

For the data type docstore, :item must be a value identified by the index field (set using indexBy).

curl -X GET https://localhost:3000/db/docstore/1

[{"_id":1, "value": "test"}]

GET /db/:dbname/iterator

Gets items from an eventlog or feed database :dbname.

Returns a list of matching objects as a JSON array.

Can only be used on eventlog|feed.

curl -X GET https://localhost:3000/db/feed/iterator

[{"IPFS":"https://ipfs.io"}]

Additional options can be passed to OrbitDB to return different entries.

curl -X GET https://localhost:3000/db/feed/iterator -d 'limit=-1'

[{"OrbitDB":"https://github.com/orbitdb/orbit-db"},{"IPFS":"https://ipfs.io"}]

See OrbitDB's Iterator API for more information.

GET /db/:dbname/index

Gets information about the data stored in :dbname.

Returns information about the data stored as a JSON object.

For the data store keyvalue all records are returned:

curl -X GET https://localhost:3000/keyvalue/index

{"Key":{"name1":"Value1"},"Key2":{"name":"Value2"}}

Docstore and feed return all records as well as iterators, signature hashes and other information about the stored data:

{"1":{"cid":"zdpuB1sqnXKwgAtJT7vqtrRUsyr4XUZyhume9uJgrrwZmyegu","id":"/orbitdb/zdpuAzpw8yuuMEuffMFcgXafsAye9GqBPwTjmiJijHz3akFhx/docstore","payload":{"op":"PUT","key":1,"value":{"_id":1,"name":"1"}},"next":[],"v":1,"clock":...}}

The eventlog returns the hash of the last stored item:

{"id":"/orbitdb/zdpuB1r3rfya65UUjQu6GsBXEmp5gmjvMwRGwkxd4ySwYnBSK/eventlog","heads":["zdpuAu7eTsdWoQ76CdWCbjcsGV3s6duYyUujaHQiGCAZPLWMb"]}

The counter data store returns information about the current counter value:

{"id":"04e6de9dd0e8d0069bcc6d8f3ef11cefe63bba6129c32f2cd422a0394814bc6723b26eb62731ee466020b0394d01dd08e4a5123eaad45e4d0840fd796652a22e42","counters":{"04e6de9dd0e8d0069bcc6d8f3ef11cefe63bba6129c32f2cd422a0394814bc6723b26eb62731ee466020b0394d01dd08e4a5123eaad45e4d0840fd796652a22e42":15}}

GET /identity

Gets the identity information.

Returns identity as a JSON object.

curl -X GET https://localhost:3000/identity

{"id":"03fc293ea95bdb5dea71d5d21cbbae2a57f2d2002c9966f0d5c7b0bda232d5934d","publicKey":"048161d9685991dc87f3e049aa04b1da461fdc5f8a280ed6234fa41c0f9bc98a1ce91f07494584a45b97160ac818e100a6b27777e0b1b09e6ba4795dcc797a6d8b","signatures":{"id":"3045022100e40ab2dcc83dde17c939d5515ce322e7f81bf47536ab342582db8c35f28d2a720220228e418cc3d2f3e0004d5f4292c0d2cf7975c93073e0cc831f0cb849e4ac920a","publicKey":"3045022100ad18ba66006e19e2952eabc9ffb532dd69d60593f90448a05d6f4903c2931e3502204009975030b839522c668cd693d357bf1f3d0423d604a6bc10645425a0a3dd1b"},"type":"orbitdb"}

POST /db/:dbname

Creates a new database and returns information about the newly created database or opens an existing database with the same name.

Returns information about the database as a JSON object.

The OrbitDB options create=true and type=eventlog|feed|docstore|keyvalue|counter must be sent with the POST otherwise an error is thrown.

curl https://localhost:3000/db/docstore -d "create=true" -d "type=docstore"

{"address":{"root":"zdpuAmnfJZ6UTssG5Ns3o8ALXZJXVx5eTLTxf7gfFzHxurbJq","path":"docstore"},"dbname":"docstore","id":"/orbitdb/zdpuAmnfJZ6UTssG5Ns3o8ALXZJXVx5eTLTxf7gfFzHxurbJq/docstore","options":{"create":"true","indexBy":"_id","localOnly":false,"maxHistory":-1,"overwrite":true,"replicate":true},"type":"docstore"}

Additional OrbitDB-specific flags can also be passed. For example, if the index field must be changed then the indexBy flag can be specified as an additional POST param (this would apply to type docstore only):

curl https://localhost:3000/db/docstore -d "create=true" -d "type=docstore" -d "indexBy=name"

Parameters can also be passed as JSON. This is useful if additional parameters such as accessController need to be specified:

curl -H "Content-Type: application/json" --data '{"create":"true","type":"feed","accessController":{"type": "orbitdb","write": ["1234"]}}'

To open an existing database, specify the address of the database. If the database does not exist locally it will be fetched from the swarm.

The address MUST be URL escaped.

curl -X POST https://localhost:3000/db/zdpuAmnfJZ6UTssG5Ns3o8ALXZJXVx5eTLTxf7gfFzHxurbJq%2Fdocstore

By default, OrbitDB will open the database if one already exists with the same name. To always overwrite the existing database with a new one, pass the overwrite flag:

curl https://localhost:3000/db/docstore -d "create=true" -d "type=docstore" -d "overwrite=true"

POST /db/:dbname/query

Queries the database :dbname.

Returns a list of found items as a JSON array.

curl https://localhost:3000/db/docstore/query -X GET -H "Content-Type: application/json" --data '{"values":[]}'

[{"project":"OrbitDB","site":"https://github.com/orbitdb/orbit-db","likes":200},{"project":"IPFS","site":"https://ipfs.io","likes":400}]

To query a subset of data, a condition can be specified. For example, to retrieve only those entries which have a total number of likes above 300:

curl https://localhost:3000/db/docstore/query -H "Content-Type: application/json" --data '{"propname":"likes","comp":"gt","values":[300]}'

[{"project":"IPFS","site":"https://ipfs.io","likes":400}]

Available operator short-codes are:

eq propname equals value. Equivalent to "=="

ne propname is not equals to value. Equivalent to "!="

gt propname is greater than value. Equivalent to ">"

lt propname is less than value. Equivalent to "<"

gte propname is greater than or equal to value. Equivalent to ">="

lte propname is less than or equal to value. Equivalent to "<="

mod Perform a modulus calculation on propname using value. Equivalent to "%"

range Perform a range query, comparing propname to min and max.

all Fetch all records for field propname. Equivalent to "*"

Modulus Query

When using a modulus query, you must supply the divisor and the remainder. For example, to obtain all likes which are multiples of 100, you would specify a divisor 100 and a remainder 0:

curl -X POST https://localhost:3000/db/docstore/query -H "Content-Type:application/json" --data '{"propname":"likes", "comp":"mod", "values":[100,0]}'

[{"site":"https://ipfs.io","likes":400,"project":"IPFS"},{"site":"https://github.com/orbitdb/orbit-db","likes":200,"project":"OrbitDB"}]

Range Query

When specifying a range query, you must supply the min and max values. For example, to obtain all likes greater than 250 but less than 1000 the min and max must be supplied:

curl -X GET https://localhost:3000/db/docstore/query -H "Content-Type:application/json" --data '{"propname":"likes", "comp":"range", "values":[250,1000]}'

[{"site":"https://ipfs.io","likes":400,"project":"IPFS"},{"site":"https://github.com/orbitdb/orbit-db","likes":200,"project":"OrbitDB"}]

POST|PUT /db/:dbname/add

Adds a new entry to the eventlog or feed database :dbname.

Returns the multihash of the new record entry.

Can only be used on eventlog|feed

curl -X POST https://localhost:3000/db/feed/add -d 'feed-item-1'

zdpuArB1ZQUQGGpZgJrhy6xyxwxMCE898kDrQW2x6KbnRNbAn

POST|PUT /db/:dbname/put

Puts a record to the database :dbname.

Returns a multihash of the record entry.

curl -X POST https://localhost:3000/db/docstore/put -H "Content-Type: application/json" -d '{"_id":1, "value": "test"}'

zdpuAkkFaimxyRE2bsiLRSiybkku3oDi4vFHqPZh29BABZtZU

For the keyvalue store, a JSON object containing the variables key and value must be passed in the POST data:

curl -X POST https://localhost:3000/db/keyvalue/put  -H "Content-Type: application/json" -d '{"key":"Key","value":{ "name": "Value" }}'

POST|PUT /db/:dbname/inc

Increments the counter database :dbname by 1.

Returns a multihash of the new counter value.

curl -X POST https://localhost:3000/db/counter/inc

zdpuAmHw9Tcc4pyVjcVX3rJNJ7SGffmu4EwjodzmaPBVGGzbd

POST|PUT /db/:dbname/inc/:val

Increments the counter database :dbname by :val.

Returns a multihash of the new counter value.

curl -X POST https://localhost:3000/db/counter/inc/100

zdpuAmHw9Tcc4pyVjcVX3rJNJ7SGffmu4EwjodzmaPBVGGzbd

POST|PUT /db/:dbname/access/write

Adds the id to the list of peers who have write access to the :dbname data store.

curl -X POST https://localhost:3000/db/docstore/access/write -d 'id=045757bffcc7a4...'

zdpuAmHw9Tcc4pyVjcVX3rJNJ7SGffmu4EwjodzmaPBVGGzbd

DELETE /db/:dbname

Deletes the local database :dbname. This does not delete any data from peers.

curl -X DELETE https://localhost:3000/db/docstore

DELETE /db/:dbname/:item

Deletes the item specified by :item from the database :dbname.

Returns the multihash of the item entry deleted or an error if no item is found.

curl -X DELETE https://localhost:3000/db/docstore/1

zdpuB39Yv1LV6CMYuNUgRi125utDpUoiP7PDsumjn1T4ASkzN

Contribute

We would be happy to accept PRs! If you want to work on something, it'd be good to talk beforehand to make sure nobody else is working on it. You can reach us on Gitter, or in the issues section.

We also have regular community calls, which we announce in the issues in the @orbitdb welcome repository. Join us!

If you want to code but don't know where to start, check out the issues labelled "help wanted".

For specific guidelines for contributing to this repository, check out the Contributing guide. For more on contributing to OrbitDB in general, take a look at the @OrbitDB welcome repository. Please note that all interactions in @OrbitDB fall under our Code of Conduct.

License

MIT © 2019 phillmac