|
| 1 | +# API <!-- omit in toc --> |
| 2 | + |
| 3 | +`ipfs` can run as part of your program (an in-process node) or as a standalone daemon process that can be communicated with via an HTTP RPC API using the [`ipfs-http-client`](../packages/ipfs-http-api) module. |
| 4 | + |
| 5 | +The http client module can be used to control either a `go-ipfs` or a `js-ipfs` daemon, though the amount of the API implemented in each language varies. |
| 6 | + |
| 7 | +Whether accessed directly or over HTTP, both methods support the full [Core API](#core-api). In addition other methods are available to construct instances of each module, etc. |
| 8 | + |
| 9 | +## Table of Contents <!-- omit in toc --> |
| 10 | + |
| 11 | +- [Core API](#core-api) |
| 12 | +- [ipfs module](#ipfs-module) |
| 13 | +- [ipfs-http-client module](#ipfs-http-client-module) |
| 14 | + - [Additional Options](#additional-options) |
| 15 | + - [Instance Utils](#instance-utils) |
| 16 | + - [Static Types and Utils](#static-types-and-utils) |
| 17 | + - [Glob source](#glob-source) |
| 18 | + - [`globSource(path, [options])`](#globsourcepath-options) |
| 19 | + - [Example](#example) |
| 20 | + - [URL source](#url-source) |
| 21 | + - [`urlSource(url)`](#urlsourceurl) |
| 22 | + - [Example](#example-1) |
| 23 | + |
| 24 | +## Core API |
| 25 | + |
| 26 | +The Core API defines the set of operations that are possible to do with an IPFS node. |
| 27 | + |
| 28 | +It is broken up into the following sections: |
| 29 | + |
| 30 | +* [BITSWAP.md](api/BITSWAP.md) |
| 31 | +* [BLOCK.md](api/BLOCK.md) |
| 32 | +* [BOOTSTRAP.md](api/BOOTSTRAP.md) |
| 33 | +* [CONFIG.md]([api/CONFIG.md) |
| 34 | +* [DAG.md](api/DAG.md) |
| 35 | +* [DHT.md](api/DHT.md) |
| 36 | +* [FILES.md](api/FILES.md) |
| 37 | +* [KEY.md](api/KEY.md) |
| 38 | +* [MISCELLANEOUS.md](api/MISCELLANEOUS.md) |
| 39 | +* [NAME.md](api/NAME.md) |
| 40 | +* [OBJECT.md](api/OBJECT.md) |
| 41 | +* [PIN.md](api/PIN.md) |
| 42 | +* [PUBSUB.md](api/PUBSUB.md) |
| 43 | +* [REFS.md](api/REFS.md) |
| 44 | +* [STATS.md](api/STATS.md) |
| 45 | +* [SWARM.md](api/SWARM.md) |
| 46 | + |
| 47 | +## ipfs module |
| 48 | + |
| 49 | +See [IPFS.md](./IPFS.md) for constructor details and instance methods not part of the Core API. |
| 50 | + |
| 51 | +## ipfs-http-client module |
| 52 | + |
| 53 | +These are functions not in the [Core API](#core-api) but that are specific to [`ipfs-http-client`](../packages/ipfs-http-client). |
| 54 | + |
| 55 | +### Additional Options |
| 56 | + |
| 57 | +All core API methods take _additional_ `options` specific to the HTTP API: |
| 58 | + |
| 59 | +* `headers` - An object or [Headers](https://developer.mozilla.org/en-US/docs/Web/API/Headers) instance that can be used to set custom HTTP headers. Note that this option can also be [configured globally](#custom-headers) via the constructor options. |
| 60 | +* `signal` - An [`AbortSignal`](https://developer.mozilla.org/en-US/docs/Web/API/AbortSignal) that can be used to abort the request on demand. |
| 61 | +* `timeout` - A number or string specifying a timeout for the request. If the timeout is reached before data is received a [`TimeoutError`](https://github.com/sindresorhus/ky/blob/2f37c3f999efb36db9108893b8b3d4b3a7f5ec45/index.js#L127-L132) is thrown. If a number is specified it is interpreted as milliseconds, if a string is passed, it is intepreted according to [`parse-duration`](https://www.npmjs.com/package/parse-duration). Note that this option can also be [configured globally](#global-timeouts) via the constructor options. |
| 62 | +* `searchParams` - An object or [`URLSearchParams`](https://developer.mozilla.org/en-US/docs/Web/API/URLSearchParams) instance that can be used to add additional query parameters to the query string sent with each request. |
| 63 | + |
| 64 | +### Instance Utils |
| 65 | + |
| 66 | +- `ipfs.getEndpointConfig()` |
| 67 | + |
| 68 | +Call this on your client instance to return an object containing the `host`, `port`, `protocol` and `api-path`. |
| 69 | + |
| 70 | +### Static Types and Utils |
| 71 | + |
| 72 | +Aside from the default export, `ipfs-http-client` exports various types and utilities that are included in the bundle: |
| 73 | + |
| 74 | +- [`Buffer`](https://www.npmjs.com/package/buffer) |
| 75 | +- [`multiaddr`](https://www.npmjs.com/package/multiaddr) |
| 76 | +- [`multibase`](https://www.npmjs.com/package/multibase) |
| 77 | +- [`multicodec`](https://www.npmjs.com/package/multicodec) |
| 78 | +- [`multihash`](https://www.npmjs.com/package/multihashes) |
| 79 | +- [`CID`](https://www.npmjs.com/package/cids) |
| 80 | +- [`globSource`](https://github.com/ipfs/js-ipfs-utils/blob/master/src/files/glob-source.js) (not available in the browser) |
| 81 | +- [`urlSource`](https://github.com/ipfs/js-ipfs-utils/blob/master/src/files/url-source.js) |
| 82 | + |
| 83 | +These can be accessed like this, for example: |
| 84 | + |
| 85 | +```js |
| 86 | +const { CID } = require('ipfs-http-client') |
| 87 | +// ...or from an es-module: |
| 88 | +import { CID } from 'ipfs-http-client' |
| 89 | +``` |
| 90 | + |
| 91 | +#### Glob source |
| 92 | + |
| 93 | +A utility to allow files on the file system to be easily added to IPFS. |
| 94 | + |
| 95 | +##### `globSource(path, [options])` |
| 96 | + |
| 97 | +- `path`: A path to a single file or directory to glob from |
| 98 | +- `options`: Optional options |
| 99 | +- `options.recursive`: If `path` is a directory, use option `{ recursive: true }` to add the directory and all its sub-directories. |
| 100 | +- `options.ignore`: To exclude file globs from the directory, use option `{ ignore: ['ignore/this/folder/**', 'and/this/file'] }`. |
| 101 | +- `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 }`. |
| 102 | + |
| 103 | +Returns an async iterable that yields `{ path, content }` objects suitable for passing to `ipfs.add`. |
| 104 | + |
| 105 | +##### Example |
| 106 | + |
| 107 | +```js |
| 108 | +const IpfsHttpClient = require('ipfs-http-client') |
| 109 | +const { globSource } = IpfsHttpClient |
| 110 | +const ipfs = IpfsHttpClient() |
| 111 | + |
| 112 | +for await (const file of ipfs.add(globSource('./docs', { recursive: true }))) { |
| 113 | + console.log(file) |
| 114 | +} |
| 115 | +/* |
| 116 | +{ |
| 117 | + path: 'docs/assets/anchor.js', |
| 118 | + cid: CID('QmVHxRocoWgUChLEvfEyDuuD6qJ4PhdDL2dTLcpUy3dSC2'), |
| 119 | + size: 15347 |
| 120 | +} |
| 121 | +{ |
| 122 | + path: 'docs/assets/bass-addons.css', |
| 123 | + cid: CID('QmPiLWKd6yseMWDTgHegb8T7wVS7zWGYgyvfj7dGNt2viQ'), |
| 124 | + size: 232 |
| 125 | +} |
| 126 | +... |
| 127 | +*/ |
| 128 | +``` |
| 129 | + |
| 130 | +#### URL source |
| 131 | + |
| 132 | +A utility to allow content from the internet to be easily added to IPFS. |
| 133 | + |
| 134 | +##### `urlSource(url)` |
| 135 | + |
| 136 | +- `url`: A string URL or [`URL`](https://developer.mozilla.org/en-US/docs/Web/API/URL) instance to send HTTP GET request to |
| 137 | + |
| 138 | +Returns an async iterable that yields `{ path, content }` objects suitable for passing to `ipfs.add`. |
| 139 | + |
| 140 | +##### Example |
| 141 | + |
| 142 | +```js |
| 143 | +const IpfsHttpClient = require('ipfs-http-client') |
| 144 | +const { urlSource } = IpfsHttpClient |
| 145 | +const ipfs = IpfsHttpClient() |
| 146 | + |
| 147 | +for await (const file of ipfs.add(urlSource('https://ipfs.io/images/ipfs-logo.svg'))) { |
| 148 | + console.log(file) |
| 149 | +} |
| 150 | +/* |
| 151 | +{ |
| 152 | + path: 'ipfs-logo.svg', |
| 153 | + cid: CID('QmTqZhR6f7jzdhLgPArDPnsbZpvvgxzCZycXK7ywkLxSyU'), |
| 154 | + size: 3243 |
| 155 | +} |
| 156 | +*/ |
| 157 | +``` |
0 commit comments