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

next generation #305

Merged
merged 17 commits into from
Aug 18, 2016
Merged

next generation #305

Show file tree
Hide file tree
Changes from 15 commits
Commits
Show all changes
17 commits
Select commit Hold shift + click to select a range
0534fa8
feat(API): kick off ipfs-api next generation
daviddias Jun 30, 2016
940c997
feat(API): follow interface-ipfs-core config spec
daviddias Jun 30, 2016
73078ea
refactor(dev): point main to src while under dev
daviddias Jul 2, 2016
108414b
refactor(module+tests): Enable running the tests
daviddias Jun 30, 2016
43a1dfa
refactor(request-api): mov away from arg flags, use option object ins…
daviddias Aug 15, 2016
e5cb43c
refactor(clean-multihash): remove duplicate (old) cleanMultihash func
daviddias Aug 15, 2016
11a166e
refactor(tests): make each feature test isolated (launchable by itself
daviddias Aug 15, 2016
776cccd
Merge pull request #313 from ipfs/clean-madness
daviddias Aug 15, 2016
ed07921
feat(pin): spec compliant pinning
daviddias Aug 15, 2016
e97c567
feat(generic): make it spec compliant
daviddias Aug 16, 2016
ba0fc67
feat(deps): clean and update
daviddias Aug 16, 2016
5d0a823
feat(swarm): spec compliant
daviddias Aug 16, 2016
5f71752
feat(internals): use promisify for every exposed interface and apply CR
daviddias Aug 17, 2016
4cffb47
feat(dependencies): update dependencies
daviddias Aug 17, 2016
2ae09fb
feat(util): add fsAdd, streamAdd and urlAdd
daviddias Aug 17, 2016
17f95fb
fix(block): testing
daviddias Aug 17, 2016
c0e66cb
fix(CR): apply CR
daviddias Aug 18, 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
204 changes: 0 additions & 204 deletions API.md
View file
Open in desktop

This file was deleted.

80 changes: 72 additions & 8 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,4 +1,5 @@
# js-ipfs-api
ipfs-api
========

[![](https://img.shields.io/badge/made%20by-Protocol%20Labs-blue.svg?style=flat-square)](http://ipn.io)
[![](https://img.shields.io/badge/project-IPFS-blue.svg?style=flat-square)](http://ipfs.io/)
Expand All @@ -9,7 +10,9 @@
[![Travis CI](https://travis-ci.org/ipfs/js-ipfs-api.svg?branch=master)](https://travis-ci.org/ipfs/js-ipfs-api)
[![Circle CI](https://circleci.com/gh/ipfs/js-ipfs-api.svg?style=svg)](https://circleci.com/gh/ipfs/js-ipfs-api)

> A client library for the IPFS HTTP API, implemented in JavaScript.
> A client library for the IPFS HTTP API, implemented in JavaScript. This client library implements the [interface-ipfs-core](https://github.com/ipfs/interface-ipfs-core) enabling applications to change between a embebed js-ipfs node and any remove IPFS node without having to change the code. In addition, this client library implements a set of utility functions.
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

remove -> remote I'm guessing :)


![](https://github.com/ipfs/interface-ipfs-core/raw/master/img/badge.png)

## Table of Contents

Expand Down Expand Up @@ -102,16 +105,71 @@ $ ipfs config --json API.HTTPHeaders.Access-Control-Allow-Origin "[\"http://exam

### API

> `WIP`

`js-ipfs-api` follows the spec defined by [`interface-ipfs-core`](https://github.com/ipfs/interface-ipfs-core), which concerns the interface to expect from IPFS implementations. This interface is a currently active endeavor - expect it to be complete in the next few weeks (August 2016). You can use it today to consult the methods available.
> `js-ipfs-api` follows the spec defined by [`interface-ipfs-core`](https://github.com/ipfs/interface-ipfs-core), which concerns the interface to expect from IPFS implementations. This interface is a currently active endeavor - expect it to be complete in the next few weeks (August 2016). You can use it today to consult the methods available.

### Extra API methods
### Utility functions

Adding to the methods defined by [`interface-ipfs-core`](https://github.com/ipfs/interface-ipfs-core), `js-ipfs-api` exposes a set of extra utility methods.
Adding to the methods defined by [`interface-ipfs-core`](https://github.com/ipfs/interface-ipfs-core), `js-ipfs-api` exposes a set of extra utility methods. These utility functions are scoped behind the `ipfs.util`.

Complete documentation for these methods is coming with: https://github.com/ipfs/js-ipfs-api/pull/305


#### Add files or entire directories from the FileSystem to IPFS

> `ipfs.util.fsAdd(path, option, callback)`

Reads path from disk (if directory add an options `{ recursive: true }` and adds it to IPFS.

Copy link
Contributor

@haadcode haadcode Aug 17, 2016 •
edited by daviddias
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Missing ) after recursive: true. Might be better to word it as:

Reads a file from path on the filesystem and adds it to IPFS. If path is a directory, use option { recursive: true } to add the directory and all its sub-directories.

```JavaScript
ipfs.util.fsAdd(<dirpath>, { recursive: true }, (err, result) => {
if (err) {
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

instead of , let's put a real path there:

ipfs.util.fsAdd('path/to/a/file', { recursive: true }, (err, result) => {

throw err
}
console.log(result)
})
```

`files` is an array of objects describing the files that were added, such as:

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

files should be result

```
[{
path: 'test-folder',
hash: 'QmRNjDeKStKGTQXnJ2NFqeQ9oW23WcpbmvCVrpDHgDg3T6',
size: 2278
},
// ...
]
```

#### Add a file from a URL to IPFS

> `ipfs.util.urlAdd(url, callback)`

```JavaScript
ipfs.util.urlAdd('http://example.com/', (err, result) => {
if (err) {
throw err
}
console.log(result)
})

```

#### Add a file from a stream to IPFS

> `ipfs.util.streamAdd(stream, callback)`

This is very similar to `ipfs.files.add({path:'', content: stream})`. It is like the reverse of cat

```JavaScript
ipfs.util.streamAdd(<readable-stream>, (err, result) => {
if (err) {
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Can we add an example how to write to the stream so that the example is explicit?

stream.write(what goes here?)
stream.end

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

It is a readable-stream, you don't really write to it.

throw err
}
console.log(result)
})
```
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Looking at the .streamAdd as a whole, how is it different from ipfs.files.add(stream, ...)? What does it take as an input to the stream? I think that should be described here, too.

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Nothing really, it is just 'backwards' "UX'ibility". ipfs.files.add does the same thing.


Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This might be too much bikeshedding, but I was thinking the naming of the functions. Instead of .fsAdd(), .streamAdd(), urlAdd() how about:
.addFromStream()
.addFromUrl()
.addFromFs()

I think switching the wording would make it a little from consistent and intuitive.

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

you got it :)

### Callbacks and promises

If you do not pass in a callback all API functions will return a `Promise`. For example:
Expand All @@ -135,9 +193,11 @@ yet available you need to bring your own polyfill.

We run tests by executing `npm test` in a terminal window. This will run both Node.js and Browser tests, both in Chrome and PhantomJS. To ensure that the module conforms with the [`interface-ipfs-core`](https://github.com/ipfs/interface-ipfs-core) spec, we run the batch of tests provided by the interface module, which can be found [here](https://github.com/ipfs/interface-ipfs-core/tree/master/src).



## Contribute

The js-ipfs API is a work in progress. As such, there's a few things you can do right now to help out:
The js-ipfs-api is a work in progress. As such, there's a few things you can do right now to help out:

* **[Check out the existing issues](https://github.com/ipfs/js-ipfs-api/issues)**!
* **Perform code reviews**. More eyes will help a) speed the project along b) ensure quality and c) reduce possible future bugs.
Expand All @@ -148,6 +208,10 @@ The js-ipfs API is a work in progress. As such, there's a few things you can do

[![](https://cdn.rawgit.com/jbenet/contribute-ipfs-gif/master/img/contribute.gif)](https://github.com/ipfs/community/blob/master/contributing.md)

## Historical context

This module started as a direct mapping from the go-ipfs cli to a JavaScript implementation, although this was useful and familiar to a lot of developers that were coming to IPFS for the first time, it also created some confusion on how to operate the core of IPFS and have access to the full capacity of the protocol. After much consideration, we decided to create `interface-ipfs-core` with the goal of standardizing the interface of a core implementation of IPFS, and keep the utility functions the IPFS community learned to use and love, such as reading files from disk and storing them directly to IPFS.

## License

[MIT](LICENSE)
32 changes: 16 additions & 16 deletions package.json
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,9 +1,21 @@
{
"name": "ipfs-api",
"version": "6.0.3",
"description": "A client library for the IPFS API",
"description": "A client library for the IPFS HTTP API. Follows interface-ipfs-core spec",
"main": "lib/index.js",
"jsnext:main": "src/index.js",
"scripts": {
"test": "node --max_old_space_size=4096 node_modules/.bin/gulp test",
"test:node": "gulp test:node",
"test:browser": "node --max_old_space_size=4096 node_modules/.bin/gulp test:browser",
"lint": "aegir-lint",
"build": "gulp build",
"release": "gulp release",
"release-minor": "gulp release --type minor",
"release-major": "gulp release --type major",
"coverage": "gulp coverage",
"coverage-publish": "aegir-coverage publish"
},
"dependencies": {
"async": "^2.0.1",
"babel-runtime": "^6.11.6",
Expand All @@ -20,6 +32,7 @@
"ndjson": "^1.4.3",
"promisify-es6": "^1.0.1",
"qs": "^6.2.1",
"tar-stream": "^1.5.2",
"wreck": "^9.0.0"
},
"engines": {
Expand All @@ -30,32 +43,19 @@
"url": "https://github.com/ipfs/js-ipfs-api"
},
"devDependencies": {
"aegir": "^6.0.0",
"aegir": "^6.0.1",
"chai": "^3.5.0",
"gulp": "^3.9.1",
"hapi": "^14.1.0",
"interface-ipfs-core": "^0.8.0",
"interface-ipfs-core": "^0.12.0",
"ipfsd-ctl": "^0.14.0",
"passthrough-counter": "^1.0.0",
"pre-commit": "^1.1.3",
"socket.io": "^1.4.8",
"socket.io-client": "^1.4.8",
"stream-equal": "^0.1.8",
"stream-http": "^2.3.1",
"streamifier": "^0.1.1"
},
"scripts": {
"test": "gulp test",
"test:node": "gulp test:node",
"test:browser": "gulp test:browser",
"lint": "aegir-lint",
"build": "gulp build",
"release": "gulp release",
"release-minor": "gulp release --type minor",
"release-major": "gulp release --type major",
"coverage": "gulp coverage",
"coverage-publish": "aegir-coverage publish"
},
"pre-commit": [
"lint",
"test"
Expand Down
Loading