aboutsummaryrefslogtreecommitdiffstats
path: root/api.md
diff options
context:
space:
mode:
authorKarissa McKelvey <krmckelv@gmail.com>2016-03-30 13:02:33 -0700
committerKarissa McKelvey <krmckelv@gmail.com>2016-03-30 13:03:02 -0700
commit3c619e437e5af11c00da771bc76c0b187094caf2 (patch)
tree024736ab4ff5ce635092c9fd1c6974105cc42e70 /api.md
parent4e76e5fc4b347cb6acf7fadde465270ac3357379 (diff)
downloaddat-docs-3c619e437e5af11c00da771bc76c0b187094caf2.tar.gz
dat-docs-3c619e437e5af11c00da771bc76c0b187094caf2.zip
add beginning info on api design
Diffstat (limited to 'api.md')
-rw-r--r--api.md114
1 files changed, 114 insertions, 0 deletions
diff --git a/api.md b/api.md
new file mode 100644
index 0000000..b41544d
--- /dev/null
+++ b/api.md
@@ -0,0 +1,114 @@
+## 1.0 Architecture Design
+
+![dat-arch.001.jpg](dat-arch.001.jpg)
+
+
+ * dat: command-line
+ * dat-desk: desktop application
+ * dat-server: http and ui frontend
+ * dat-js: JS api
+ * hyperdrive: storage layer
+ * discovery-swarm: swarm
+
+
+## dat-js
+
+A common JavaScript API for Dat.
+
+```
+var Dat = require('dat-js')
+```
+
+#### `var dat = Dat(opts, cb)`
+
+Options
+
+ * `db`: leveldb instance for underlying hyperdrive
+ * `DISCOVERY_SERVER`: the discovery server to use. (default 'discovery1.publicbits.org')
+ * `DAT_DOMAIN`: the domain to use (default 'dat.local')
+
+#### `dat.link(dir, cb)`
+
+Create a dat link for the given directory. Does not start sharing the dat. Must use `dat.join` to begin serving the link to the swarm.
+
+```js
+var linker = dat.link(dir)
+var done = function (err, link) {
+ if (err) throw err
+ console.log('Done linking!', link)
+}
+var dir = '/Users/karissa/data/mydata'
+var linker = dat.link(dir, done)
+linker.on('progress', function (progress) {
+ console.log('progress item', progress)
+})
+```
+
+#### `dat.download(link, dir, cb)`
+
+Download the given link to a given location. Get progress events from the stream. Progress events are the same as emitted by the `dat` object.
+
+```js
+var done = function (err) {
+ if (err) throw err
+ console.log('Done downloading!')
+}
+var link = 'dat://8a82dae10ee8384'
+var dir = '/Users/karissa/data/mydata'
+var downloader = dat.download(link, dir, done)
+downloader.on('progress', function (progress) {
+ console.log('progress item', progress)
+})
+```
+
+#### `dat.join(link, cb)`
+
+Join a swarm for the given link. Should be called after `link` or `download`. Throws error if data has not been downloaded or linked.
+
+#### `dat.leave(link, cb)`
+
+Leave the swarm for the given link.
+
+#### `dat.on('progress', cb)`
+
+Get all progress events from uploading and downloading data.
+
+```js
+dat.on('progress', function (progress) {
+ console.log(progress)
+})
+```
+
+## dat
+
+Command-line interface for dat
+
+#### `dat link DIR`
+
+Create a new link for the contents of a directory and begin automatically serving the data to a swarm in the background.
+
+ * `--foreground`: run the server in the foreground instead.
+
+#### `dat download LINK DIR`
+
+Download a link to a directory and begin automatically serving the data to a swarm in the background.
+
+ * `--foreground`: run the server in the foreground instead.
+
+#### `dat join LINK`
+
+Starts serving the given link in a background progress. Must have already performed `link` or `download`.
+
+ * `--foreground`: run the server in the foreground instead.
+
+#### `dat leave LINK`
+
+Stops serving the given link to the discovery swarm. Must have already performed `link` or `download`.
+
+#### `dat ls`
+
+View a static list of the current dat links that are served.
+
+#### `dat mon`
+
+Opens up real-time monitoring panel for viewing progress of running dats. Can provide optional parameter `dat mon LINK` to filter the monitor and logs for a given dat link.