diff --git a/README.md b/README.md index 8ec096e29..afe6c1d2a 100644 --- a/README.md +++ b/README.md @@ -54,6 +54,78 @@ test.all(common) A valid (read: that follows this interface) IPFS core implementation, must expose the following API. +## Block + +### `block.put` + +> Create a new IPFS Block. + +##### `Go` **WIP** + +##### `JavaScript` - ipfs.block.put(data, [callback]) + +Where `data` can be a + +- Buffer, requiring that the encoding is specified on the options. If no + encoding is specified, Buffer is treated as the Data field +- [Block][] instance + +`callback` has the signature `function (err, block) {}`, where `err` is an error +if the operation was not successful. and `block` is a [Block][]. + + + + +### `block.get` + +> Retrieve an IPFS Block from the underlying Block Store by its mulithash. + +##### `Go` **WIP** + +##### `JavaScript` - ipfs.block.get(multihash, [callback]) + +`multihash` is a [multihash][] which can be passed as a + +- Buffer, the raw Buffer of the multihash (or of and encoded version) +- String, the toString version of the multihash (or of an encoded version) + +`callback` must follow the signature `function (err, node) {}`, where `err` is +an error if the operation was not successful and `block` is a [Block][]. + +If no `callback` is passed, a promise is returned. + + + + +### `block.stat` + +> Returns various stats of an IPFS Block + +##### `Go` **WIP** + +##### `JavaScript` - ipfs.block.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) + +`callback` must follow the signature `function (err, stats) {}`, where `err` is +an error if the operation was not successful and `stats` is an object with +the format + +```JavaScript +{ + Key: 'QmPTkMuuL6PD8L2SwTwbcs1NPg14U8mRzerB1ZrrBrkSDD', + Size: 10 +} +``` + +If no `callback` is passed, a promise is returned. + + + + ## Object ### `object.new` @@ -64,7 +136,7 @@ A valid (read: that follows this interface) IPFS core implementation, must expos ##### `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](https://github.com/vijayee/js-ipfs-merkle-dag/blob/master/src/dag-node.js) +`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. @@ -84,13 +156,13 @@ If no `callback` is passed, a promise is returned. - 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](https://github.com/vijayee/js-ipfs-merkle-dag/blob/master/src/dag-node.js). +- [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](https://github.com/vijayee/js-ipfs-merkle-dag/blob/master/src/dag-node.js) +`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. @@ -106,7 +178,7 @@ If no `callback` is passed, a promise is returned. ##### `JavaScript` - ipfs.object.get(multihash, [options, callback]) -`multihash` is a [multihash]() which can be passed as: +`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) @@ -115,18 +187,14 @@ If no `callback` is passed, a promise is returned. - `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](https://github.com/vijayee/js-ipfs-merkle-dag/blob/master/src/dag-node.js) +`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: +`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) @@ -147,7 +215,7 @@ If no `callback` is passed, a promise is returned. ##### `JavaScript` - ipfs.object.links(multihash, [options, callback]) -`multihash` is a [multihash]() which can be passed as: +`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) @@ -172,7 +240,7 @@ If no `callback` is passed, a promise is returned. ##### `JavaScript` - ipfs.object.stat(multihash, [options, callback]) -`multihash` is a [multihash]() which can be passed as: +`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) @@ -212,7 +280,7 @@ If no `callback` is passed, a promise is returned. ##### `JavaScript` - ipfs.object.patch.addLink(multihash, DAGLink, [options, callback]) -`multihash` is a [multihash]() which can be passed as: +`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) @@ -223,7 +291,7 @@ If no `callback` is passed, a promise is returned. - `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](https://github.com/vijayee/js-ipfs-merkle-dag/blob/master/src/dag-node.js) that resulted by the operation of adding a Link. +`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. @@ -239,7 +307,7 @@ If no `callback` is passed, a promise is returned. ##### `JavaScript` - ipfs.object.patch.rmLink(multihash, DAGLink, [options, callback]) -`multihash` is a [multihash]() which can be passed as: +`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) @@ -250,7 +318,7 @@ If no `callback` is passed, a promise is returned. - `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](https://github.com/vijayee/js-ipfs-merkle-dag/blob/master/src/dag-node.js) that resulted by the operation of adding a Link. +`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. @@ -266,7 +334,7 @@ If no `callback` is passed, a promise is returned. ##### `JavaScript` - ipfs.object.patch.appendData(multihash, data, [options, callback]) -`multihash` is a [multihash]() which can be passed as: +`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) @@ -277,7 +345,7 @@ If no `callback` is passed, a promise is returned. - `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](https://github.com/vijayee/js-ipfs-merkle-dag/blob/master/src/dag-node.js) that resulted by the operation of adding a Link. +`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. @@ -293,7 +361,7 @@ If no `callback` is passed, a promise is returned. ##### `JavaScript` - ipfs.object.patch.setData(multihash, data, [options, callback]) -`multihash` is a [multihash]() which can be passed as: +`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) @@ -304,6 +372,11 @@ If no `callback` is passed, a promise is returned. - `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](https://github.com/vijayee/js-ipfs-merkle-dag/blob/master/src/dag-node.js) that resulted by the operation of adding a Link. +`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. + + +[Block]: https://github.com/ipfs/js-ipfs-block +[DAGNode]: https://github.com/vijayee/js-ipfs-merkle-dag +[multihash]: http://github.com/jbenet/multihash