Skip to content

Commit

Permalink
docs: consolidate and update docs (#3364)
Browse files Browse the repository at this point in the history 
* Consolidates docs under `/docs`
* Adds missing licenses, CoC, READMEs, etc
* Updates docs where information was incorrect
  • Loading branch information
@achingbrain
achingbrain authored Nov 2, 2020
1 parent 396a9d2 commit 933ea01
Showing 1 changed file with 22 additions and 87 deletions.
109 changes: 22 additions & 87 deletions README.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -29,24 +29,15 @@

> A client library for the IPFS HTTP API, implemented in JavaScript. This client library implements the IPFS [Core API](https://github.com/ipfs/js-ipfs/tree/master/docs/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

* Look into the [examples](https://github.com/ipfs/js-ipfs/tree/master/examples) to learn how to spawn an IPFS node in Node.js and in the Browser
* Read the [Core API docs](https://github.com/ipfs/js-ipfs/tree/master/docs/core-api) to see what you can do with an IPFS node
* Visit https://dweb-primer.ipfs.io to learn about IPFS and the concepts that underpin it
* Head over to https://proto.school to take interactive tutorials that cover core IPFS APIs
* Check out https://docs.ipfs.io for tips, how-tos and more

## Lead Maintainer
## Lead Maintainer <!-- omit in toc -->

[Alex Potsides](http://github.com/achingbrain)

## Table of Contents
## Table of Contents <!-- omit in toc -->

- [Getting started](#getting-started)
- [Lead Maintainer](#lead-maintainer)
- [Table of Contents](#table-of-contents)
- [Install](#install)
- [Getting Started](#getting-started)
- [Install](#install)
- [Next Steps](#next-steps)
- [Usage](#usage)
- [API](#api)
- [Additional Options](#additional-options)
Expand All @@ -58,12 +49,9 @@
- [URL source](#url-source)
- [`urlSource(url)`](#urlsourceurl)
- [Example](#example-1)
- [IPLD Formats](#ipld-formats)
- [Running the daemon with the right port](#running-the-daemon-with-the-right-port)
- [Importing the module and usage](#importing-the-module-and-usage)
- [Importing a sub-module and usage](#importing-a-sub-module-and-usage)
- [In a web browser](#in-a-web-browser)
- [CORS](#cors)
- [Custom Headers](#custom-headers)
- [Global Timeouts](#global-timeouts)
- [Development](#development)
Expand All @@ -72,7 +60,11 @@
- [Historical context](#historical-context)
- [License](#license)

## Install
## 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 🐉..

### Install

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

Expand All @@ -82,13 +74,24 @@ npm install --save ipfs-http-client

Both the Current and Active LTS versions of Node.js are supported. Please see [nodejs.org](https://nodejs.org/) for what these currently are.

### Next Steps

* Read the [docs](https://github.com/ipfs/js-ipfs/tree/master/docs)
* Look into the [examples](https://github.com/ipfs/js-ipfs/tree/master/examples) to learn how to spawn an IPFS node in Node.js and in the Browser
* Consult the [Core API docs](https://github.com/ipfs/js-ipfs/tree/master/docs/core-api) to see what you can do with an IPFS node
* Visit https://dweb-primer.ipfs.io to learn about IPFS and the concepts that underpin it
* Head over to https://proto.school to take interactive tutorials that cover core IPFS APIs
* Check out https://docs.ipfs.io for tips, how-tos and more
* See https://blog.ipfs.io for news and more
* Need help? Please ask 'How do I?' questions on https://discuss.ipfs.io

## Usage

### API

[![IPFS Core API Compatible](https://cdn.rawgit.com/ipfs/interface-ipfs-core/master/img/badge.svg)](https://github.com/ipfs/js-ipfs/tree/master/packages/interface-ipfs-core)

> `js-ipfs-http-client` implements the [IPFS Core API](https://github.com/ipfs/js-ipfs/tree/master/docs/core-api) - please follow the previous link to see the the methods available.
> `js-ipfs-http-client` implements the [IPFS Core API](https://github.com/ipfs/js-ipfs/tree/master/docs/core-api) - please follow the previous link to see the methods available.
### Additional Options

Expand All @@ -107,7 +110,6 @@ Call this on your client instance to return an object containing the `host`, `po

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

- [`Buffer`](https://www.npmjs.com/package/buffer)
- [`multiaddr`](https://www.npmjs.com/package/multiaddr)
- [`multibase`](https://www.npmjs.com/package/multibase)
- [`multicodec`](https://www.npmjs.com/package/multicodec)
Expand Down Expand Up @@ -192,53 +194,6 @@ console.log(file)
*/
```

### IPLD Formats

By default an instance of the client supports the following [IPLD formats](https://github.com/ipld/interface-ipld-format), which are enough to do all core IPFS operations:

* [dag-pb](https://github.com/ipld/specs/blob/master/block-layer/codecs/dag-pb.md)
* [dag-cbor](https://github.com/ipld/specs/blob/master/block-layer/codecs/dag-cbor.md)
* [raw](https://github.com/ipld/specs/issues/223)

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

1. Configure the [IPLD layer](https://github.com/ipfs/js-ipfs/blob/master/packages/ipfs/docs/MODULE.md#optionsipld) 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:
```javascript
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:
```javascript
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.
Expand Down Expand Up @@ -273,15 +228,6 @@ const ipfs = ipfsClient({ host: 'localhost', port: '5001', protocol: 'http' })
const ipfs = ipfsClient({ host: '1.1.1.1', port: '80', apiPath: '/ipfs/api/v0' })
```

### Importing a sub-module and usage

```javascript
const bitswap = require('ipfs-http-client/src/bitswap')('/ip4/127.0.0.1/tcp/5001')
const list = await bitswap.wantlist()
// ...
```

### In a web browser

**through Browserify**
Expand Down Expand Up @@ -331,17 +277,6 @@ If you omit the host and port, the client will parse `window.host`, and use this
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:

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

If you are using `js-ipfs`, substitute `ipfs` for `jsipfs` in the commands above.

### 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:
Expand Down

0 comments on commit 933ea01

Please sign in to comment.