From 20962c172962cdbe0344ec333d5faff6fc537687 Mon Sep 17 00:00:00 2001 From: David Dias Date: Tue, 28 Jun 2016 09:54:04 +0100 Subject: [PATCH] break the APIs into separate files --- API/files/README.md | 118 ++++++++++++ API/object/README.md | 260 +++++++++++++++++++++++++++ README.md | 417 +++---------------------------------------- 3 files changed, 399 insertions(+), 396 deletions(-) create mode 100644 API/files/README.md create mode 100644 API/object/README.md diff --git a/API/files/README.md b/API/files/README.md new file mode 100644 index 00000000..3b47e3fd --- /dev/null +++ b/API/files/README.md @@ -0,0 +1,118 @@ +files API +========= + +#### `add` + +> Add files and data to IPFS. + +##### `Go` **WIP** + +##### `JavaScript` - ipfs.files.add(data, [callback]) + +Where `data` may be + +- an array of objects, each of the form +```js +{ + path: '/tmp/myfile.txt', + content: (Buffer or Readable stream) +} +``` +- a `Buffer` instance +- a `Readable` stream + +If no `content` is passed, then the path is treated as an empty directory + +`callback` must follow `function (err, res) {}` signature, where `err` is an error if the operation was not successful. `res` will be an array of: + +```js +{ + path: '/tmp/myfile.txt', + node: DAGNode +} +``` + +If no `callback` is passed, a promise is returned. + +Example: + +```js +var files = [ + { + path: '/tmp/myfile.txt', + content: (Buffer or Readable stream) + } +] +ipfs.files.add(files, function (err, files) { + // 'files' will be an array of objects +}) +``` + + +#### `createAddStream` + +> Add files and data to IPFS using a transform stream. + +##### `Go` **WIP** + +##### `JavaScript` - ipfs.files.createAddStream([callback]) + +Provides a Transform stream, where objects can be written of the forms + +```js +{ + path: '/tmp/myfile.txt', + content: (Buffer or Readable stream) +} +``` + +`callback` must follow `function (err, stream) {}` signature, where `err` is an +error if the operation was not successful. `stream` will be a Transform stream, +to which tuples like the above two object formats can be written and [DAGNode][] +objects will be outputted. + +If no `callback` is passed, a promise is returned. + +```js +ipfs.files.createAddStream(function (err, stream) { + stream.on('data', function (file) { + // 'file' will be of the form + // { + // path: '/tmp/myfile.txt', + // node: DAGNode + // } + }) + + stream.write({path: , content: }) + // write as many as you want + + stream.end() +}) +``` + + + + +#### `cat` + +> Streams the file at the given IPFS multihash.. + +##### `Go` **WIP** + +##### `JavaScript` - ipfs.cat(multihash, [callback]) + +`multihash` is a [multihash][] which can be passed as + +- Buffer, the raw Buffer of the multihash +- String, the base58 encoded version of the multihash + +`callback` must follow `function (err, stream) {}` signature, where `err` is an error if the operation was not successful and `stream` is a readable stream of the file. + +If no `callback` is passed, a promise is returned. + +```js +ipfs.files.cat(multihash, function (err, file) { + // file will be a stream containing the data of the file requested +}) +``` + diff --git a/API/object/README.md b/API/object/README.md new file mode 100644 index 00000000..e0315695 --- /dev/null +++ b/API/object/README.md @@ -0,0 +1,260 @@ +object API +========== + +#### `object.new` + +> Create a new MerkleDAG node, using a specific layout. Caveat: So far, only UnixFS object layouts are supported. + +##### `Go` **WIP** + +##### `JavaScript` - ipfs.object.new([callback]) + +`callback` must follow `function (err, node) {}` signature, where `err` is an error if the operation was not successful and `node` is a MerkleDAG node of the type [DAGNode][] + +If no `callback` is passed, a [promise][] is returned. + + + + + +#### `object.put` + +> Store an MerkleDAG node. + +##### `Go` **WIP** + +##### `JavaScript` - ipfs.object.put(obj, [options, callback]) + +`obj` is the MerkleDAG Node to be stored. Can of type: + +- Object, with format `{ Data: , Links: [] }` +- Buffer, requiring that the encoding is specified on the options. If no encoding is specified, Buffer is treated as the Data field +- [DAGNode][] + +`options` is a optional argument of type object, that can contain the following properties: + +- `enc`, the encoding of the Buffer (json, yml, etc), if passed a Buffer. + +`callback` must follow `function (err, node) {}` signature, where `err` is an error if the operation was not successful and `node` is a MerkleDAG node of the type [DAGNode][] + +If no `callback` is passed, a [promise][] is returned. + + + + + +#### `object.get` + +> Fetch a MerkleDAG node + +##### `Go` **WIP** + +##### `JavaScript` - ipfs.object.get(multihash, [options, callback]) + +`multihash` is a [multihash][] which can be passed as: + +- Buffer, the raw Buffer of the multihash (or of and encoded version) +- String, the toString version of the multihash (or of an encoded version) + +`options` is a optional argument of type object, that can contain the following properties: + +- `enc`, the encoding of multihash (base58, base64, etc), if any. + +`callback` must follow `function (err, node) {}` signature, where `err` is an error if the operation was not successful and `node` is a MerkleDAG node of the type [DAGNode][] + +If no `callback` is passed, a [promise][] is returned. + +#### `object.data` + +> Returns the Data field of an object + +##### `Go` **WIP** + +##### `JavaScript` - ipfs.object.data(multihash, [options, callback]) +`multihash` is a [multihash][] which can be passed as: + +- Buffer, the raw Buffer of the multihash (or of and encoded version) +- String, the toString version of the multihash (or of an encoded version) + +`options` is a optional argument of type object, that can contain the following properties: + +- `enc`, the encoding of multihash (base58, base64, etc), if any. + +`callback` must follow `function (err, data) {}` signature, where `err` is an error if the operation was not successful and `data` is a Buffer with the data that the MerkleDAG node contained. + +If no `callback` is passed, a [promise][] is returned. + +#### `object.links` + +> Returns the Links field of an object + +##### `Go` **WIP** + +##### `JavaScript` - ipfs.object.links(multihash, [options, callback]) + +`multihash` is a [multihash][] which can be passed as: + +- Buffer, the raw Buffer of the multihash (or of and encoded version) +- String, the toString version of the multihash (or of an encoded version) + +`options` is a optional argument of type object, that can contain the following properties: + +- `enc`, the encoding of multihash (base58, base64, etc), if any. + +`callback` must follow `function (err, links) {}` signature, where `err` is an error if the operation was not successful and `links` is an Array of [DAGLink](https://github.com/vijayee/js-ipfs-merkle-dag/blob/master/src/dag-node.js#L199-L203) objects. + +If no `callback` is passed, a [promise][] is returned. + + + + + +#### `object.stat` + +> Returns stats about an Object + +##### `Go` **WIP** + +##### `JavaScript` - ipfs.object.stat(multihash, [options, callback]) + +`multihash` is a [multihash][] which can be passed as: + +- Buffer, the raw Buffer of the multihash (or of and encoded version) +- String, the toString version of the multihash (or of an encoded version) + +`options` is a optional argument of type object, that can contain the following properties: + +- `enc`, the encoding of multihash (base58, base64, etc), if any. + +`callback` must follow `function (err, stats) {}` signature, where `err` is an error if the operation was not successful and `stats` is an Object with following format: + +```JavaScript +{ + Hash: 'QmPTkMuuL6PD8L2SwTwbcs1NPg14U8mRzerB1ZrrBrkSDD', + NumLinks: 0, + BlockSize: 10, + LinksSize: 2, + DataSize: 8, + CumulativeSize: 10 +} +``` + +If no `callback` is passed, a [promise][] is returned. + + + + + +#### `object.patch` + +> `object.patch` exposes the available patch calls. + +##### `object.patch.addLink` + +> Add a Link to an existing MerkleDAG Object + +###### `Go` **WIP** + +###### `JavaScript` - ipfs.object.patch.addLink(multihash, DAGLink, [options, callback]) + +`multihash` is a [multihash][] which can be passed as: + +- Buffer, the raw Buffer of the multihash (or of and encoded version) +- String, the toString version of the multihash (or of an encoded version) + +`DAGLink` is the new link to be added on the node that is identified by the `multihash` + +`options` is a optional argument of type object, that can contain the following properties: + +- `enc`, the encoding of multihash (base58, base64, etc), if any. + +`callback` must follow `function (err, node) {}` signature, where `err` is an error if the operation was not successful and `node` is a MerkleDAG node of the type [DAGNode][] that resulted by the operation of adding a Link. + +If no `callback` is passed, a [promise][] is returned. + + + + + +##### `object.patch.rmLink` + +> Remove a Link from an existing MerkleDAG Object + +###### `Go` **WIP** + +###### `JavaScript` - ipfs.object.patch.rmLink(multihash, DAGLink, [options, callback]) + +`multihash` is a [multihash][] which can be passed as: + +- Buffer, the raw Buffer of the multihash (or of and encoded version) +- String, the toString version of the multihash (or of an encoded version) + +`DAGLink` is the link to be removed on the node that is identified by the `multihash` + +`options` is a optional argument of type object, that can contain the following properties: + +- `enc`, the encoding of multihash (base58, base64, etc), if any. + +`callback` must follow `function (err, node) {}` signature, where `err` is an error if the operation was not successful and `node` is a MerkleDAG node of the type [DAGNode][] that resulted by the operation of adding a Link. + +If no `callback` is passed, a [promise][] is returned. + + + + + +##### `object.patch.appendData` + +> Append Data to the Data field of an existing node. + +###### `Go` **WIP** + +###### `JavaScript` - ipfs.object.patch.appendData(multihash, data, [options, callback]) + +`multihash` is a [multihash][] which can be passed as: + +- Buffer, the raw Buffer of the multihash (or of and encoded version) +- String, the toString version of the multihash (or of an encoded version) + +`data` is a Buffer containing Data to be appended to the existing node. + +`options` is a optional argument of type object, that can contain the following properties: + +- `enc`, the encoding of multihash (base58, base64, etc), if any. + +`callback` must follow `function (err, node) {}` signature, where `err` is an error if the operation was not successful and `node` is a MerkleDAG node of the type [DAGNode][] that resulted by the operation of adding a Link. + +If no `callback` is passed, a [promise][] is returned. + + + + + +##### `object.patch.setData` + +> Reset the Data field of a MerkleDAG Node to new Data + +###### `Go` **WIP** + +###### `JavaScript` - ipfs.object.patch.setData(multihash, data, [options, callback]) + +`multihash` is a [multihash][] which can be passed as: + +- Buffer, the raw Buffer of the multihash (or of and encoded version) +- String, the toString version of the multihash (or of an encoded version) + +`data` is a Buffer containing Data to replace the existing Data on the node. + +`options` is a optional argument of type object, that can contain the following properties: + +- `enc`, the encoding of multihash (base58, base64, etc), if any. + +`callback` must follow `function (err, node) {}` signature, where `err` is an error if the operation was not successful and `node` is a MerkleDAG node of the type [DAGNode][] that resulted by the operation of adding a Link. + +If no `callback` is passed, a [promise][] is returned. + +[DAGNode]: https://github.com/vijayee/js-ipfs-merkle-dag +[multihash]: http://github.com/jbenet/multihash +[promise]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise + + diff --git a/README.md b/README.md index 5e72950e..721378ae 100644 --- a/README.md +++ b/README.md @@ -17,22 +17,22 @@ - [Node.js](#nodejs) - [Go](#go) - [API](#api) - - [Files](#files) - - [`add`](#add) - - [`createAddStream`](#createaddstream) - - [`cat`](#cat) - - [Object](#object) - - [`object.new`](#objectnew) - - [`object.put`](#objectput) - - [`object.get`](#objectget) - - [`object.data`](#objectdata) - - [`object.links`](#objectlinks) - - [`object.stat`](#objectstat) - - [`object.patch`](#objectpatch) - - [`object.patch.addLink`](#objectpatchaddlink) - - [`object.patch.rmLink`](#objectpatchrmlink) - - [`object.patch.appendData`](#objectpatchappenddata) - - [`object.patch.setData`](#objectpatchsetdata) + - [Files](/API/files) + - [`add`](/API/files#add) + - [`createAddStream`](/files#createaddstream) + - [`cat`](/API/files#cat) + - [Object](/API/object) + - [`object.new`](/API/object#objectnew) + - [`object.put`](/API/object#objectput) + - [`object.get`](/API/object#objectget) + - [`object.data`](/API/object#objectdata) + - [`object.links`](/API/object#objectlinks) + - [`object.stat`](/API/object#objectstat) + - [`object.patch`](/API/object#objectpatch) + - [`object.patch.addLink`](/API/object#objectpatchaddlink) + - [`object.patch.rmLink`](/API/object#objectpatchrmlink) + - [`object.patch.appendData`](/API/object#objectpatchappenddata) + - [`object.patch.setData`](/API/object#objectpatchsetdata) - [Contribute](#contribute) - [Want to hack on IPFS?](#want-to-hack-on-ipfs) - [License](#license) @@ -60,12 +60,15 @@ interface-ipfs-core API. ## Install +In JavaScript land: ```js npm install interface-ipfs-core ``` +In Go land: + ```go -# TODO +# Not available ``` ## Usage @@ -96,385 +99,7 @@ test.all(common) ## API -A valid (read: that follows this interface) IPFS core implementation, must expose the following API. - -### Files - -#### `add` - -> Add files and data to IPFS. - -##### `Go` **WIP** - -##### `JavaScript` - ipfs.files.add(data, [callback]) - -Where `data` may be - -- an array of objects, each of the form -```js -{ - path: '/tmp/myfile.txt', - content: (Buffer or Readable stream) -} -``` -- a `Buffer` instance -- a `Readable` stream - -If no `content` is passed, then the path is treated as an empty directory - -`callback` must follow `function (err, res) {}` signature, where `err` is an error if the operation was not successful. `res` will be an array of: - -```js -{ - path: '/tmp/myfile.txt', - node: DAGNode -} -``` - -If no `callback` is passed, a promise is returned. - -Example: - -```js -var files = [ - { - path: '/tmp/myfile.txt', - content: (Buffer or Readable stream) - } -] -ipfs.files.add(files, function (err, files) { - // 'files' will be an array of objects -}) -``` - - -#### `createAddStream` - -> Add files and data to IPFS using a transform stream. - -##### `Go` **WIP** - -##### `JavaScript` - ipfs.files.createAddStream([callback]) - -Provides a Transform stream, where objects can be written of the forms - -```js -{ - path: '/tmp/myfile.txt', - content: (Buffer or Readable stream) -} -``` - -`callback` must follow `function (err, stream) {}` signature, where `err` is an -error if the operation was not successful. `stream` will be a Transform stream, -to which tuples like the above two object formats can be written and [DAGNode][] -objects will be outputted. - -If no `callback` is passed, a promise is returned. - -```js -ipfs.files.createAddStream(function (err, stream) { - stream.on('data', function (file) { - // 'file' will be of the form - // { - // path: '/tmp/myfile.txt', - // node: DAGNode - // } - }) - - stream.write({path: , content: }) - // write as many as you want - - stream.end() -}) -``` - - - - -#### `cat` - -> Streams the file at the given IPFS multihash.. - -##### `Go` **WIP** - -##### `JavaScript` - ipfs.cat(multihash, [callback]) - -`multihash` is a [multihash][] which can be passed as - -- Buffer, the raw Buffer of the multihash -- String, the base58 encoded version of the multihash - -`callback` must follow `function (err, stream) {}` signature, where `err` is an error if the operation was not successful and `stream` is a readable stream of the file. - -If no `callback` is passed, a promise is returned. - -```js -ipfs.files.cat(multihash, function (err, file) { - // file will be a stream containing the data of the file requested -}) -``` - - - - -### Object - -#### `object.new` - -> Create a new MerkleDAG node, using a specific layout. Caveat: So far, only UnixFS object layouts are supported. - -##### `Go` **WIP** - -##### `JavaScript` - ipfs.object.new([callback]) - -`callback` must follow `function (err, node) {}` signature, where `err` is an error if the operation was not successful and `node` is a MerkleDAG node of the type [DAGNode][] - -If no `callback` is passed, a [promise][] is returned. - - - - - -#### `object.put` - -> Store an MerkleDAG node. - -##### `Go` **WIP** - -##### `JavaScript` - ipfs.object.put(obj, [options, callback]) - -`obj` is the MerkleDAG Node to be stored. Can of type: - -- Object, with format `{ Data: , Links: [] }` -- Buffer, requiring that the encoding is specified on the options. If no encoding is specified, Buffer is treated as the Data field -- [DAGNode][] - -`options` is a optional argument of type object, that can contain the following properties: - -- `enc`, the encoding of the Buffer (json, yml, etc), if passed a Buffer. - -`callback` must follow `function (err, node) {}` signature, where `err` is an error if the operation was not successful and `node` is a MerkleDAG node of the type [DAGNode][] - -If no `callback` is passed, a [promise][] is returned. - - - - - -#### `object.get` - -> Fetch a MerkleDAG node - -##### `Go` **WIP** - -##### `JavaScript` - ipfs.object.get(multihash, [options, callback]) - -`multihash` is a [multihash][] which can be passed as: - -- Buffer, the raw Buffer of the multihash (or of and encoded version) -- String, the toString version of the multihash (or of an encoded version) - -`options` is a optional argument of type object, that can contain the following properties: - -- `enc`, the encoding of multihash (base58, base64, etc), if any. - -`callback` must follow `function (err, node) {}` signature, where `err` is an error if the operation was not successful and `node` is a MerkleDAG node of the type [DAGNode][] - -If no `callback` is passed, a [promise][] is returned. - -#### `object.data` - -> Returns the Data field of an object - -##### `Go` **WIP** - -##### `JavaScript` - ipfs.object.data(multihash, [options, callback]) -`multihash` is a [multihash][] which can be passed as: - -- Buffer, the raw Buffer of the multihash (or of and encoded version) -- String, the toString version of the multihash (or of an encoded version) - -`options` is a optional argument of type object, that can contain the following properties: - -- `enc`, the encoding of multihash (base58, base64, etc), if any. - -`callback` must follow `function (err, data) {}` signature, where `err` is an error if the operation was not successful and `data` is a Buffer with the data that the MerkleDAG node contained. - -If no `callback` is passed, a [promise][] is returned. - -#### `object.links` - -> Returns the Links field of an object - -##### `Go` **WIP** - -##### `JavaScript` - ipfs.object.links(multihash, [options, callback]) - -`multihash` is a [multihash][] which can be passed as: - -- Buffer, the raw Buffer of the multihash (or of and encoded version) -- String, the toString version of the multihash (or of an encoded version) - -`options` is a optional argument of type object, that can contain the following properties: - -- `enc`, the encoding of multihash (base58, base64, etc), if any. - -`callback` must follow `function (err, links) {}` signature, where `err` is an error if the operation was not successful and `links` is an Array of [DAGLink](https://github.com/vijayee/js-ipfs-merkle-dag/blob/master/src/dag-node.js#L199-L203) objects. - -If no `callback` is passed, a [promise][] is returned. - - - - - -#### `object.stat` - -> Returns stats about an Object - -##### `Go` **WIP** - -##### `JavaScript` - ipfs.object.stat(multihash, [options, callback]) - -`multihash` is a [multihash][] which can be passed as: - -- Buffer, the raw Buffer of the multihash (or of and encoded version) -- String, the toString version of the multihash (or of an encoded version) - -`options` is a optional argument of type object, that can contain the following properties: - -- `enc`, the encoding of multihash (base58, base64, etc), if any. - -`callback` must follow `function (err, stats) {}` signature, where `err` is an error if the operation was not successful and `stats` is an Object with following format: - -```JavaScript -{ - Hash: 'QmPTkMuuL6PD8L2SwTwbcs1NPg14U8mRzerB1ZrrBrkSDD', - NumLinks: 0, - BlockSize: 10, - LinksSize: 2, - DataSize: 8, - CumulativeSize: 10 -} -``` - -If no `callback` is passed, a [promise][] is returned. - - - - - -#### `object.patch` - -> `object.patch` exposes the available patch calls. - -##### `object.patch.addLink` - -> Add a Link to an existing MerkleDAG Object - -###### `Go` **WIP** - -###### `JavaScript` - ipfs.object.patch.addLink(multihash, DAGLink, [options, callback]) - -`multihash` is a [multihash][] which can be passed as: - -- Buffer, the raw Buffer of the multihash (or of and encoded version) -- String, the toString version of the multihash (or of an encoded version) - -`DAGLink` is the new link to be added on the node that is identified by the `multihash` - -`options` is a optional argument of type object, that can contain the following properties: - -- `enc`, the encoding of multihash (base58, base64, etc), if any. - -`callback` must follow `function (err, node) {}` signature, where `err` is an error if the operation was not successful and `node` is a MerkleDAG node of the type [DAGNode][] that resulted by the operation of adding a Link. - -If no `callback` is passed, a [promise][] is returned. - - - - - -##### `object.patch.rmLink` - -> Remove a Link from an existing MerkleDAG Object - -###### `Go` **WIP** - -###### `JavaScript` - ipfs.object.patch.rmLink(multihash, DAGLink, [options, callback]) - -`multihash` is a [multihash][] which can be passed as: - -- Buffer, the raw Buffer of the multihash (or of and encoded version) -- String, the toString version of the multihash (or of an encoded version) - -`DAGLink` is the link to be removed on the node that is identified by the `multihash` - -`options` is a optional argument of type object, that can contain the following properties: - -- `enc`, the encoding of multihash (base58, base64, etc), if any. - -`callback` must follow `function (err, node) {}` signature, where `err` is an error if the operation was not successful and `node` is a MerkleDAG node of the type [DAGNode][] that resulted by the operation of adding a Link. - -If no `callback` is passed, a [promise][] is returned. - - - - - -##### `object.patch.appendData` - -> Append Data to the Data field of an existing node. - -###### `Go` **WIP** - -###### `JavaScript` - ipfs.object.patch.appendData(multihash, data, [options, callback]) - -`multihash` is a [multihash][] which can be passed as: - -- Buffer, the raw Buffer of the multihash (or of and encoded version) -- String, the toString version of the multihash (or of an encoded version) - -`data` is a Buffer containing Data to be appended to the existing node. - -`options` is a optional argument of type object, that can contain the following properties: - -- `enc`, the encoding of multihash (base58, base64, etc), if any. - -`callback` must follow `function (err, node) {}` signature, where `err` is an error if the operation was not successful and `node` is a MerkleDAG node of the type [DAGNode][] that resulted by the operation of adding a Link. - -If no `callback` is passed, a [promise][] is returned. - - - - - -##### `object.patch.setData` - -> Reset the Data field of a MerkleDAG Node to new Data - -###### `Go` **WIP** - -###### `JavaScript` - ipfs.object.patch.setData(multihash, data, [options, callback]) - -`multihash` is a [multihash][] which can be passed as: - -- Buffer, the raw Buffer of the multihash (or of and encoded version) -- String, the toString version of the multihash (or of an encoded version) - -`data` is a Buffer containing Data to replace the existing Data on the node. - -`options` is a optional argument of type object, that can contain the following properties: - -- `enc`, the encoding of multihash (base58, base64, etc), if any. - -`callback` must follow `function (err, node) {}` signature, where `err` is an error if the operation was not successful and `node` is a MerkleDAG node of the type [DAGNode][] that resulted by the operation of adding a Link. - -If no `callback` is passed, a [promise][] is returned. - -[DAGNode]: https://github.com/vijayee/js-ipfs-merkle-dag -[multihash]: http://github.com/jbenet/multihash -[promise]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise +A valid (read: that follows this interface) IPFS core implementation, must expose the API described in [/API](/API) ## Contribute