ipfs-http-client-lite

A lightweight JavaScript HTTP client library for IPFS.

An alternative client library for the IPFS HTTP API, aiming to be as lightweight as possible (<20KB) in the browser.

Lead Maintainer

Alan Shaw.

Table of Contents

• Install
• Usage
  • Running the daemon with the right port
  • CORS
  • Custom HTTP Headers
  • Importing
  • API Docs
• Contribute
• License

Install

This module requires Node.js and npm to install:

npm install --save ipfs-http-client-lite

We support both the Current and Active LTS versions of Node.js. Please see nodejs.org for what these currently are.

Usage

Running the daemon with the right port

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.

# Show the ipfs config API port to check it is correct
> ipfs config Addresses.API
/ip4/127.0.0.1/tcp/5001
# Set it if it does not match the above output
> ipfs config Addresses.API /ip4/127.0.0.1/tcp/5001
# Restart the daemon after changing the config

# Run the daemon
> ipfs daemon

CORS

In a web browser IPFS HTTP client (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:

$ ipfs config --json API.HTTPHeaders.Access-Control-Allow-Origin  '["http://example.com"]'
$ ipfs config --json API.HTTPHeaders.Access-Control-Allow-Methods '["PUT", "POST", "GET"]'

Custom HTTP Headers

If you wish to send custom headers with each request made by this library, for example, the Authorization header. You can use the config to do so:

const ipfs = IpfsHttpClientLite({
  apiUrl: 'http://localhost:5001',
  headers: {
    Authorization: 'Bearer ' + TOKEN
  }
})

Importing

const IpfsHttpClientLite = require('ipfs-http-client-lite')

// Connect to ipfs daemon HTTP API server
const ipfs = IpfsHttpClientLite('http://localhost:5001')
// Note: leaving out the argument will default to this value

For ultra small bundle size, import just the methods you need. e.g.

const cat = require('ipfs-http-client-lite/src/cat')('http://localhost:5001')
const data = await cat('QmQeEyDPA47GqnduyVVWNdnj6UBPXYPVWogAQoqmAcLx6y')

In a web browser

Bundling

This module can be bundled with webpack and browserify and should be compatible with most other bundlers.

CDN

Instead of a local installation (and bundling) you may request a remote copy of the IPFS HTTP API client from unpkg CDN.

To always request the latest version, use the following:

<script src="https://unpkg.com/ipfs-http-client-lite/dist/index.min.js"></script>

You can also use the un-minified version, just remove ".min" from the URL.

For maximum security you may also decide to:

• Reference a specific version of the IPFS HTTP API client (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:

<script src="https://unpkg.com/ipfs-http-client-lite@1.0.0/dist/index.js"
integrity="sha384-5bXRcW9kyxxnSMbOoHzraqa7Z0PQWIao+cgeg327zit1hz5LZCEbIMx/LWKPReuB"
crossorigin="anonymous"></script>

The CDN-based IPFS HTTP API provides the IpfsHttpClientLite constructor as a property of the global window object. Example:

const ipfs = window.IpfsHttpClientLite('http://localhost:5001')

If you omit the URL, the client will parse window.location.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:

const ipfs = window.IpfsHttpClientLite()

API

This module is in heavy development, not all API methods are available (or documented) yet!

• IpfsHttpClientLite
• add
• addFromFs
• addFromStream TODO: add docs
• addFromURL TODO: add docs
• addPullStream
• bitswap.stat TODO: add docs
• bitswap.wantlist TODO: add docs
• block.get
• block.put
• block.stat
• bootstrap.add
• bootstrap.list
• bootstrap.rm
• cat
• catPullStream TODO: add docs
• config.get
• config.replace
• config.set
• dag.get
• dag.put
• dag.tree
• dht.findPeer
• dht.findProvs
• dht.get
• dht.provide
• dht.put
• dht.query
• dns
• files.cp
• files.flush
• files.ls
• files.lsPullStream
• files.mkdir
• files.mv
• files.read
• files.readPullStream
• files.rm
• files.stat
• files.write
• id TODO: add docs
• key.export
• key.gen
• key.import
• key.list
• key.rename
• key.rm
• ls TODO: add docs
• lsPullStream TODO: add docs
• name.pubsub.cancel
• name.pubsub.state
• name.pubsub.subs
• object.data
• object.get
• object.links
• object.new
• object.patch.addLink
• object.patch.appendData
• object.patch.rmLink
• object.patch.setData
• object.put
• pin.add
• pin.ls
• pin.rm
• ping TODO: add docs
• pingPullStream TODO: add docs
• pubsub.ls
• pubsub.peers
• pubsub.publish
• pubsub.subscribe
• pubsub.unsubscribe
• refs
• refsPullStream
• refs.local
• refs.localPullStream
• repo.gc
• repo.stat
• repo.version
• resolve
• shutdown
• stats.bitswap
• stats.bw
• stats.bwPullStream
• stats.repo
• swarm.addrs
• swarm.connect
• swarm.disconnect
• swarm.localAddrs
• swarm.peers
• version TODO: add docs

Note: All API methods are documented using Promises/async/await but they also accept a callback as their last parameter.

Testing

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.

Contribute

Feel free to dive in! Open an issue or submit PRs.

Want to hack on IPFS?

License

Dual-licensed under Apache 2.0 and MIT terms:

• Apache License, Version 2.0, (LICENSE-APACHE or http://www.apache.org/licenses/LICENSE-2.0)
• MIT license (LICENSE-MIT or http://opensource.org/licenses/MIT)