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

Commit 666bc94

Browse files
daviddiasdaviddias
authored
Merge pull request #31 from ipfs/separate-apis
break the APIs into separate files
2 parents bc92f91 + 20962c1 commit 666bc94

File tree

3 files changed

+399
-396
lines changed

3 files changed

+399
-396
lines changed

‎API/files/README.md

+118
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,118 @@
1+
files API
2+
=========
3+
4+
#### `add`
5+
6+
> Add files and data to IPFS.
7+
8+
##### `Go` **WIP**
9+
10+
##### `JavaScript` - ipfs.files.add(data, [callback])
11+
12+
Where `data` may be
13+
14+
- an array of objects, each of the form
15+
```js
16+
{
17+
path: '/tmp/myfile.txt',
18+
content: (Buffer or Readable stream)
19+
}
20+
```
21+
- a `Buffer` instance
22+
- a `Readable` stream
23+
24+
If no `content` is passed, then the path is treated as an empty directory
25+
26+
`callback` must follow `function (err, res) {}` signature, where `err` is an error if the operation was not successful. `res` will be an array of:
27+
28+
```js
29+
{
30+
path: '/tmp/myfile.txt',
31+
node: DAGNode
32+
}
33+
```
34+
35+
If no `callback` is passed, a promise is returned.
36+
37+
Example:
38+
39+
```js
40+
var files = [
41+
{
42+
path: '/tmp/myfile.txt',
43+
content: (Buffer or Readable stream)
44+
}
45+
]
46+
ipfs.files.add(files, function (err, files) {
47+
// 'files' will be an array of objects
48+
})
49+
```
50+
51+
52+
#### `createAddStream`
53+
54+
> Add files and data to IPFS using a transform stream.
55+
56+
##### `Go` **WIP**
57+
58+
##### `JavaScript` - ipfs.files.createAddStream([callback])
59+
60+
Provides a Transform stream, where objects can be written of the forms
61+
62+
```js
63+
{
64+
path: '/tmp/myfile.txt',
65+
content: (Buffer or Readable stream)
66+
}
67+
```
68+
69+
`callback` must follow `function (err, stream) {}` signature, where `err` is an
70+
error if the operation was not successful. `stream` will be a Transform stream,
71+
to which tuples like the above two object formats can be written and [DAGNode][]
72+
objects will be outputted.
73+
74+
If no `callback` is passed, a promise is returned.
75+
76+
```js
77+
ipfs.files.createAddStream(function (err, stream) {
78+
stream.on('data', function (file) {
79+
// 'file' will be of the form
80+
// {
81+
// path: '/tmp/myfile.txt',
82+
// node: DAGNode
83+
// }
84+
})
85+
86+
stream.write({path: <path to file>, content: <buffer or readable stream>})
87+
// write as many as you want
88+
89+
stream.end()
90+
})
91+
```
92+
93+
94+
95+
96+
#### `cat`
97+
98+
> Streams the file at the given IPFS multihash..
99+
100+
##### `Go` **WIP**
101+
102+
##### `JavaScript` - ipfs.cat(multihash, [callback])
103+
104+
`multihash` is a [multihash][] which can be passed as
105+
106+
- Buffer, the raw Buffer of the multihash
107+
- String, the base58 encoded version of the multihash
108+
109+
`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.
110+
111+
If no `callback` is passed, a promise is returned.
112+
113+
```js
114+
ipfs.files.cat(multihash, function (err, file) {
115+
// file will be a stream containing the data of the file requested
116+
})
117+
```
118+

‎API/object/README.md

+260
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,260 @@
1+
object API
2+
==========
3+
4+
#### `object.new`
5+
6+
> Create a new MerkleDAG node, using a specific layout. Caveat: So far, only UnixFS object layouts are supported.
7+
8+
##### `Go` **WIP**
9+
10+
##### `JavaScript` - ipfs.object.new([callback])
11+
12+
`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][]
13+
14+
If no `callback` is passed, a [promise][] is returned.
15+
16+
17+
18+
19+
20+
#### `object.put`
21+
22+
> Store an MerkleDAG node.
23+
24+
##### `Go` **WIP**
25+
26+
##### `JavaScript` - ipfs.object.put(obj, [options, callback])
27+
28+
`obj` is the MerkleDAG Node to be stored. Can of type:
29+
30+
- Object, with format `{ Data: <data>, Links: [] }`
31+
- Buffer, requiring that the encoding is specified on the options. If no encoding is specified, Buffer is treated as the Data field
32+
- [DAGNode][]
33+
34+
`options` is a optional argument of type object, that can contain the following properties:
35+
36+
- `enc`, the encoding of the Buffer (json, yml, etc), if passed a Buffer.
37+
38+
`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][]
39+
40+
If no `callback` is passed, a [promise][] is returned.
41+
42+
43+
44+
45+
46+
#### `object.get`
47+
48+
> Fetch a MerkleDAG node
49+
50+
##### `Go` **WIP**
51+
52+
##### `JavaScript` - ipfs.object.get(multihash, [options, callback])
53+
54+
`multihash` is a [multihash][] which can be passed as:
55+
56+
- Buffer, the raw Buffer of the multihash (or of and encoded version)
57+
- String, the toString version of the multihash (or of an encoded version)
58+
59+
`options` is a optional argument of type object, that can contain the following properties:
60+
61+
- `enc`, the encoding of multihash (base58, base64, etc), if any.
62+
63+
`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][]
64+
65+
If no `callback` is passed, a [promise][] is returned.
66+
67+
#### `object.data`
68+
69+
> Returns the Data field of an object
70+
71+
##### `Go` **WIP**
72+
73+
##### `JavaScript` - ipfs.object.data(multihash, [options, callback])
74+
`multihash` is a [multihash][] which can be passed as:
75+
76+
- Buffer, the raw Buffer of the multihash (or of and encoded version)
77+
- String, the toString version of the multihash (or of an encoded version)
78+
79+
`options` is a optional argument of type object, that can contain the following properties:
80+
81+
- `enc`, the encoding of multihash (base58, base64, etc), if any.
82+
83+
`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.
84+
85+
If no `callback` is passed, a [promise][] is returned.
86+
87+
#### `object.links`
88+
89+
> Returns the Links field of an object
90+
91+
##### `Go` **WIP**
92+
93+
##### `JavaScript` - ipfs.object.links(multihash, [options, callback])
94+
95+
`multihash` is a [multihash][] which can be passed as:
96+
97+
- Buffer, the raw Buffer of the multihash (or of and encoded version)
98+
- String, the toString version of the multihash (or of an encoded version)
99+
100+
`options` is a optional argument of type object, that can contain the following properties:
101+
102+
- `enc`, the encoding of multihash (base58, base64, etc), if any.
103+
104+
`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.
105+
106+
If no `callback` is passed, a [promise][] is returned.
107+
108+
109+
110+
111+
112+
#### `object.stat`
113+
114+
> Returns stats about an Object
115+
116+
##### `Go` **WIP**
117+
118+
##### `JavaScript` - ipfs.object.stat(multihash, [options, callback])
119+
120+
`multihash` is a [multihash][] which can be passed as:
121+
122+
- Buffer, the raw Buffer of the multihash (or of and encoded version)
123+
- String, the toString version of the multihash (or of an encoded version)
124+
125+
`options` is a optional argument of type object, that can contain the following properties:
126+
127+
- `enc`, the encoding of multihash (base58, base64, etc), if any.
128+
129+
`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:
130+
131+
```JavaScript
132+
{
133+
Hash: 'QmPTkMuuL6PD8L2SwTwbcs1NPg14U8mRzerB1ZrrBrkSDD',
134+
NumLinks: 0,
135+
BlockSize: 10,
136+
LinksSize: 2,
137+
DataSize: 8,
138+
CumulativeSize: 10
139+
}
140+
```
141+
142+
If no `callback` is passed, a [promise][] is returned.
143+
144+
145+
146+
147+
148+
#### `object.patch`
149+
150+
> `object.patch` exposes the available patch calls.
151+
152+
##### `object.patch.addLink`
153+
154+
> Add a Link to an existing MerkleDAG Object
155+
156+
###### `Go` **WIP**
157+
158+
###### `JavaScript` - ipfs.object.patch.addLink(multihash, DAGLink, [options, callback])
159+
160+
`multihash` is a [multihash][] which can be passed as:
161+
162+
- Buffer, the raw Buffer of the multihash (or of and encoded version)
163+
- String, the toString version of the multihash (or of an encoded version)
164+
165+
`DAGLink` is the new link to be added on the node that is identified by the `multihash`
166+
167+
`options` is a optional argument of type object, that can contain the following properties:
168+
169+
- `enc`, the encoding of multihash (base58, base64, etc), if any.
170+
171+
`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.
172+
173+
If no `callback` is passed, a [promise][] is returned.
174+
175+
176+
177+
178+
179+
##### `object.patch.rmLink`
180+
181+
> Remove a Link from an existing MerkleDAG Object
182+
183+
###### `Go` **WIP**
184+
185+
###### `JavaScript` - ipfs.object.patch.rmLink(multihash, DAGLink, [options, callback])
186+
187+
`multihash` is a [multihash][] which can be passed as:
188+
189+
- Buffer, the raw Buffer of the multihash (or of and encoded version)
190+
- String, the toString version of the multihash (or of an encoded version)
191+
192+
`DAGLink` is the link to be removed on the node that is identified by the `multihash`
193+
194+
`options` is a optional argument of type object, that can contain the following properties:
195+
196+
- `enc`, the encoding of multihash (base58, base64, etc), if any.
197+
198+
`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.
199+
200+
If no `callback` is passed, a [promise][] is returned.
201+
202+
203+
204+
205+
206+
##### `object.patch.appendData`
207+
208+
> Append Data to the Data field of an existing node.
209+
210+
###### `Go` **WIP**
211+
212+
###### `JavaScript` - ipfs.object.patch.appendData(multihash, data, [options, callback])
213+
214+
`multihash` is a [multihash][] which can be passed as:
215+
216+
- Buffer, the raw Buffer of the multihash (or of and encoded version)
217+
- String, the toString version of the multihash (or of an encoded version)
218+
219+
`data` is a Buffer containing Data to be appended to the existing node.
220+
221+
`options` is a optional argument of type object, that can contain the following properties:
222+
223+
- `enc`, the encoding of multihash (base58, base64, etc), if any.
224+
225+
`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.
226+
227+
If no `callback` is passed, a [promise][] is returned.
228+
229+
230+
231+
232+
233+
##### `object.patch.setData`
234+
235+
> Reset the Data field of a MerkleDAG Node to new Data
236+
237+
###### `Go` **WIP**
238+
239+
###### `JavaScript` - ipfs.object.patch.setData(multihash, data, [options, callback])
240+
241+
`multihash` is a [multihash][] which can be passed as:
242+
243+
- Buffer, the raw Buffer of the multihash (or of and encoded version)
244+
- String, the toString version of the multihash (or of an encoded version)
245+
246+
`data` is a Buffer containing Data to replace the existing Data on the node.
247+
248+
`options` is a optional argument of type object, that can contain the following properties:
249+
250+
- `enc`, the encoding of multihash (base58, base64, etc), if any.
251+
252+
`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.
253+
254+
If no `callback` is passed, a [promise][] is returned.
255+
256+
[DAGNode]: https://github.com/vijayee/js-ipfs-merkle-dag
257+
[multihash]: http://github.com/jbenet/multihash
258+
[promise]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise
259+
260+

0 commit comments

Comments
 (0)