Skip to content
This repository was archived by the owner on Mar 10, 2020. It is now read-only.

draft api docs for blocks #15

Merged
merged 4 commits into from
May 17, 2016
Merged

draft api docs for blocks #15

Changes from all commits
Commits
Show all changes
4 commits
Select commit Hold shift + click to select a range
c3bcf39
use markdown footnotes for DAGNode
hackergrrl May 17, 2016
e9f08c3
linkify multihash
hackergrrl May 17, 2016
aeb8cce
blocks api draft
hackergrrl May 17, 2016
afc2a02
update block stat format
hackergrrl May 17, 2016
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
113 changes: 93 additions & 20 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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`
Expand All @@ -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.

Expand All @@ -84,13 +156,13 @@ If no `callback` is passed, a promise is returned.

- Object, with format `{ Data: <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.

Expand All @@ -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)
Expand All @@ -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)
Expand All @@ -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)
Expand All @@ -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)
Expand Down Expand Up @@ -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)
Expand All @@ -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.

Expand All @@ -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)
Expand All @@ -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.

Expand All @@ -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)
Expand All @@ -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.

Expand All @@ -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)
Expand All @@ -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