⛔️ DEPRECATED: js-IPFS has been superseded by Helia
📚 Learn more about this deprecation or how to migrate
⚠️ If you continue using this repo, please note that security fixes will not be provided
ipfs-http-client
A client library for the IPFS HTTP API exposed by js-ipfs.
Note: The client library for the Kubo RPC API has moved into js-kubo-rpc-client.
Table of contents
Install
$ npm i ipfs-http-client
Browser <script>
tag
Loading this module through a script tag will make it's exports available as IpfsHttpClient
in the global namespace.
<script src="https://unpkg.com/ipfs-http-client/dist/index.min.js"></script>
The JavaScript HTTP RPC API client library for js-ipfs.
Getting Started
We've come a long way, but this project is still in Alpha, lots of development is happening, APIs might change, beware of 🐉..
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.
Next Steps
Usage
create([options])
create an instance of the HTTP API client
Parameters
None
Options
options
can be a String
, a URL
or a Multiaddr
which will be interpreted as the address of the IPFS node we wish to use the API of.
Alternatively it can be an object which may have the following keys:
Name | Type | Default | Description |
---|
url | String or URL or Multiaddr | 'http://localhost:5001/api/v0' | A URL that resolves to a running instance of the IPFS HTTP RPC API |
protocol | String | 'http' | The protocol to used (ignored if url is specified) |
host | String | 'localhost' | The host to used (ignored if url is specified) |
port | number | 5001 | The port to used (ignored if url is specified) |
path | String | 'api/v0' | The path to used (ignored if url is specified) |
agent | http.Agent | http.Agent({ keepAlive: true, maxSockets: 6 }) | An http.Agent used to control client behaviour (node.js only) |
Returns
Type | Description |
---|
Object | An object that conforms to the IPFS Core API |
Example
import { create } from 'ipfs-http-client'
const client = create()
const client = create({ url: "http://127.0.0.1:5002/api/v0" });
const client = create(new URL('http://127.0.0.1:5002'))
const { cid } = await client.add('Hello world!')
API
js-ipfs-http-client
implements the IPFS Core API - please follow the previous link to see 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.
Instance Utils
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')
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, pattern, [options])
path
: A path to a single file or directory to glob frompattern
: A pattern to match files under path
options
: Optional optionsoptions.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
import { create, globSource } from 'ipfs'
const ipfs = await create()
for await (const file of ipfs.addAll(globSource('./docs', '**/*'))) {
console.log(file)
}
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
import { create, urlSource } from 'ipfs-http-client'
const ipfs = create()
const file = await ipfs.add(urlSource('https://ipfs.io/images/ipfs-logo.svg'))
console.log(file)
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.
> ipfs config Addresses.API
/ip4/127.0.0.1/tcp/5001
> ipfs config Addresses.API /ip4/127.0.0.1/tcp/5001
> ipfs daemon
Importing the module and usage
import { create } from 'ipfs-http-client'
const ipfs = create('http://localhost:5001')
const ipfs = create('/ip4/127.0.0.1/tcp/5001')
const ipfs = create({ host: 'localhost', port: '5001', protocol: 'http' })
const ipfs = create({ host: '1.1.1.1', port: '80', apiPath: '/ipfs/api/v0' })
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:
<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()
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 = create({
host: 'localhost',
port: 5001,
protocol: 'http',
headers: {
authorization: 'Bearer ' + TOKEN
}
})
If you wish to send infura headers with each request made by this library, for example, the Authorization header. You can use the config to do so:
const auth =
'Basic ' + Buffer.from(INFURA_ID + ':' + INFURA_SECRET_KEY).toString('base64');
const client = ipfsClient.create({
host: 'ipfs.infura.io',
port: 5001,
protocol: 'https',
headers: {
authorization: auth,
},
});
Global Timeouts
To set a global timeout for all requests pass a value for the timeout
option:
const ipfs = create({ timeout: 10000 })
const ipfs = create({ timeout: '2m' })
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.
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
Licensed under either of
Contribute
Contributions welcome! Please check out the issues.
Also see our contributing document for more information on how we work, and about contributing in general.
Please be aware that all interactions related to this repo are subject to the IPFS Code of Conduct.
Unless you explicitly state otherwise, any contribution intentionally submitted for inclusion in the work by you, as defined in the Apache-2.0 license, shall be dual licensed as above, without any additional terms or conditions.