ipfs-http-client
A client library for the IPFS HTTP API
Last updated 8 days ago by achingbrain .
(Apache-2.0 OR MIT) · Repository · Bugs · Original npm · Tarball · package.json
$ cnpm install ipfs-http-client 
SYNC missed versions from official npm registry.

IPFS http client lib logo

The JavaScript HTTP client library for IPFS implementations.



A client library for the IPFS HTTP API, implemented in JavaScript. This client library implements the IPFS Core API enabling applications to change between an embedded 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.

Getting started

Lead Maintainer

Alex Potsides

Table of Contents

Install

This module uses node.js, and can be installed through npm:

npm install --save ipfs-http-client

Both the Current and Active LTS versions of Node.js are supported. Please see nodejs.org for what these currently are.

Usage

API

IPFS Core API Compatible

js-ipfs-http-client implements the IPFS Core API - please follow the previous link to see the the methods available.

Additional Options

All core API methods take additional options specific to the HTTP API:

  • headers - An object or Headers instance that can be used to set custom HTTP headers. Note that this option can also be configured globally via the constructor options.
  • searchParams - An object or URLSearchParams instance that can be used to add additional query parameters to the query string sent with each request.
  • ipld.formats - An array of additional IPLD formats to support
  • ipld.loadFormat an async function that takes the name of an IPLD format as a string and should return the implementation of that codec

Instance Utils

  • ipfs.getEndpointConfig()

Call this on your client instance to return an object containing the host, port, protocol and api-path.

Static Types and Utils

Aside from the default export, ipfs-http-client exports various types and utilities that are included in the bundle:

These can be accessed like this, for example:

const { CID } = require('ipfs-http-client')
// ...or from an es-module:
import { CID } from 'ipfs-http-client'

Glob source

A utility to allow files on the file system to be easily added to IPFS.

globSource(path, [options])
  • path: A path to a single file or directory to glob from
  • options: Optional options
  • options.recursive: If path is a directory, use option { recursive: true } to add the directory and all its sub-directories.
  • options.ignore: To exclude file globs from the directory, use option { ignore: ['ignore/this/folder/**', 'and/this/file'] }.
  • options.hidden: Hidden/dot files (files or folders starting with a ., for example, .git/) are not included by default. To add them, use the option { hidden: true }.

Returns an async iterable that yields { path, content } objects suitable for passing to ipfs.add.

Example
const IpfsHttpClient = require('ipfs-http-client')
const { globSource } = IpfsHttpClient
const ipfs = IpfsHttpClient()

for await (const file of ipfs.add(globSource('./docs', { recursive: true }))) {
  console.log(file)
}
/*
{
  path: 'docs/assets/anchor.js',
  cid: CID('QmVHxRocoWgUChLEvfEyDuuD6qJ4PhdDL2dTLcpUy3dSC2'),
  size: 15347
}
{
  path: 'docs/assets/bass-addons.css',
  cid: CID('QmPiLWKd6yseMWDTgHegb8T7wVS7zWGYgyvfj7dGNt2viQ'),
  size: 232
}
...
*/

URL source

A utility to allow content from the internet to be easily added to IPFS.

urlSource(url)
  • url: A string URL or URL instance to send HTTP GET request to

Returns an async iterable that yields { path, content } objects suitable for passing to ipfs.add.

Example
const IpfsHttpClient = require('ipfs-http-client')
const { urlSource } = IpfsHttpClient
const ipfs = IpfsHttpClient()

for await (const file of ipfs.add(urlSource('https://ipfs.io/images/ipfs-logo.svg'))) {
  console.log(file)
}
/*
{
  path: 'ipfs-logo.svg',
  cid: CID('QmTqZhR6f7jzdhLgPArDPnsbZpvvgxzCZycXK7ywkLxSyU'),
  size: 3243
}
*/

IPLD Formats

By default an instance of the client supports the following IPLD formats, which are enough to do all core IPFS operations:

