Name: js-ipfs-api
Owner: Parity Technologies
Description: A client library for the IPFS HTTP API, implemented in JavaScript.
Forked from: ipfs/js-ipfs-api
Created: 2017-05-16 15:28:29.0
Updated: 2017-05-16 15:28:31.0
Pushed: 2017-05-16 15:34:16.0
Size: 24828
Language: JavaScript
GitHub Committers
User | Most Recent Commit | # Commits |
---|
Other Committers
User | Most Recent Commit | # Commits |
---|
A client library for the IPFS HTTP API, implemented in JavaScript. This client library implements the interface-ipfs-core enabling applications to change between a embebed js-ipfs node and any remote IPFS node without having to change the code. In addition, this client library implements a set of utility functions.
This module uses node.js, and can be installed through npm:
m install --save ipfs-api
Note: ipfs-api requires Node.js v4 (LTS) or higher.
To interact with the API, you need to have a local daemon running. It needs to be open on the right port. 5001
is the default, and is used in the examples below, but it can be set to whatever you need.
ow the ipfs config API port to check it is correct
fs config Addresses.API
/127.0.0.1/tcp/5001
t it if it does not match the above output
fs config Addresses.API /ip4/127.0.0.1/tcp/5001
start the daemon after changing the config
n the daemon
fs daemon
ipfsAPI = require('ipfs-api')
onnect to ipfs daemon API server
ipfs = ipfsAPI('localhost', '5001', {protocol: 'http'}) // leaving out the arguments will default to these values
r connect with multiaddr
ipfs = ipfsAPI('/ip4/127.0.0.1/tcp/5001')
r using options
ipfs = ipfsAPI({host: 'localhost', port: '5001', protocol: 'http'})
Same as in Node.js, you just have to browserify the code before serving it. See the browserify repo for how to do that.
See the example in the examples folder to get a boilerplate.
See the example in the examples folder to get an idea on how to use js-ipfs-api with webpack
Instead of a local installation (and browserification) you may request a remote copy of IPFS API from unpkg CDN.
To always request the latest version, use the following:
ipt src="https://unpkg.com/ipfs-api/dist/index.js"></script>
For maximum security you may also decide to:
reference a specific version of IPFS API (to prevent unexpected breaking changes when a newer latest version is published)
generate a SRI hash of that version and use it to ensure integrity
set the CORS settings attribute to make anonymous requests to CDN
Example:
ipt src="https://unpkg.com/ipfs-api@9.0.0/dist/index.js"
grity="sha384-5bXRcW9kyxxnSMbOoHzraqa7Z0PQWIao+cgeg327zit1hz5LZCEbIMx/LWKPReuB"
sorigin="anonymous"></script>
CDN-based IPFS API provides the IpfsApi
constructor as a method of the global window
object. Example:
ipfs = window.IpfsApi('localhost', '5001')
If you omit the host and port, the API will parse window.host
, and use this information. This also works, and can be useful if you want to write apps that can be run from multiple different gateways:
ipfs = window.IpfsApi()
In a web browser IPFS API (either browserified or CDN-based) might encounter an error saying that the origin is not allowed. This would be a CORS (“Cross Origin Resource Sharing”) failure: IPFS servers are designed to reject requests from unknown domains by default. You can whitelist the domain that you are calling from by changing your ipfs config like this:
fs config --json API.HTTPHeaders.Access-Control-Allow-Origin "[\"http://example.com\"]"
fs config --json API.HTTPHeaders.Access-Control-Allow-Credentials "[\"true\"]"
fs config --json API.HTTPHeaders.Access-Control-Allow-Methods "[\"PUT\", \"POST\", \"GET\"]"
js-ipfs-api
follows the spec defined byinterface-ipfs-core
, which concerns the interface to expect from IPFS implementations. This interface is a currently active endeavor. You can use it today to consult the methods available.
Currently, the PubSub API only works in Node.js envinroment
We currently don't support pubsub when run in the browser, and we test it with separate set of tests to make sure if it's being used in the browser, pubsub errors.
More info: https://github.com/ipfs/js-ipfs-api/issues/518
This means:
ipfs.block.get(cid, [options, callback])
ipfs.block.put(block, cid, [callback])
ipfs.block.stat(cid, [callback])
ipfs.config.get([key, callback])
ipfs.config.set(key, value, [callback])
ipfs.config.replace(config, [callback])
ipfs.dag.put(dagNode, options, callback)
ipfs.dag.get(cid [, path, options], callback)
ipfs.dag.tree(cid [, path, options], callback)
ipfs.files.add(data, [options], [callback])
ipfs.add
ipfs.files.createAddStream([options], [callback])
ipfs.files.cat(multihash, [callback])
ipfs.cat
ipfs.files.get(hash, [callback])
ipfs.get
ipfs.ls
ipfs.files.cp
ipfs.files.ls
ipfs.files.mkdir
ipfs.files.stat
ipfs.files.rm
ipfs.files.read
ipfs.files.write
ipfs.files.mv
ipfs.object.new([template][, callback])
ipfs.object.put(obj, [options, callback])
ipfs.object.get(multihash, [options, callback])
ipfs.object.data(multihash, [options, callback])
ipfs.object.links(multihash, [options, callback])
ipfs.object.stat(multihash, [options, callback])
ipfs.object.patch.addLink(multihash, DAGLink, [options, callback])
ipfs.object.patch.rmLink(multihash, DAGLink, [options, callback])
ipfs.object.patch.appendData(multihash, data, [options, callback])
ipfs.object.patch.setData(multihash, data, [options, callback])
active branch: https://github.com/ipfs/js-ipfs-api/pull/493
ipfs.pubsub.subscribe(topic, options, handler, callback)
ipfs.pubsub.unsubscribe(topic, handler)
ipfs.pubsub.publish(topic, data, callback)
ipfs.pubsub.ls(topic, callback)
ipfs.pubsub.peers(topic, callback)
ipfs.swarm.addrs([callback])
ipfs.swarm.connect(addr, [callback])
ipfs.swarm.disconnect(addr, [callback])
ipfs.swarm.peers([opts] [, callback])
Adding to the methods defined by 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
ipfs.util.addFromFs(path, option, callback)
Reads a file or folder from path
on the filesystem and adds it to IPFS. Options:
path
is a directory, use option { recursive: true }
to add the directory and all its sub-directories.{ ignore: ['ignore/this/folder/**', 'and/this/file'] }
..
, for example, .git/
) are not included by default. To add them, use the option { hidden: true }
..util.addFromFs('path/to/a/folder', { recursive: true , ignore: ['subfolder/to/ignore/**']}, (err, result) => {
(err) {
throw err
nsole.log(result)
result
is an array of objects describing the files that were added, such as:
th: 'test-folder',
sh: 'QmRNjDeKStKGTQXnJ2NFqeQ9oW23WcpbmvCVrpDHgDg3T6',
ze: 2278
..
ipfs.util.addFromURL(url, callback)
.util.addFromURL('http://example.com/', (err, result) => {
(err) {
throw err
nsole.log(result)
ipfs.util.addFromStream(stream, callback)
This is very similar to ipfs.files.add({path:'', content: stream})
. It is like the reverse of cat
.util.addFromStream(<readable-stream>, (err, result) => {
(err) {
throw err
nsole.log(result)
If you do not pass in a callback all API functions will return a Promise
. For example:
.id()
hen(function (id) {
console.log('my id is: ', id)
atch(function(err) {
console.log('Fail: ', err)
This relies on a global Promise
object. If you are in an environment where that is not
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
spec, we run the batch of tests provided by the interface module, which can be found here.
The js-ipfs-api is a work in progress. As such, there's a few things you can do right now to help out:
interface-ipfs-core
.Want to hack on IPFS?
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.