From 79892a6e8e938a94a5d7e3d1ea8b6f00715b1d26 Mon Sep 17 00:00:00 2001
From: Victor Bjelkholm <victor@typeform.com>
Date: Tue, 3 Nov 2015 21:25:31 +0100
Subject: [PATCH] Add current work in progress of readme.md and api.md

---
 API.md    | 334 ++++++++++++++++++++++++++++++++++++++++++++++++++++++
 README.md | 241 ++++++++++-----------------------------
 2 files changed, 397 insertions(+), 178 deletions(-)
 create mode 100644 API.md

diff --git a/API.md b/API.md
new file mode 100644
index 000000000..5671482af
--- /dev/null
+++ b/API.md
@@ -0,0 +1,334 @@
+# js-ipfs-api
+
+## API Reference
+
+- [add](#add)
+- [cat](#cat)
+- [ls](#ls)
+- [ID](#id)
+- [version](#version)
+- [commands](#commands)
+- [ping](#ping)
+- [config](#config)
+- [update](#update)
+- [diag](#diag)
+- [block](#block)
+- [object](#object)
+- [swarm](#swarm)
+- [pin](#pin)
+- [gateway](#gateway)
+- [log](#log-1)
+- [name](#name)
+- [dht](#dht)
+
+## add
+`ipfs_client.add(file/files, callback)`
+
+`ipfs_client.add(file/files, options, callback)`
+
+Add a file/many files to IPFS returning the hash and name. The
+name value will only be set if you are actually sending a file.
+
+**Usage**
+
+```javascript
+ipfs_client.add(files, function(err, res) {
+    if(err || !res) return throw new Error(err)
+
+    res.forEach(function(file) {
+        console.log(file);
+    });
+});
+```
+
+`files` can be a mixed array of filenames or buffers of data and also a single value.
+
+```javascript
+var files = ["../files/hello.txt", new Buffer("IPFS!"), 'IPFS!'];
+var files = "../files/hello.txt";
+```
+
+As a second parameter, you can also set options like recursive
+
+`TODO: Add all available options`
+
+```javascript
+ipfs_client.add(files, {recursive: true}, callback)
+```
+
+## cat
+`ipfs_client.cat(hash/hashes, callback)`
+
+`ipfs_client.cat(hash/hashes, options, callback)`
+
+Retrieve the contents of a single, or array of hashes
+
+`TODO: update this example because .cat should only return string OR stream always`
+
+**Usage**
+
+```javascript
+ipfs_client.cat(hashes, function(err, res) {
+    if(err || !res) throw new Error(err)
+
+    if(res.readable) {
+        // Returned as a stream
+        res.pipe(process.stdout);
+    } else {
+        // Returned as a string
+        console.log(res);
+    }
+});
+```
+
+Hashes can be a string containing the hash or an array of strings.
+
+```
+var hashes = "QmahiUEctp3JYevAuS6Uwid4mudd6yD8M6aszpQ5nvVHSt"
+var hashes = [
+  "QmahiUEctp3JYevAuS6Uwid4mudd6yD8M6aszpQ5nvVHSt",
+  "QmWCSGzec5txqWS9o8DVsBMgYNn3pGMrjbwsgwfPuh2DWL"
+]
+```
+
+## ls
+`ipfs_client.ls(hash/hashes, callback)`
+
+`ipfs_client.ls(hash/hashes, options, callback)`
+
+Get the node structure of a hash, included in it is a hash and array to links.
+
+**Usage**
+
+```javascript
+ipfs_client.ls(hashes, 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)
+        })
+    })
+})
+```
+
+## ID
+`ipfs_client.id(callback) // Returns your ID`
+
+`ipfs_client.id(id, callback) // Returns another peers ID`
+
+Prints out information about the specified peer, if no peer is specified, prints out local peers info.
+
+**Usage**
+
+```javascript
+ipfs_client.id(function(err, res) {
+  if(err || !res) throw new Error(err)
+
+  console.log(res);
+  /* =>
+  { ID: 'QmWuZGboBP9fpoFvFZ1H9mEKcor5Uz8vk76eib9ssvCpvw',
+     PublicKey: 'CAASpgIwggEiMA0GCSqGSIb3DQEBAQUAA4IBDwAwggEKAoIBAQCzVZOuuwTPnQhK0Lh1hXGoLRC8+maz158X2NgtJtr8qVnHM/ytO8nDsPaAGl6DxKkueO1zPWWBtHYfnJ0CQb1/l28yuf4FTD8mafTQyAgDLcfMruUAp8rYGgK5lkmpjGE1OUel9Wuib52Bb896aCf97+RSdHDD3kj3fV5RS5yl9+PLG8XtEyXQSIVn0dX/zQAIh2DANWL6bGIcKHJR+AfemCV9v343MwoLeA+ypY5dm+zwPTxwuCxCVQO4UWEMSs0NKr51n+xDeVmGluoyX33YciIBv35tqhrkHdEPeMBcZx4NNdhQkz0ATpkAMTu0+x9bogB9YrLAuTKeRXuAK14PAgMBAAE=',
+     Addresses:
+      [ '/ip6/::1/tcp/4001/ipfs/',
+        '/ip4/127.0.0.1/tcp/4001/ipfs/',
+        '/ip4/192.168.1.129/tcp/4001/ipfs/',
+        '/ip4/37.133.29.50/tcp/4001/ipfs/',
+        '/ip4/37.133.29.50/tcp/41530/ipfs/' ],
+     AgentVersion: 'go-ipfs/0.3.8-dev',
+     ProtocolVersion: 'ipfs/0.1.0' }
+     */
+})
+```
+
+## version
+`ipfs_client.version(callback)`
+
+Returns the current version of the connected daemon.
+
+**Usage**
+
+```javascript
+  ipfs_client.version(function(err, res) {
+    if(err || !res) throw new Error(err)
+    console.log(res)
+    //  ->{ Version: '0.3.10-dev', Commit: '' }
+  })
+```
+
+## commands
+`ipfs_client.commands()`
+
+Lists all available commands (and subcommands).
+
+## ping
+`ipfs_client.ping()`
+
+IPFS ping is a tool to test sending data to other nodes. It finds nodes via the routing system, send pings, wait for pongs, and print out round-trip latency information
+
+## config
+
+IPFS config controls configuration variables.
+
+### get
+`ipfs_client.config.get`
+
+Get a value from a config key
+
+### set
+`ipfs_client.config.set`
+
+Set a value of a config key
+
+### show
+`ipfs_client.config.show`
+
+Show a value from a config key
+
+### replace
+`ipfs_client.config.replace`
+
+Replace a config key with new value
+
+## update
+
+**(Disabled)**
+
+**(IPFS update is disabled until we can deploy the binaries to you over IPFS itself)**
+
+### apply
+`ipfs_client.update.apply`
+
+**(Disabled)**
+
+### check
+`ipfs_client.update.check`
+
+**(Disabled)**
+
+### log
+`ipfs_client.update.log`
+
+**(Disabled)**
+
+## diag
+
+### net
+`ipfs_client.diag.net`
+
+Sends out a message to each node in the network recursively requesting a listing of data about them including number of connected peers and latencies between them.
+
+## block
+
+### get
+`ipfs_client.block.get`
+
+Get a raw IPFS block
+
+### put
+`ipfs_client.block.put`
+
+Stores input as an IPFS block
+
+## object
+
+### get
+`ipfs_client.object.get`
+
+Get and serialize the DAG node named by <key>
+
+### put
+`ipfs_client.object.put`
+
+Stores input as a DAG object, outputs its key
+
+### data
+`ipfs_client.object.data`
+
+Outputs the raw bytes in an IPFS object
+
+### stat
+`ipfs_client.object.stat`
+
+Get stats for the DAG node named by <key>
+
+### links
+`ipfs_client.object.links`
+
+Get stats for the DAG node named by <key>
+
+## swarm
+
+### peers
+`ipfs_client.swarm.peers`
+
+Outputs the links pointed to by the specified object
+
+### connect
+`ipfs_client.swarm.connect`
+
+Open connection to a given address
+
+## pin
+
+### add
+`ipfs_client.pin.add`
+
+Pins objects to local storage
+
+### remove
+`ipfs_client.pin.remove`
+
+Removes (unpin) objects from local storage
+
+### list
+`ipfs_client.pin.list`
+
+Lists all objects currently in local storage
+
+## gateway
+
+`(TODO)`
+
+### enable
+`ipfs_client.gateway.enable`
+### disable
+`ipfs_client.gateway.disable`
+
+## log
+
+### tail
+`ipfs_client.log.tail`
+
+Read the logs
+
+## name
+
+### publish
+`ipfs_client.name.publish`
+
+Publish an object to IPNS
+
+### resolve
+`ipfs_client.name.resolve`
+
+Gets the value currently published at an IPNS name
+
+## dht
+
+### findprovs
+`ipfs_client.dht.findprovs`
+
+Run a 'FindProviders' query through the DHT
+
+### get
+`ipfs_client.dht.get`
+
+Run a 'GetValue' query through the DHT
+
+### put
+`ipfs_client.dht.put`
+
+Run a 'PutValue' query through the DHT
\ No newline at end of file
diff --git a/README.md b/README.md
index e39bb0350..02fc079b9 100644
--- a/README.md
+++ b/README.md
@@ -1,216 +1,101 @@
-IPFS API wrapper library in JavaScript
-======================================
+IPFS API library for JavaScript
+====================================================
 
-[![](https://img.shields.io/badge/made%20by-Protocol%20Labs-blue.svg?style=flat-square)](http://ipn.io) [![](https://img.shields.io/badge/project-IPFS-blue.svg?style=flat-square)](http://ipfs.io/) [![](https://img.shields.io/badge/freejs-%23ipfs-blue.svg?style=flat-square)](http://webchat.freenode.net/?channels=%23ipfs) [![Dependency Status](https://david-dm.org/ipfs/js-ipfs-api.svg?style=flat-square)](https://david-dm.org/ipfs/js-ipfs-api) [![Circle CI](https://circleci.com/gh/ipfs/js-ipfs-api.svg?style=svg)](https://circleci.com/gh/ipfs/js-ipfs-api)
+[![](https://img.shields.io/badge/made%20by-Protocol%20Labs-blue.svg?style=flat-square)](http://ipn.io) [![](https://img.shields.io/badge/project-IPFS-blue.svg?style=flat-square)](http://ipfs.io/) [![](https://img.shields.io/badge/freenode-%23ipfs-blue.svg?style=flat-square)](http://webchat.freenode.net/?channels=%23ipfs) [![Dependency Status](https://david-dm.org/ipfs/node-ipfs-api.svg?style=flat-square)](https://david-dm.org/ipfs/node-ipfs-api)
+[![Circle CI](https://circleci.com/gh/ipfs/node-ipfs-api.svg?style=svg)](https://circleci.com/gh/ipfs/node-ipfs-api)
 
-> A client library for the IPFS API.
+- [Description](#description)
+- [Installation](#installation)
+  - [npm](#npm)
+  - [Browser](#browser)
+- [FAQ](#faq)
+  - [CORS](#cors)
+  - [Buffers in browser version](#buffers-in-browser-version)
+- [Contributing](#contributing)
+- [License](#license)
 
-# Usage
+# Description
 
-## Installing the module
+# Installation
 
-### In Node.js Through npm
+## npm
 
 ```bash
-$ npm install --save ipfs-api
+npm install --save ipfs-api
 ```
 
+Then you will be able to import the library with `require`.
+
 ```javascript
-var ipfsAPI = require('ipfs-api')
+var ipfsAPI = require('ipfs-api');
 
 // connect to ipfs daemon API server
-var ipfs = ipfsAPI('localhost', '5001') // leaving out the arguments will default to these values
+var ipfs_client = ipfsAPI('localhost', '5001'); // leaving out the arguments will default to these values
 ```
 
-### In the Browser through browserify
-
-Same as in Node.js, you just have to [browserify](https://github.com/substack/js-browserify) the code before serving it. See the browserify repo for how to do that.
-
-### In the Browser through `<script>` tag
+## Browser
+Make the [ipfsapi.min.js](/dist/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.
 
-Make the [ipfsapi.min.js](/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')
+```javascript
+// connect to ipfs daemon API server
+var ipfs_client = window.ipfsAPI('localhost', '5001') // leaving out the arguments will default to these values
 ```
 
-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:
+# Usage
 
+```javascript
+ipfs_client.add(new Buffer('Hello World!'), function(err, resAdd) {
+  if(err) throw err
+  var hash = resAdd[0].Hash
+  ipfs_client.cat(hash, function(err, resCat) {
+    if(err) throw err
+    resCat.on('data', function(chunk) {
+    	console.log(chunk.toString())
+    	// => "Hello World!"
+    })
+  })
+})
 ```
-var ipfs = window.ipfsAPI()
-```
-
-#### Gotchas
 
-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](https://github.com/feross/buffer).
+For more examples and reference, check out the [API Reference](API.md)
 
+# FAQ
 ## CORS
 
-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 exporting `API_ORIGIN` and restarting the daemon, like:
+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 exporting API_ORIGIN and restarting the daemon, like:
 
 ```bash
 export API_ORIGIN="http://localhost:8080"
 ipfs daemon
 ```
 
-## API
-
-### Level 1 Commands
-Level 1 commands are simple commands
-
-#### add
-
-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**
-```javascript
-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
-```js
-var files = ["../files/hello.txt", new Buffer("ipfs!")]
-var files = "../files/hello.txt"
-```
-
-**Curl**
-```sh
-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**
-```js
-[{
-    Hash: string,
-    Name: string
-}, ...]
-```
-*The name value will only be set for actual files.*
-
+## Buffers in browser version
 
+When using the api from the browser 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](https://github.com/feross/buffer)
 
-#### cat
 
-Retrieve the contents of a single hash, or array of hashes.
+# Contributing
 
-**Usage**
-```javascript
-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**
-```sh
-curl "http://localhost:5001/api/v0/cat?arg=<hash>&stream-channels=true"
-```
-
-**Response**
+# License
 
-The response is either a readable stream, or a string.
+The MIT License (MIT)
 
-#### ls
-Get the node structure of a hash. Included in it is a hash and array to links.
-
-**Usage**
-```javascript
-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**
-```sh
-curl "http://localhost:5001/api/v0/ls?arg=<hash>&stream-channels=true"
-```
-
-**Response**
-```js
-{
-    Objects: [
-        { 
-            Hash: string,
-            Links: [{
-                Name: string,
-                Hash: string,
-                Size: number
-            }, ...]
-        },
-        ....
-    ]
-}
-```
-
-
-**version**
-
-**commands**
-
-### Level 2 Commands
-Level 2 commands are simply named spaced wrapped commands
-
-#### Config
-
-#### Update
-
-#### Mount
-
-#### Diag
-
-#### Block
-
-#### Object
-
-**Curl**
-```sh
-curl 'http://localhost:5001/api/v0/object/get?arg=QmYEqnfCZp7a39Gxrgyv3qRS4MoCTGjegKV6zroU3Rvr52&stream-channels=true' --compressed
-```
-
-**Response**
-```js
-{
-    Links: [{
-        Name: string,
-        Hash: string,
-        Size: number
-    }, ...],
-    Data: string
-}
-```
-*Data is base64 encoded.*
+Copyright (c) 2015 - Protocol Labs
 
-#### Swarm
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
 
-#### Pin
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
 
-#### Gateway
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.