If your application requires support for extra codecs, you can configure them as follows:

  1. Configure the IPLD layer of your IPFS daemon to support the codec. This step is necessary so the node knows how to prepare data received over HTTP to be passed to IPLD for serialization:
    const ipfs = require('ipfs')
    
    const node = await ipfs({
      ipld: {
        // either specify them as part of the `formats` list
        formats: [
          require('my-format')
        ],
    
        // or supply a function to load them dynamically
        loadFormat: async (format) => {
          return require(format)
        }
      }
    })
    
  2. Configure your IPFS HTTP API Client to support the codec. This is necessary so that the client can send the data to the IPFS node over HTTP:
    const ipfsHttpClient = require('ipfs-http-client')
    
    const client = ipfsHttpClient({
      url: 'http://127.0.0.1:5002',
      ipld: {
        // either specify them as part of the `formats` list
        formats: [
          require('my-format')
        ],
    
        // or supply a function to load them dynamically
        loadFormat: async (format) => {
          return require(format)
        }
      }
    })
    

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

Importing the module and usage

const ipfsClient = require('ipfs-http-client')

// connect to ipfs daemon API server
const ipfs = ipfsClient('http://localhost:5001') // (the default in Node.js)

// or connect with multiaddr
const ipfs = ipfsClient('/ip4/127.0.0.1/tcp/5001')

// or using options
const ipfs = ipfsClient({ host: 'localhost', port: '5001', protocol: 'http' })

// or specifying a specific API path
const ipfs = ipfsClient({ host: '1.1.1.1', port: '80', apiPath: '/ipfs/api/v0' })

Importing a sub-module and usage

const bitswap = require('ipfs-http-client/src/bitswap')('/ip4/127.0.0.1/tcp/5001')

const list = await bitswap.wantlist(key)
// ...

In a web browser

through Browserify

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.

through webpack

See the example in the examples folder to get an idea on how to use js-ipfs-http-client with webpack.

from CDN

Instead of a local installation (and browserification) you may request a remote copy of IPFS API from jsDelivr.

To always request the latest version, use one of the following examples:

<!-- loading the minified version using jsDelivr -->
<script src="https://cdn.jsdelivr.net/npm/ipfs-http-client/dist/index.min.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. Learn more also at the jsdelivr website
  • set the CORS settings attribute to make anonymous requests to CDN

Example:

<script src="https://www.jsdelivr.com/package/npm/ipfs-http-client"
integrity="sha384-5bXRcW9kyxxnSMbOoHzraqa7Z0PQWIao+cgeg327zit1hz5LZCEbIMx/LWKPReuB"
crossorigin="anonymous"></script>

CDN-based IPFS API provides the IpfsHttpClient constructor as a method of the global window object. Example:

const ipfs = window.IpfsHttpClient({ host: 'localhost', port: 5001 })

If you omit the host and port, the client 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:

const ipfs = window.IpfsHttpClient()

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 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 = ipfsClient({
  host: 'localhost',
  port: 5001,
  protocol: 'http',
  headers: {
    authorization: 'Bearer ' + TOKEN
  }
})

Global Timeouts

To set a global timeout for all requests pass a value for the timeout option:

// Timeout after 10 seconds
const ipfs = ipfsClient({ timeout: 10000 })
// Timeout after 2 minutes
const ipfs = ipfsClient({ timeout: '2m' })
// see https://www.npmjs.com/package/parse-duration for valid string values

Development

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

The js-ipfs-http-client 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!
  • Perform code reviews. More eyes will help a) speed the project along b) ensure quality and c) reduce possible future bugs.
  • Add tests. There can never be enough tests. Note that interface tests exist inside interface-ipfs-core.

Want to hack on IPFS?

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

FOSSA Status

Current Tags

  • 44.3.0                                ...           latest (8 days ago)
  • 44.3.1-rc.7                                ...           next (an hour ago)

