A client library for the IPFS API.
$ npm install --save ipfs-api
var ipfsAPI = require('ipfs-api')
// connect to ipfs daemon API server
var ipfs = ipfsAPI('localhost', '5001', {protocol: 'http'}) // leaving out the arguments will default to these values
// or connect with multiaddr
var ipfs = ipfsAPI('/ip4/127.0.0.1/tcp/5001')
// or using options
var ipfs = ipfsAPI({host: 'localhost', port: '5001', procotol: '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.
Make the ipfsapi.min.js available through your server and load it using a normal <script>
tag, this will export the ipfsAPI
constructor on the window
object, such that:
var 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:
var ipfs = window.ipfsAPI()
When using the api from script tag for things that require buffers (ipfs.add
, for example), you will have to use either the exposed ipfs.Buffer
, that works just like a node buffer, or use this browser buffer.
If are using this module in a browser with something like browserify, then you will get an error saying that the origin is not allowed. This would be a CORS ("Cross Origin Resource Sharing") failure. The ipfs server rejects 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\"]"
We classify the API calls by 'core', 'extensions', 'tooling', and 'network', following the same API spec organization available at ipfs/specs
The tests folder also contains great examples that can be used to understand how this client library interacts with the HTTP-API. You can find the tests here: https://github.com/ipfs/js-ipfs-api/tree/master/test/api
node start and stop are not implemented in the API
curl
curl 'http://localhost:5001/api/v0/object/get?arg=QmYEqnfCZp7a39Gxrgyv3qRS4MoCTGjegKV6zroU3Rvr52&stream-channels=true' --compressed
response
{
Links: [{
Name: string,
Hash: string,
Size: number
}, ...],
Data: string
}
Data is base64 encoded.
Add a file (where file is any data) to ipfs returning the hash and name. The name value will only be set if you are actually sending a file. A single or array of files can be used.
usage
ipfs.add(files, function(err, res) {
if(err || !res) return console.error(err)
res.forEach(function(file) {
console.log(file.Hash)
console.log(file.Name)
})
})
files
can be a mixed array of filenames or buffers of data. A single value is
also acceptable.
Example
var files = ["../files/hello.txt", new Buffer("ipfs!")]
var files = "../files/hello.txt"
curl
curl 'http://localhost:5001/api/v0/add?stream-channels=true' \
-H 'content-type: multipart/form-data; boundary=a831rwxi1a3gzaorw1w2z49dlsor' \
-H 'Connection: keep-alive' \
--data-binary $'--a831rwxi1a3gzaorw1w2z49dlsor\r\nContent-Type: application/octet-stream\r\nContent-Disposition: file; name="file"; filename="Hello.txt"\r\n\r\nhello--a831rwxi1a3gzaorw1w2z49dlsor--' --compressed
response
[{
Hash: string,
Name: string
}, ...]
The name value will only be set for actual files.
Retrieve the contents of a single hash, or array of hashes.
usage
ipfs.cat(hashs, function(err, res) {
if(err || !res) return console.error(err)
if(res.readable) {
// Returned as a stream
res.pipe(process.stdout)
} else {
// Returned as a string
console.log(res)
}
})
curl
curl "http://localhost:5001/api/v0/cat?arg=<hash>&stream-channels=true"
response
The response is either a readable stream, or a string.
Get the node structure of a hash. Included in it is a hash and array to links.
Usage
ipfs.ls(hashs, function(err, res) {
if(err || !res) return console.error(err)
res.Objects.forEach(function(node) {
console.log(node.Hash)
console.log("Links [%d]", node.Links.length)
node.Links.forEach(function(link, i) {
console.log("[%d]", i, link)
})
})
})
Curl
curl "http://localhost:5001/api/v0/ls?arg=<hash>&stream-channels=true"
Response
{
Objects: [
{
Hash: string,
Links: [{
Name: string,
Hash: string,
Size: number
}, ...]
},
....
]
}