93 Versions

  • 44.3.1-rc.7                                ...           an hour ago
  • 44.3.1-rc.6                                ...           5 hours ago
  • 44.3.1-rc.5                                ...           6 hours ago
  • 44.3.1-rc.3                                ...           a day ago
  • 44.3.1-rc.2                                ...           7 days ago
  • 44.3.0                                ...           8 days ago
  • 44.2.1-rc.32                                ...           9 days ago
  • 44.2.1-rc.11                                ...           16 days ago
  • 44.2.1-rc.2                                ...           24 days ago
  • 44.2.0                                ...           a month ago
  • 44.1.2-rc.2                                ...           a month ago
  • 44.1.1                                ...           a month ago
  • 44.1.1-rc.8                                ...           a month ago
  • 44.1.1-rc.7                                ...           a month ago
  • 44.1.0                                ...           a month ago
  • 44.0.4-rc.3                                ...           2 months ago
  • 44.0.3                                ...           2 months ago
  • 44.0.2                                ...           2 months ago
  • 44.0.1                                ...           2 months ago
  • 44.0.0                                ...           3 months ago
  • 43.0.2-rc.5                                ...           3 months ago
  • 43.0.2-rc.4                                ...           3 months ago
  • 43.0.1                                ...           3 months ago
  • 43.0.0                                ...           3 months ago
  • 42.0.1-rc.5619                                ...           3 months ago
  • 42.0.1-rc.5616                                ...           3 months ago
  • 42.0.1-rc.5598                                ...           3 months ago
  • 42.0.1-rc.49                                ...           4 months ago
  • 42.0.1-rc.55                                ...           4 months ago
  • 42.0.1-rc.74                                ...           4 months ago
  • 42.0.1-rc.91                                ...           4 months ago
  • 42.0.1-rc.115                                ...           4 months ago
  • 42.0.1-rc.145                                ...           4 months ago
  • 42.0.1-rc.151                                ...           4 months ago
  • 42.0.0                                ...           5 months ago
  • 42.0.0-pre.2                                ...           5 months ago
  • 42.0.0-pre.1                                ...           5 months ago
  • 42.0.0-pre.0                                ...           5 months ago
  • 41.0.1                                ...           5 months ago
  • 41.0.0                                ...           6 months ago
  • 40.2.1                                ...           6 months ago
  • 40.2.0                                ...           6 months ago
  • 40.1.0                                ...           7 months ago
  • 40.0.1                                ...           7 months ago
  • 40.0.0                                ...           7 months ago
  • 39.0.2                                ...           8 months ago
  • 38.2.1                                ...           8 months ago
  • 39.0.1                                ...           8 months ago
  • 39.0.0                                ...           9 months ago
  • 38.2.0                                ...           9 months ago
  • 38.1.0                                ...           9 months ago
  • 38.0.1                                ...           9 months ago
  • 38.0.0                                ...           9 months ago
  • 37.0.3                                ...           9 months ago
  • 37.0.2                                ...           9 months ago
  • 37.0.1                                ...           9 months ago
  • 37.0.0                                ...           9 months ago
  • 36.1.0                                ...           9 months ago
  • 35.1.1                                ...           10 months ago
  • 36.0.0                                ...           10 months ago
  • 35.1.0                                ...           10 months ago
  • 35.0.0                                ...           10 months ago
  • 34.0.0                                ...           10 months ago
  • 33.1.1                                ...           a year ago
  • 33.1.0                                ...           a year ago
  • 33.0.2                                ...           a year ago
  • 33.0.1                                ...           a year ago
  • 33.0.0                                ...           a year ago
  • 32.0.1                                ...           a year ago
  • 32.0.0                                ...           a year ago
  • 31.1.0                                ...           a year ago
  • 31.0.2                                ...           a year ago
  • 31.0.1                                ...           a year ago
  • 31.0.0                                ...           a year ago
  • 30.1.4                                ...           a year ago
  • 30.1.3                                ...           a year ago
  • 30.1.2                                ...           a year ago
  • 30.1.1                                ...           a year ago
  • 30.1.0                                ...           a year ago
  • 30.0.0                                ...           a year ago
  • 29.1.1                                ...           a year ago
  • 29.1.0                                ...           a year ago
  • 29.0.1                                ...           a year ago
  • 29.0.0                                ...           a year ago
  • 28.1.2                                ...           a year ago
  • 28.1.1                                ...           a year ago
  • 28.1.0                                ...           2 years ago
  • 28.0.3                                ...           2 years ago
  • 28.0.2                                ...           2 years ago
  • 28.0.1                                ...           2 years ago
  • 28.0.0                                ...           2 years ago
  • 27.1.0                                ...           2 years ago
  • 27.0.0                                ...           2 years ago
Maintainers (1)
Downloads
Today 133
This Week 581
This Month 546
Last Day 275
Last Week 659
Last Month 1,641
Dependencies (27)
Dev Dependencies (9)
Dependents (185)

Copyright 2014 - 2016 © taobao.org |