From 2ec619ebb9dc63351caa25b9b7c34592db9a5af7 Mon Sep 17 00:00:00 2001 From: Richard Littauer Date: Mon, 14 Dec 2015 10:30:30 -0500 Subject: [PATCH 01/37] Added Group add --- apiary.apib | 36 ++++++++++++++++++++++++++++++++++-- 1 file changed, 34 insertions(+), 2 deletions(-) diff --git a/apiary.apib b/apiary.apib index 94de2e0..7f58593 100644 --- a/apiary.apib +++ b/apiary.apib @@ -4,9 +4,41 @@ FORMAT: 1A The API for interacting with IPFS nodes. -# Group add +# Group add [GET /add{?arg,&recursive,quiet,silent,progress,trickle,only-hash,wrap-with-directory,hidden,chunker,pin}] +Add an object to ipfs. -TODO +Adds contents of to ipfs. Use -r to add directories. +Note that directories are added recursively, to form the ipfs +MerkleDAG. A smarter partial add with a staging area (like git) +remains to be implemented. + ++ Parameters + + arg (string, required) - The path to a file to be added to IPFS + + recursive (boolean, optional) - Add directory paths recursively + + quiet (boolean, optional) - Write minimal output + + silent (boolean, optional) - Write no output + + progress (boolean, optional) - Stream progress data + + trickle (boolean, optional) - Use trickle-dag format for dag generation + + only-hash (boolean, optional) - Only chunk and hash - do not write to disk + + wrap-with-directory (boolean, optional) - Wrap files with a directory object + + hidden (boolean, optional) - Include files that are hidden + + chunker (boolean, optional) - chunking algorithm to use + + pin (boolean, optional) - Pin this object when adding. Default true + ++ Response 200 (text/plain) + + + Body + ``` + added QmbFMke1KXqnYyBBWxB74N4c5SBnJMVAiMNRcGu6x1AwQH test + ``` + ++ Response 400 (text/plain) + + + Body + + ``` + File argument 'path' is required + ``` # Group bitswap A set of commands to manipulate the bitswap agent From 4efdaf8b53222ee7db2a9b7510d4ca99e9df7515 Mon Sep 17 00:00:00 2001 From: Richard Littauer Date: Mon, 14 Dec 2015 10:40:46 -0500 Subject: [PATCH 02/37] Added block put --- apiary.apib | 29 +++++++++++++++++++++++++++-- 1 file changed, 27 insertions(+), 2 deletions(-) diff --git a/apiary.apib b/apiary.apib index 7f58593..b6b5934 100644 --- a/apiary.apib +++ b/apiary.apib @@ -81,7 +81,11 @@ Show blocks currently on the wantlist # Group block -A plumbing command used to manipulate raw ipfs blocks. +Manipulate raw IPFS blocks + +`ipfs block` is a plumbing command used to manipulate raw ipfs blocks. +Reads from stdin or writes to stdout, and is a base58 encoded +multihash. ## stat [GET /block/stat?{arg}] Retrieve information on a raw ipfs block. @@ -111,8 +115,29 @@ Store data as a raw ipfs block. ``` ## put [GET /block/put] -TODO +Stores input as an IPFS block + +ipfs block put is a plumbing command for storing raw ipfs blocks. +It reads from stdin, and is a base58 encoded multihash. + ++ Parameters + + arg (string, required) - The path to the data to be stored as an IPFS block + ++ Response 200 (text/plain) + + + Body + ``` + QmdfTbBqBPQ7VNxZEYEj14VmRuZBkqFbiwReogJgS1zR1n + ``` + ++ Response 403 (text/plain) + + + Body + + ``` + 403 - Forbidden + ``` # Group bootstrap Show or edit the list of bootstrap peers. From 99aba1c18468c77277a356d900949af638e1242c Mon Sep 17 00:00:00 2001 From: Richard Littauer Date: Mon, 14 Dec 2015 11:35:19 -0500 Subject: [PATCH 03/37] Added config --- apiary.apib | 107 ++++++++++++++++++++++++++++++++++++++++++++++++++-- 1 file changed, 104 insertions(+), 3 deletions(-) diff --git a/apiary.apib b/apiary.apib index b6b5934..24c10f2 100644 --- a/apiary.apib +++ b/apiary.apib @@ -301,18 +301,119 @@ Lists all available commands (and subcommands) that are available. # Group config +## config [GET /config{?arg1,arg2,&bool,json}] + +ipfs config controls configuration variables. It works +much like 'git config'. The configuration values are stored in a config +file inside your IPFS repository. + +**Examples:** + +Get the value of the 'datastore.path' key: + + `ipfs config datastore.path` + +Set the value of the 'datastore.path' key: + + `ipfs config datastore.path ~/.ipfs/datastore` + ++ Parameters + + arg1: "Addresses.API" (string, required) - The key of the config entry + + arg2 (string, required) - The value to set the config entry to + + bool (boolean, optional) - Set a boolean + + json (boolean, optional) - Parse stringified JSON + ++ Response 200 (application/json) + + + Attributes (object) + + `Key`: "API.HTTPHeaders" (string) + + `Value`: null (string, nullable) + ++ Response 500 (application/json) + + + Attributes (object) + + `Message` (string) + + `Code`: 0 (number) + ## edit [GET /config/edit] +Opens the config file for editing in $EDITOR -+ Response 200 (text/plain) +To use 'ipfs config edit', you must have the $EDITOR environment + variable set to your preferred text editor. -## replace [GET /config/replace] ++ Response 200 (buffer) -+ Response 200 (text/plain) +## replace [GET /config/replace{?arg}] +Replaces the config with + +Make sure to back up the config file first if neccessary, this operation +can't be undone. + ++ Parameters + + + arg (string, required) - The file to use as the new config + ++ Response 200 () ## show [GET /config/show] +Outputs the content of the config file + +**Warning** + +Your private key is stored in the config file, and it will be +included in the output of this command. + Response 200 (text/plain) + + Attributes (object) + + `API` (object) + + `HTTPHeaders`: null (string, nullable) + + `Addresses` (object) + + `API`: "/ip4/127.0.0.1/tcp/5001" (string) + + `Gateway`: "/ip4/127.0.0.1/tcp/8080" (string) + + `Swarm` (array) + - MultiAddr (string) + + `Bootstrap` (array) + - MultiAddr (string) + + `Datastore` (object) + - `GCPeriod`: "" (string) + - `NoSync`: false (boolean) + - `Params`: null (nullable) + - `Path`: "" (string) + - `StorageGCWatermark`: 90 (number) + - `StorageMax`: "10GB" (string) + - `Type`: "" (string) + + `Discovery` (object) + + `MDNS` (object) + - `Enabled`: true (boolean) + - `Interval`: 10 (number) + + `Gateway` (object) + - `HTTPHeaders`: null (nullable) + - `RootRedirect`: "" (string) + - `Writable`: false (boolean) + + `Identity` (object) + - `PeerID`: hash (string) + - `PrivKey`: hash (string) + + `Ipns` (object) + - `RecordLifetime`: "" (string) + - `RepublishPeriod`: "" (string) + - `ResolveCacheSize`: 128 (number) + + `Log` (object) + - `MaxAgeDays`: 0 (number) + - `MaxBackups`: 1 (number) + - `MaxSizeMB`: 250 (number) + + `Mounts` (object) + - `FuseAllowOther`: false (boolean) + - `IPFS`: "/ipfs" (string) + - `IPFS`: "/ipns" (string) + + `SupernodeRouting` (object) + + `Servers` (array) + - MultiAddr (string) + + `Swarm` (object) + - `AddrFilters`: null (nullable) + + `Tour` (object) + - `Last`: "" (string) + # Group daemon # Group dht From e870bf21c1192fd151fd5022c2b45467127e5f75 Mon Sep 17 00:00:00 2001 From: Richard Littauer Date: Mon, 14 Dec 2015 11:42:00 -0500 Subject: [PATCH 04/37] Added ipfs daemon --- apiary.apib | 71 +++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 71 insertions(+) diff --git a/apiary.apib b/apiary.apib index 24c10f2..93631f9 100644 --- a/apiary.apib +++ b/apiary.apib @@ -415,6 +415,77 @@ included in the output of this command. - `Last`: "" (string) # Group daemon +Run a network-connected IPFS node + +`ipfs daemon` runs a persistent IPFS daemon that can serve commands +over the network. Most applications that use IPFS will do so by +communicating with a daemon over the HTTP API. While the daemon is +running, calls to `ipfs` commands will be sent over the network to +the daemon. + +The daemon will start listening on ports on the network, which are +documented in (and can be modified through) `ipfs config Addresses`. +For example, to change the `Gateway` port: + + ipfs config Addresses.Gateway /ip4/127.0.0.1/tcp/8082 + +The API address can be changed the same way: + + ipfs config Addresses.API /ip4/127.0.0.1/tcp/5002 + +Make sure to restart the daemon after changing addresses. + +By default, the gateway is only accessible locally. To expose it to +other computers in the network, use 0.0.0.0 as the ip address: + + ipfs config Addresses.Gateway /ip4/0.0.0.0/tcp/8080 + +Be careful if you expose the API. It is a security risk, as anyone could +control your node remotely. If you need to control the node remotely, +make sure to protect the port as you would other services or database +(firewall, authenticated proxy, etc). + +HTTP Headers + +IPFS supports passing arbitrary headers to the API and Gateway. You can +do this by setting headers on the API.HTTPHeaders and Gateway.HTTPHeaders +keys: + + ipfs config --json API.HTTPHeaders.X-Special-Header '["so special :)"]' + ipfs config --json Gateway.HTTPHeaders.X-Special-Header '["so special :)"]' + +Note that the value of the keys is an _array_ of strings. This is because +headers can have more than one value, and it is convenient to pass through +to other libraries. + +CORS Headers (for API) + +You can setup CORS headers the same way: + + ipfs config --json API.HTTPHeaders.Access-Control-Allow-Origin '["*"]' + ipfs config --json API.HTTPHeaders.Access-Control-Allow-Methods '["PUT", "GET", "POST"]' + ipfs config --json API.HTTPHeaders.Access-Control-Allow-Credentials '["true"]' + + +**Deprecation Notice** + +Previously, IPFS used an environment variable as seen below: + + export API_ORIGIN="http://localhost:8888/" + +This is deprecated. It is still honored in this version, but will be removed in a +future version, along with this notice. Please move to setting the HTTP Headers. + ++ Parameters + + init (boolean, optional) - Initialize IPFS with default settings if not already initialized + + routing (string, optional) - Overrides the routing option (dht, supernode) + + mount (boolean, optional) - Mounts IPFS to the filesystem + + writable (boolean, optional) - Enable writing objects (with POST, PUT and DELETE) + + mount-ipfs (string, optional) - Path to the mountpoint for IPFS (if using --mount) + + mount-ipns (string, optional) - Path to the mountpoint for IPNS (if using --mount) + + unrestricted-api (boolean, optional) - Allow API access to unlisted hashes + + disable-transport-encryption (boolean, optional) - Disable transport encryption (for debugging protocols) + + enable-gc (boolean, optional) - Enable automatic periodic repo garbage collection # Group dht From 438dd5d5956a60e206b407df0ba8195379669cdb Mon Sep 17 00:00:00 2001 From: Richard Littauer Date: Mon, 14 Dec 2015 11:56:28 -0500 Subject: [PATCH 05/37] Added dht --- apiary.apib | 40 +++++++++++++++++++++++++++++++--------- 1 file changed, 31 insertions(+), 9 deletions(-) diff --git a/apiary.apib b/apiary.apib index 93631f9..9b81622 100644 --- a/apiary.apib +++ b/apiary.apib @@ -488,26 +488,48 @@ future version, along with this notice. Please move to setting the HTTP Headers. + enable-gc (boolean, optional) - Enable automatic periodic repo garbage collection # Group dht +Issue commands directly through the DHT -## findpeer [GET /dht/findpeer] +## findpeer [GET /dht/findpeer{?arg,&verbose}] +Run a 'FindPeer' query through the DHT -+ Response 200 (text/plain) ++ Parameters + + arg (string, required) - The peer to search for -## findprovs [GET /dht/findprovs] +## findprovs [GET /dht/findprovs{?arg,&verbose}] +Run a 'FindProviders' query through the DHT -+ Response 200 (text/plain) +FindProviders will return a list of peers who are able to provide the value requested. -## get [GET /dht/get] ++ Parameters + + arg (string, required) - The key to find providers for + + verbose (boolean, optional) - Write extra information -+ Response 200 (text/plain) +## get [GET /dht/get(?arg,&verbose)] +Run a 'GetValue' query through the DHT -## put [GET /dht/put] +GetValue will return the value stored in the dht at the given key. -+ Response 200 (text/plain) ++ Parameters + + arg (string, required) - The key to find providers for + + verbose (boolean, optional) - Write extra information + +## put [GET /dht/put{?arg1,arg2,&verbose}] +Run a 'PutValue' query through the DHT + +PutValue will store the given key value pair in the dht. + ++ Parameters + + arg (string, required) - The key to store the value at + + arg (string, required) - The value to store + + verbose (boolean, optional) - Write extra information ## query [GET /dht/query] +Run a 'findClosestPeers' query through the DHT -+ Response 200 (text/plain) ++ Parameters + + arg (string, required) - The peerID to run the query against + + verbose (boolean, optional) - Write extra information # Group diag Generate diagnostic reports. From 55eaa438a187753f45c0a91ecaf11f16b1cc6dac Mon Sep 17 00:00:00 2001 From: Richard Littauer Date: Mon, 14 Dec 2015 19:44:07 -0500 Subject: [PATCH 06/37] Added ipfs file --- apiary.apib | 52 ++++++++++++++++++++++++++++++++++++++++++++++++++-- 1 file changed, 50 insertions(+), 2 deletions(-) diff --git a/apiary.apib b/apiary.apib index 9b81622..5cb7608 100644 --- a/apiary.apib +++ b/apiary.apib @@ -655,10 +655,58 @@ ipfs.io. TXT "dnslink=/ipfs/QmRzTuh2Lpuz7Gr39stNr6mTFdqAghsZec1JoUnfySUzcy ..." - Path: `/ipfs/QmTgNJEgQaCqRht9KSXNyZsCp2xpHZmBRms28NRMmtcERp` (Multihash) # Group file +Interact with ipfs objects representing Unix filesystems -## ls [GET /file/ls] +'ipfs file' provides a familar interface to filesystems represtented +by IPFS objects that hides IPFS-implementation details like layout +objects (e.g. fanout and chunking). -+ Response 200 (text/plain) +## ls [GET /file/ls{?arg}] +List directory contents for Unix-filesystem object + +Retrieves the object named by and displays the +contents. + +The JSON output contains size information. For files, the child size +is the total size of the file contents. For directories, the child +size is the IPFS link size. + ++ Parameters + + arg (string, required) - The path to the IPFS object(s) to list links from + ++ Response 200 (application/json) + + + Attributes + + `Arguments` (object) - The key is the provided path, the value its hash + + `Objects` (object) + + Key (object) - The key is the hash of the IPFS object(s) + - `Hash` (string) - The hash + - `Size` (number) + - `Type` (string) + - `Links` (nullable) + + + Body + + ``` + { + "Arguments": { + "/ipfs/QmW2WQi7j6c7UgJTarActp7tDNikE4B2qXtFCfLPdsgaTQ/cat.jpg": "Qmd286K6pohQcTKYqnS1YhWrCiS4gz7Xi34sdwMe9USZ7u" + }, + "Objects": { + "Qmd286K6pohQcTKYqnS1YhWrCiS4gz7Xi34sdwMe9USZ7u": { + "Hash": "Qmd286K6pohQcTKYqnS1YhWrCiS4gz7Xi34sdwMe9USZ7u", + "Size": 443230, + "Type": "File", + "Links": null + } + } + } + ``` ++ Response 500 (application/json) + + + Attributes + + `Message` (string) + + `Code` (number) # Group get From f11186d1bf188b28fbe52bd0b0a970adb4d97319 Mon Sep 17 00:00:00 2001 From: Richard Littauer Date: Mon, 14 Dec 2015 19:44:39 -0500 Subject: [PATCH 07/37] Added ipfs get --- apiary.apib | 35 +++++++++++++++++++++++++++++++++++ 1 file changed, 35 insertions(+) diff --git a/apiary.apib b/apiary.apib index 5cb7608..dd373ab 100644 --- a/apiary.apib +++ b/apiary.apib @@ -711,9 +711,44 @@ size is the IPFS link size. # Group get ## get [GET /get] +Download IPFS objects + +Retrieves the object named by and stores the data to disk. + +By default, the output will be stored at ./, but an alternate path +can be specified with '--output=' or '-o='. + +To output a TAR archive instead of unpacked files, use '--archive' or '-a'. + +To compress the output with GZIP compression, use '--compress' or '-C'. You +may also specify the level of compression by specifying '-l=<1-9>'. + ++ Parameters + + arg (string, required) - The path to the IPFS object(s) to tbe outputted + + output (string, optional) - The path where output should be stored + + archive (boolean, optional) - Output a TAR archive + + compress (boolean, optional) - Compress the output with GZIP compression + + compression-level (int, optional) - The level of compression (1-9) + Response 200 (text/plain) + + Headers + + ``` + Content-type: text/plain + Access-Control-Allow-Headers: X-Stream-Output, X-Chunked-Output + Access-Control-Expose-Headers: X-Stream-Output, X-Chunked-Output + Date: Tue, 15 Dec 2015 00:38:02 GMT + Trailer: X-Stream-Error + Transfer-Encoding: chunked, chunked + X-Stream-Output: 1 + ``` + ++ Response 500 (application/json) + + Attributes + + `Message`: "context canceled" (string) + + `Code`: 0 (number) + # Group id ## id [GET /id] From e02fe5e6bd854934e2991ebf59fa0b01e1229453 Mon Sep 17 00:00:00 2001 From: Richard Littauer Date: Mon, 14 Dec 2015 19:47:46 -0500 Subject: [PATCH 08/37] Filled out ipfs id --- apiary.apib | 22 ++++++++++++++++++++++ test | 0 2 files changed, 22 insertions(+) create mode 100644 test diff --git a/apiary.apib b/apiary.apib index dd373ab..597d584 100644 --- a/apiary.apib +++ b/apiary.apib @@ -751,7 +751,23 @@ may also specify the level of compression by specifying '-l=<1-9>'. # Group id +Prints out information about the specified peer, +if no peer is specified, prints out local peers info. + +ipfs id supports the format option for output with the following keys: + : the peers id +: agent version +: protocol version +: public key +: addresses (newline delimited) + ## id [GET /id] +Show IPFS Node ID info + ++ Parameters + + + arg (string, required) - peerID of node to look up + + format (string, optional) - optional output format + Response 200 (application/json) @@ -783,6 +799,12 @@ may also specify the level of compression by specifying '-l=<1-9>'. } ``` ++ Response 400 + + + Attributes + + `Message`: "Invalid peer id" (string) + + `Code`: 1 (number) + # Group log ## level [GET /log/level] diff --git a/test b/test new file mode 100644 index 0000000..e69de29 From b6da282aaec9c726318fa3439e0f389663c06580 Mon Sep 17 00:00:00 2001 From: Richard Littauer Date: Mon, 14 Dec 2015 19:57:09 -0500 Subject: [PATCH 09/37] Added in args to calls --- apiary.apib | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/apiary.apib b/apiary.apib index 597d584..fc607bf 100644 --- a/apiary.apib +++ b/apiary.apib @@ -490,7 +490,7 @@ future version, along with this notice. Please move to setting the HTTP Headers. # Group dht Issue commands directly through the DHT -## findpeer [GET /dht/findpeer{?arg,&verbose}] +## findpeer [GET /dht/findpeer{?arg}] Run a 'FindPeer' query through the DHT + Parameters @@ -520,8 +520,8 @@ Run a 'PutValue' query through the DHT PutValue will store the given key value pair in the dht. + Parameters - + arg (string, required) - The key to store the value at - + arg (string, required) - The value to store + + arg1 (string, required) - The key to store the value at + + arg2 (string, required) - The value to store + verbose (boolean, optional) - Write extra information ## query [GET /dht/query] @@ -710,7 +710,7 @@ size is the IPFS link size. # Group get -## get [GET /get] +## get [GET /get{?arg,&output,archive,compress,compression-level}] Download IPFS objects Retrieves the object named by and stores the data to disk. @@ -761,7 +761,7 @@ ipfs id supports the format option for output with the following keys: : public key : addresses (newline delimited) -## id [GET /id] +## id [GET /id{?arg,&format}] Show IPFS Node ID info + Parameters From 99b4397df3dc534e78e9d108adc8c2e4c5b9ee9f Mon Sep 17 00:00:00 2001 From: Richard Littauer Date: Mon, 14 Dec 2015 19:57:16 -0500 Subject: [PATCH 10/37] Added ipfs log --- apiary.apib | 18 +++++++++++++++++- 1 file changed, 17 insertions(+), 1 deletion(-) diff --git a/apiary.apib b/apiary.apib index fc607bf..9901f3d 100644 --- a/apiary.apib +++ b/apiary.apib @@ -806,12 +806,28 @@ Show IPFS Node ID info + `Code`: 1 (number) # Group log +`ipfs log` contains utility commands to affect or read the logging +output of a running daemon. -## level [GET /log/level] +## level [GET /log/level{?arg1,arg2}] +`ipfs log level` is a utility command used to change the logging +output of a running daemon. + ++ Parameters + + arg1 (string) - the subsystem logging identifier. Use 'all' for all subsystems. + + arg2 (enum[string]) + + Members + + debug + + info + + warning + + error + + fatal + + panic + Response 200 (text/plain) ## tail [GET /log/tail] +'ipfs log tail' is a utility command used to read log output as it is written. + Response 200 (text/plain) From 51b7ec232dee3e5ac19e774f3a92d0c644a85017 Mon Sep 17 00:00:00 2001 From: Richard Littauer Date: Mon, 14 Dec 2015 20:57:47 -0500 Subject: [PATCH 11/37] Added ipfs ls --- apiary.apib | 50 ++++++++++++++++++++++++++++++++++++++++++++++++-- 1 file changed, 48 insertions(+), 2 deletions(-) diff --git a/apiary.apib b/apiary.apib index 9901f3d..a70e797 100644 --- a/apiary.apib +++ b/apiary.apib @@ -832,10 +832,56 @@ output of a running daemon. + Response 200 (text/plain) # Group ls +List links from an object. -## ls [GET /ls] +## ls [GET /ls{?arg,&headers}] +Retrieves the object named by and displays the links +it contains, with the following format: -+ Response 200 (text/plain) + + ++ Parameters + + arg (string, required) - The path to the IPFS object(s) to list links from + + headers (boolean, optional) - Print table headers (Hash, Name, Size) + ++ Response 200 (application/json) + + + Attributes + + `Objects` (array) + + (object) + - `Hash`: "/ipfs/QmW2WQi7j6c7UgJTarActp7tDNikE4B2qXtFCfLPdsgaTQ/cat.jpg" (string) + + `Links` (array) + + (object) + - `Name`: "" (string) + - `Hash`: "QmPEKipMh6LsXzvtLxunSPP7ZsBM8y9xQ2SQQwBXy5UY6e" (string) + - `Size`: 262158 (number) + - `Type`: 2 (number) + + + Body + + ``` + { + "Objects": [ + { + "Hash": "/ipfs/QmW2WQi7j6c7UgJTarActp7tDNikE4B2qXtFCfLPdsgaTQ/cat.jpg", + "Links": [ + { + "Name": "", + "Hash": "QmPEKipMh6LsXzvtLxunSPP7ZsBM8y9xQ2SQQwBXy5UY6e", + "Size": 262158, + "Type": 2 + }, + { + "Name": "", + "Hash": "QmT8onRUfPgvkoPMdMvCHPYxh98iKCfFkBYM1ufYpnkHJn", + "Size": 181100, + "Type": 2 + } + ] + } + ] + } + ``` # Group mount Mount ipfs at a read-only mountpoint on the OS (default: /ipfs and /ipns). From 8f5337a01b0b31303154c6cf92ff2a6bb3a4c338 Mon Sep 17 00:00:00 2001 From: Richard Littauer Date: Mon, 14 Dec 2015 21:00:57 -0500 Subject: [PATCH 12/37] Added content to mount --- apiary.apib | 6 ++++++ 1 file changed, 6 insertions(+) diff --git a/apiary.apib b/apiary.apib index a70e797..43d0f15 100644 --- a/apiary.apib +++ b/apiary.apib @@ -884,10 +884,16 @@ it contains, with the following format: ``` # Group mount +Mounts IPFS to the filesystem (read-only) + Mount ipfs at a read-only mountpoint on the OS (default: /ipfs and /ipns). All ipfs objects will be accessible under that directory. Note that the root will not be listable, as it is virtual. Access known paths directly. ++ Parameters + + ipfs-path (string, optional) - The path where IPFS should be mounted + + ipns-path (string, optional) - The path where IPNS should be mounted + + Response 200 (application/json) # Group name From 40899559985f5970ca7fcccf19d829891a4c7b90 Mon Sep 17 00:00:00 2001 From: Richard Littauer Date: Mon, 14 Dec 2015 21:11:25 -0500 Subject: [PATCH 13/37] Added ipfs name as much as possible --- apiary.apib | 35 +++++++++++++++++++++++++++++++++-- 1 file changed, 33 insertions(+), 2 deletions(-) diff --git a/apiary.apib b/apiary.apib index 43d0f15..9be795f 100644 --- a/apiary.apib +++ b/apiary.apib @@ -897,15 +897,46 @@ root will not be listable, as it is virtual. Access known paths directly. + Response 200 (application/json) # Group name +IPFS namespace (IPNS) tool -## publish [GET /name/publish] +IPNS is a PKI namespace, where names are the hashes of public keys, and +the private key enables publishing new (signed) values. In publish, the +default value of is your own identity public key. -+ Response 200 (text/plain) +## publish [GET /name/publish{?arg,&resolve,lifetime,ttl}] +Publish an object to IPNS + ++ Parameters + + arg (string, required) - IPFS path of the obejct to be published + + resolve (boolean, optional) - Resolve given path before publishing + + Default: `true` + + lifetime (string, optional) - time duration that the record will be valid for + + Default: `24hrs` + + ttl (string, optional) - time duration this record should be cached for (caution: experimental) + + ++ Response 200 (application/json) + + + Attributes + + `Name` (string) - IPFS hash + + `Value` (string) - IPFS path ## resolve [GET /name/resolve] +Gets the value currently published at an IPNS name + ++ Parameters + + arg (string, required) - The IPNS name to resolve. Defaults to your node's peerID. + + recursive (boolean, optional) - Resolve until the result is not an IPNS name + + nocache (boolean, optional) - Do not used cached entries + Response 200 (text/plain) ++ Response 500 + + + Attributes + + `Message`: "could not resolve name" (string) + + `Code`: 0 (number) + # Group object Interact with ipfs objects. From 38042124bdf6e23847f31baf8d91dbd4515f98c5 Mon Sep 17 00:00:00 2001 From: Richard Littauer Date: Mon, 14 Dec 2015 22:13:31 -0500 Subject: [PATCH 14/37] Added ipfs object This one, in particular, is not great, but this should be a good start. There's a few things in the `ipfs object` docs that are inconsistent; for instance, I'm not sure that and aren't options. The "--encoding" flag is mentioned several times, but never specified as an option, unless it is in `put`, where it has the name `inputenc`, which I think does something different. The formatting is also a bit inconsistent - tick marks given here but not there, and so on. I think I'll need to comb over this in more detail later. For now, here's a stub. Better to have something than nothing. --- apiary.apib | 115 ++++++++++++++++++++++++++++++++++++++++++++++++---- test | 0 2 files changed, 107 insertions(+), 8 deletions(-) delete mode 100644 test diff --git a/apiary.apib b/apiary.apib index 9be795f..ccc17ad 100644 --- a/apiary.apib +++ b/apiary.apib @@ -940,34 +940,133 @@ Gets the value currently published at an IPNS name # Group object Interact with ipfs objects. -## data [GET /object/data] +`ipfs object` is a plumbing command used to manipulate DAG objects +directly. -+ Response 200 (text/plain) +## data [GET /object/data{?arg}] +Outputs the raw bytes in an IPFS object + +`ipfs object data` is a plumbing command for retreiving the raw bytes stored in +a DAG node. It outputs to stdout, and is a base58 encoded +multihash. -## get [GET /object/get] +Note that the "--encoding" option does not affect the output, since the +output is the raw data of the object. + ++ Parameters + + arg (string, optional) - Key of the object to retrieve, in base58-encoded multihash format + Response 200 (text/plain) -## links [GET /object/links] +## get [GET /object/get{?arg,&encoding}] +Get and serialize the DAG node named by + +`ipfs object get` is a plumbing command for retreiving DAG nodes. +It serializes the DAG node to the format specified by the "--encoding" +flag. It outputs to stdout, and is a base58 encoded multihash. + ++ Parameters + + arg (string, required) - Key of the object to retrieve (in base58-encoded multihash format) + + encoding (enum[string], optional) - Serializes the DAG node to the format specified + + Default: `protobuf` + + Members: + + `protobuf` + + `json` + + `xml` + Response 200 (text/plain) -## new [GET /object/new] +## links [GET /object/links{?arg}] +Outputs the links pointed to by the specified object + +`ipfs object links` is a plumbing command for retreiving the links from +a DAG node. It outputs to stdout, and is a base58 encoded +multihash. + ++ Parameters + + arg (string, required) - Key of the object to retrieve, in base58-encoded multihash format + Response 200 (text/plain) -## patch [GET /object/patch] +## new [GET /object/new{?arg}] +Creates a new object from an ipfs template + +`ipfs object new` is a plumbing command for creating new DAG nodes. +By default it creates and returns a new empty merkledag node, but +you may pass an optional template argument to create a preformatted +node. + ++ Parameters + + arg (string, required) - optional template to use + + Available templates: + * unixfs-dir + + Response 200 (text/plain) -## put [GET /object/put] +## patch [GET /object/patch{?arg1,arg2,&name,ref}] +Create a new merkledag object based on an existing one + +`ipfs object patch ` is a plumbing command used to +build custom DAG objects. It adds and removes links from objects, creating a new object as a result. This is the merkle-dag version of modifying an object. It can also set the data inside a node with `set-data` and append to that data as well with `append-data`. + ++ Parameters + + arg1 (string, required) - the hash of the node to modify + + arg2 (enum[string], required) - the operation to perform + + Members: + + `add-link` - with ` `, adds a link to a node + + `rm-link` - with ``, removes a link from a node + + `set-data` - sets a nodes data from stdin + + `append-data` - appends to a nodes data from stdin + + name (string, optional) - used with `` and `` + + ref (string, optional) - used with ` ` + + create (boolean, optional) - create intermediate directories on `` + Response 200 (text/plain) -## stat [GET /object/stat] +## put [GET /object/put{?arg,&inputenc}] +Stores input as a DAG object, outputs its key + +`ipfs object put` is a plumbing command for storing DAG nodes. +It reads from stdin, and the output is a base58 encoded multihash. + +Data should be in the format specified by the --inputenc flag. + ++ Parameters + + arg (string, required) - Data to be stored as a DAG object + + inputenc (enum[string], optional) - Encoding type of input data + + Default: `json` + + Members: + + `protobuf` + + `json` + Response 200 (text/plain) + + Body + + ``` + added QmXg9Pp2ytZ14xgmQjYEiHjVjMFXzCVVEcRTWJBmLgR39V + ``` +## stat [GET /object/stat{?arg}] +Get stats for the DAG node named by + +`ipfs object stat` is a plumbing command to print DAG node statistics. + is a base58 encoded multihash. + ++ Parameters + + arg (string, required) - Key of the object to retrieve (in base58-encoded multihash format) + ++ Response 200 (application/json) + + + Attributes + - `Hash`: "QmXg9Pp2ytZ14xgmQjYEiHjVjMFXzCVVEcRTWJBmLgR39V" (string) - number of links in link table + - `NumLinks`: 0 (number) - number of links in link table + - `BlockSize`: 5 (number) - size of the raw, encoded data + - `LinksSize`: 2 (number) - size of the links segment + - `DataSize`: 3 (number) - size of the data segment + - `CumulativeSize`: 5 (number) - cumulative size of object and its references + # Group pin ## add [GET /pin/add] diff --git a/test b/test deleted file mode 100644 index e69de29..0000000 From 096a0d37d0341560ae0db4117f739850e685b430 Mon Sep 17 00:00:00 2001 From: Richard Littauer Date: Mon, 14 Dec 2015 22:31:21 -0500 Subject: [PATCH 15/37] Added `ipfs pin` group It seems strange to me that pin/rm has the same 200 response as pin/add. But that seems to be the case. --- apiary.apib | 82 +++++++++++++++++++++++++++++++++++++++++++++++++---- 1 file changed, 76 insertions(+), 6 deletions(-) diff --git a/apiary.apib b/apiary.apib index ccc17ad..fb9fb6f 100644 --- a/apiary.apib +++ b/apiary.apib @@ -1068,17 +1068,87 @@ Get stats for the DAG node named by - `CumulativeSize`: 5 (number) - cumulative size of object and its references # Group pin -## add [GET /pin/add] +Pin (and unpin) objects to local storage -+ Response 200 (text/plain) +## add [GET /pin/add{?arg,&recursive}] +Pins objects to local storage -## ls [GET /pin/ls] +Retrieves the object named by and stores it locally +on disk. -+ Response 200 (text/plain) ++ Parameters + + arg (string, required) - Path to object(s) to be pinned + + recursive (boolean, optional) - Recursively pin the object linked to by the specified object(s) -## rm [GET /pin/rm] ++ Response 200 (application/json) -+ Response 200 (text/plain) + + Attributes + + `Pinned` (array) + - Multihash + + + Body + + ``` + { + "Pinned": [ + "Qmd286K6pohQcTKYqnS1YhWrCiS4gz7Xi34sdwMe9USZ7u" + ] + } + ``` + +## ls [GET /pin/ls{&type,count,quiet}] +List objects pinned to local storage + ++ Parameters + + type (enum[string], optional) - The type of pinned keys to list. + Default: `recursive` + Members: + + `all` + + `direct` + + `indirect` + + `recursive` + + count (boolean, optional) - Show refcount when listing indirect pins + + quiet (boolean, optional) - Write just hashes of objects + ++ Response 200 (application/json) + + + Attributes + + `Keys` (object) - Contains multiple hashes + + hash (object) + - `Type`: "recursive" (string) + - `Coun`: 1 (number) + +## rm [GET /pin/rm{?arg,&recursive}] +Removes the pinned object from local storage. + +By default, recursively. Use `-r=false` for direct pins. + ++ Parameters + + arg (string, required) - Path to object(s) to be unpinned + + recursive (boolean, optional) - Recursively unpin the object linked to by the specified object(s) + Default: true + ++ Response 200 (application/json) + + + Attributes + + `Pinned` (array) + - Multihash + + + Body + + ``` + { + "Pinned": [ + "Qmd286K6pohQcTKYqnS1YhWrCiS4gz7Xi34sdwMe9USZ7u" + ] + } + ``` + ++ Response 500 (application/json) + + + Attributes + - `Message`: "Qmd286K6pohQcTKYqnS1YhWrCiS4gz7Xi34sdwMe9USZ7u is not pinned" (string) + - `Code`: 0 (number) # Group ping Send echo request packets to IPFS hosts From 729117b5e40a5ee1baa82bfb677d987e987940da Mon Sep 17 00:00:00 2001 From: Richard Littauer Date: Mon, 14 Dec 2015 22:34:32 -0500 Subject: [PATCH 16/37] Added options and args to ipfs ping --- apiary.apib | 6 +++++- 1 file changed, 5 insertions(+), 1 deletion(-) diff --git a/apiary.apib b/apiary.apib index fb9fb6f..1a158a5 100644 --- a/apiary.apib +++ b/apiary.apib @@ -1153,11 +1153,15 @@ By default, recursively. Use `-r=false` for direct pins. # Group ping Send echo request packets to IPFS hosts -## ping [GET /ping] +## ping [GET /ping{?arg,&count}] 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. ++ Parameters + + arg (string, required) - ID of peer to be pinged + + count (number, required) - number of ping messages to send + + Response 200 (application/json) + Headers From 71e5f600f173f9e2d67fc2f6f9be54a033ac25e8 Mon Sep 17 00:00:00 2001 From: Richard Littauer Date: Mon, 14 Dec 2015 22:46:15 -0500 Subject: [PATCH 17/37] Added `ipfs refs` I got a malformed syntax error when trying refs on Postman, but it seemed to work fine in the command line. I am not sure what exactly is happening with the format option, and I suspect that coud be improved a bit. Otherwise, this seems fine to me. Threw in headers because I might as well, they were right there. --- apiary.apib | 45 +++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 45 insertions(+) diff --git a/apiary.apib b/apiary.apib index 1a158a5..fb66c15 100644 --- a/apiary.apib +++ b/apiary.apib @@ -1191,10 +1191,55 @@ trip latency information. # Group refs +## refs [GET /refs{?arg,&format,edges,unique,recursive}] +Lists links (references) from an object + +Retrieves the object named by and displays the link +hashes it contains, with the following format: + + + +Note: list all refs recursively with -r. + ++ Parameters + + arg (string, required) - Path to the object(s) to list refs from + + format (string, optional) - Emit edges with given format. tokens: ` ` + + edges (boolean, optional) - Emit edge format: ` -> ` + + unique (boolean, optional) - Omit duplicate refs from output + + recursive (boolean, optional) - Recursively list links of child nodes + ++ Response 200 (text/plain) + + + Body + + ``` + Qmd286K6pohQcTKYqnS1YhWrCiS4gz7Xi34sdwMe9USZ7u + ``` + ## local [GET /refs/local] +Lists all local references + +Displays the hashes of all local objects. + Response 200 (text/plain) + + Headers + + ``` + Access-Control-Allow-Headers: X-Stream-Output, X-Chunked-Output + Access-Control-Expose-Headers: X-Stream-Output, X-Chunked-Output + Content-Type: text/plain + Trailer: X-Stream-Error + Transfer-Encoding: chunked, chunked + X-Stream-Output: 1 + ``` + + + Body + + ``` + QmW2WQi7j6c7UgJTarActp7tDNikE4B2qXtFCfLPdsgaTQ + ``` + # Group repo Manipulate the IPFS repo. From 633ebdb0a0e4f1a9b96f5542dcd2ea5bdbd0b600 Mon Sep 17 00:00:00 2001 From: Richard Littauer Date: Mon, 14 Dec 2015 22:48:10 -0500 Subject: [PATCH 18/37] Added params to resolve --- apiary.apib | 6 +++++- 1 file changed, 5 insertions(+), 1 deletion(-) diff --git a/apiary.apib b/apiary.apib index fb66c15..f9e9555 100644 --- a/apiary.apib +++ b/apiary.apib @@ -1254,13 +1254,17 @@ order to reclaim hard disk space. # Group resolve Resolve the value of names to IPFS. -## resolve [GET /resolve] +## resolve [GET /resolve{?arg,&resolve}] There are a number of mutable name protocols that can link among themselves and into IPNS. For example IPNS references can (currently) point at IPFS object, and DNS links can point at other DNS links, IPNS entries, or IPFS objects. This command accepts any of these identifiers and resolves them to the referenced item. ++ Parameters + + arg (string, required) - The name to resolve. + + recursive (boolean, optional) - Resolve until the result is an IPFS name + + Response 200 (application/json) + Attributes (object) From 100164582b4747a4f5b2ab235a58113e96d84766 Mon Sep 17 00:00:00 2001 From: Richard Littauer Date: Mon, 14 Dec 2015 22:50:18 -0500 Subject: [PATCH 19/37] Added params to stats bw --- apiary.apib | 8 +++++++- 1 file changed, 7 insertions(+), 1 deletion(-) diff --git a/apiary.apib b/apiary.apib index f9e9555..6e721a8 100644 --- a/apiary.apib +++ b/apiary.apib @@ -1273,9 +1273,15 @@ identifiers and resolves them to the referenced item. # Group stats Query IPFS statistics. -## bw [GET /stats/bw] +## bw [GET /stats/bw{&peer,proto,poll,interval}] Print ipfs bandwidth information. ++ Parameters + + peer (string, optional) - specify a peer to print bandwidth for + + proto (string, optional) - specify a protocol to print bandwidth for + + poll (boolean, optional) - print bandwidth at an interval + + interval (string, optional) - time interval to wait between updating output + + Response 200 (application/json) + Attributes (object) From f3d47ae71fc2453728350575ad44577efba261b0 Mon Sep 17 00:00:00 2001 From: Richard Littauer Date: Mon, 14 Dec 2015 22:54:29 -0500 Subject: [PATCH 20/37] Added content to ipfs swarm --- apiary.apib | 17 ++++++++++++++++- 1 file changed, 16 insertions(+), 1 deletion(-) diff --git a/apiary.apib b/apiary.apib index 6e721a8..1ac0b9f 100644 --- a/apiary.apib +++ b/apiary.apib @@ -1297,14 +1297,21 @@ Swarm inspection tool. ## addrs [GET /swarm/addrs] List known addresses. Useful for debugging. +`ipfs swarm addrs` lists all addresses this node is aware of. + + Response 200 (application/json) + Attributes (object) - Addrs (SwarmAddrs) -## addrs local [GET /swarm/addrs/local] +## addrs local [GET /swarm/addrs/local{&id}] List all local addresses. +`ipfs swarm addrs local` lists all local addresses the node is listening on. + ++ Parameters + + id (boolean, optional) - Show peer ID in addresses + + Response 200 (application/json) + Attributes (object) @@ -1356,6 +1363,10 @@ Filters default to those specified under the `"Swarm.AddrFilters"` config key. ## filters add [GET /swarm/filters/add{?arg}] Add the given multiaddr to the filter list. +`ipfs swarm filters add` will add an address filter to the daemons swarm. +Filters applied this way will not persist daemon reboots, to acheive that, +add your filters to the ipfs config file. + + Parameters + arg (MultiAddr, required) - Address to add to the filter list @@ -1364,6 +1375,10 @@ Add the given multiaddr to the filter list. ## filters rm [GET /swarm/filters/rm{?arg}] Remove the given multiaddr from the filter list. +`ipfs swarm filters rm` will remove an address filter from the daemons swarm. +Filters removed this way will not persist daemon reboots, to acheive that, +remove your filters from the ipfs config file. + + Parameters + arg (MultiAddr, required) - Address to remove from the filter list From 1e6dc9513ead42262d9d16fead7d64f0d864a899 Mon Sep 17 00:00:00 2001 From: Richard Littauer Date: Mon, 14 Dec 2015 22:59:31 -0500 Subject: [PATCH 21/37] Added `ipfs tar` I didn't get a response in my terminal for tarcat, so I assume there is none. I was unable to get tar/add to work, as well, in Postman, but in the terminal it returned the hash of the file, so that is probably what it returns there, too. --- apiary.apib | 25 +++++++++++++++++++++++-- test.tar | 0 2 files changed, 23 insertions(+), 2 deletions(-) create mode 100644 test.tar diff --git a/apiary.apib b/apiary.apib index 1ac0b9f..a721215 100644 --- a/apiary.apib +++ b/apiary.apib @@ -1396,16 +1396,37 @@ List the set of peers the node is connected to. # Group tar Utility functions for tar files in ipfs -## add [GET /tar/add] +## add [GET /tar/add{?arg}] Import a tar file into ipfs +`ipfs tar add` will parse a tar file and create a merkledag structure to represent it. + ++ Parameters + + arg (string, required) - tar file to add + + Response 200 (text/plain) -## cat [GET /tar/cat] + + Body + + ``` + QmevjfjydFGfFNTkBpvr8gYwUwFyM5LMe46sNyAQ1Fxw6a + ``` + +## cat [GET /tar/cat{?arg}] Export a tar file from ipfs +`ipfs tar cat` will export a tar file from a previously imported one in ipfs + ++ Parameters + + arg (string, required) - ipfs path of archive to export + + Response 200 (text/plain) + + Body + + ``` + ``` + # Group tour This is a tour that takes you through various IPFS concepts, features, and tools to make sure you get up to speed with diff --git a/test.tar b/test.tar new file mode 100644 index 0000000..e69de29 From 8e1d586618f03399cfa291ec2b1ea6556f221337 Mon Sep 17 00:00:00 2001 From: Richard Littauer Date: Mon, 14 Dec 2015 23:03:00 -0500 Subject: [PATCH 22/37] Added params to version --- apiary.apib | 8 +++++++- 1 file changed, 7 insertions(+), 1 deletion(-) diff --git a/apiary.apib b/apiary.apib index a721215..22d9e8f 100644 --- a/apiary.apib +++ b/apiary.apib @@ -1490,7 +1490,13 @@ Restart the IPFS Tour # Group version Show version details about the ipfs node. -## version [GET /version] +## version [GET /version{&number,commit,repo}] +Returns the current version of ipfs and exits. + ++ Parameters + + number (boolean, optional) - Only show the version number + + commit (boolean, optional) - Show the commit hash + + repo (boolean, optional) - Show repo version + Response 200 (application/json) + Attributes (object) From 2e59d1ace64ad318abcf4c806e2c9b6aedbdb554 Mon Sep 17 00:00:00 2001 From: Richard Littauer Date: Wed, 16 Dec 2015 11:43:59 -0500 Subject: [PATCH 23/37] Linted according to API doc --- apiary.apib | 221 ++++++++++++++++++++++++++++++++++------------------ 1 file changed, 144 insertions(+), 77 deletions(-) diff --git a/apiary.apib b/apiary.apib index 22d9e8f..857b9ca 100644 --- a/apiary.apib +++ b/apiary.apib @@ -4,7 +4,7 @@ FORMAT: 1A The API for interacting with IPFS nodes. -# Group add [GET /add{?arg,&recursive,quiet,silent,progress,trickle,only-hash,wrap-with-directory,hidden,chunker,pin}] +# Group add [GET /add{?arg}{&recursive,quiet,silent,progress,trickle,only%2Dhash,wrap%2Dwith%2Ddirectory,hidden,chunker,pin}] Add an object to ipfs. Adds contents of to ipfs. Use -r to add directories. @@ -28,6 +28,7 @@ remains to be implemented. + Response 200 (text/plain) + Body + ``` added QmbFMke1KXqnYyBBWxB74N4c5SBnJMVAiMNRcGu6x1AwQH test ``` @@ -151,7 +152,7 @@ the addresses of bootstrap nodes. These are the *trusted peers* from which to learn about other peers in the network. Only edit this list if you understand the risks of adding or removing nodes from this list. -## add [GET /bootstrap/add{?arg,&default}] +## add [GET /bootstrap/add{?arg}{&default}] Add peers to the bootstrap list Outputs a list of peers that were added (that weren't already @@ -236,14 +237,14 @@ Peers are output in the format `/`. } ``` -## rm [GET /bootstrap/rm{?arg,&all}] +## rm [GET /bootstrap/rm{?arg}{&all}] Removes peers from the bootstrap list Outputs the list of peers that were removed. + Parameters + arg (Multiaddr, optional) - A peer to add to the bootstrap list - + all (bool, optional) Remove all bootstrap peers. + + all (boolean, optional) - Remove all bootstrap peers. + Response 200 (application/json) @@ -280,13 +281,16 @@ Outputs the list of peers that were removed. Retrieves the object named by and outputs the data it contains. + Parameters - + arg (string, required) - The path to the IPFS object(s) to be outputted + + arg (string, required) - The path to the IPFS object or objects to be outputted + Response 200 + Headers - - Transfer-Encoding: chunked - - X-Stream-Output: 1 + + ``` + Transfer-Encoding: chunked + X-Stream-Output: 1 + ``` # Group commands @@ -301,7 +305,7 @@ Lists all available commands (and subcommands) that are available. # Group config -## config [GET /config{?arg1,arg2,&bool,json}] +## config [GET /config{?arg1,arg2}{&bool,json}] ipfs config controls configuration variables. It works much like 'git config'. The configuration values are stored in a config @@ -496,7 +500,9 @@ Run a 'FindPeer' query through the DHT + Parameters + arg (string, required) - The peer to search for -## findprovs [GET /dht/findprovs{?arg,&verbose}] ++ Response 200 + +## findprovs [GET /dht/findprovs{?arg}{&verbose}] Run a 'FindProviders' query through the DHT FindProviders will return a list of peers who are able to provide the value requested. @@ -505,7 +511,9 @@ FindProviders will return a list of peers who are able to provide the value requ + arg (string, required) - The key to find providers for + verbose (boolean, optional) - Write extra information -## get [GET /dht/get(?arg,&verbose)] ++ Response 200 + +## get [GET /dht/get{?arg}{&verbose}] Run a 'GetValue' query through the DHT GetValue will return the value stored in the dht at the given key. @@ -514,7 +522,9 @@ GetValue will return the value stored in the dht at the given key. + arg (string, required) - The key to find providers for + verbose (boolean, optional) - Write extra information -## put [GET /dht/put{?arg1,arg2,&verbose}] ++ Response 200 + +## put [GET /dht/put{?arg1,arg2}{&verbose}] Run a 'PutValue' query through the DHT PutValue will store the given key value pair in the dht. @@ -524,13 +534,73 @@ PutValue will store the given key value pair in the dht. + arg2 (string, required) - The value to store + verbose (boolean, optional) - Write extra information -## query [GET /dht/query] ++ Response 200 + +## query [GET /dht/query{?arg}{&verbose}] Run a 'findClosestPeers' query through the DHT + Parameters + arg (string, required) - The peerID to run the query against + verbose (boolean, optional) - Write extra information ++ Response 200 (application/json) + + + Headers + + ``` + Access-Control-Allow-Headers: X-Stream-Output, X-Chunked-Output + Access-Control-Expose-Headers: X-Stream-Output, X-Chunked-Output + Date: Wed, 16 Dec 2015 16:37:26 GMT + Trailer: X-Stream-Error + Transfer-Encoding: chunked, chunked + X-Chunked-Output: 1 + ``` + + + Body + + ``` + {"Extra":"","ID":"QmR6RQTtbGfzNqWTb4qvvovxpv8R5Fi1aC5YWUmE259ZDG","Responses":null,"Type":2} + {"Extra":"","ID":"QmdAYL426boH1RRFR6JABaNT4JNfrEJV1coiPfKytpPVwP","Responses":null,"Type":2} + {"Extra":"","ID":"QmP4HvpqhWDdfswxMoBkKW2LJjNeUKcQxKqpgmQuXnqrvX","Responses":null,"Type":2} + {"Extra":"","ID":"QmR6RQTtbGfzNqWTb4qvvovxpv8R5Fi1aC5YWUmE259ZDG","Responses":null,"Type":6} + {"Extra":"","ID":"QmdAYL426boH1RRFR6JABaNT4JNfrEJV1coiPfKytpPVwP","Responses":null,"Type":6} + {"Extra":"","ID":"QmWvc4uZhqKKmPWyjt8f1o9V1Gu2SkB1YSAFoDhfGUENcJ","Responses":null,"Type":2} + {"Extra":"","ID":"QmPBZAQmeEy4rVNGCCjY9tjJXmWURukfCRJRRgNKttNf3t","Responses":null,"Type":2} + {"Extra":"","ID":"QmP4HvpqhWDdfswxMoBkKW2LJjNeUKcQxKqpgmQuXnqrvX","Responses":null,"Type":6} + {"Extra":"","ID":"QmWvc4uZhqKKmPWyjt8f1o9V1Gu2SkB1YSAFoDhfGUENcJ","Responses":null,"Type":6} + {"Extra":"","ID":"QmdWox4MybJu5SK5YgQiYpCirvWgPNvRNBtAUpv4hthVio","Responses":null,"Type":2} + {"Extra":"","ID":"QmNRV7kyUxYaQ4KQxFXPYm8EfuzJbtGn1wSFenjXL6LD8y","Responses":null,"Type":2} + {"Extra":"","ID":"QmPBZAQmeEy4rVNGCCjY9tjJXmWURukfCRJRRgNKttNf3t","Responses":null,"Type":6} + {"Extra":"","ID":"QmPvYDTzGoJc6oRL9tDpqudF3CJzUfwoftfPnoAhbbSsfR","Responses":null,"Type":2} + {"Extra":"","ID":"QmeqnZVvHbP6BoLsE4pqCBRdTjvLvuEtAsf644YYXKb9ZU","Responses":null,"Type":2} + {"Extra":"","ID":"QmdWox4MybJu5SK5YgQiYpCirvWgPNvRNBtAUpv4hthVio","Responses":null,"Type":6} + {"Extra":"","ID":"QmNRV7kyUxYaQ4KQxFXPYm8EfuzJbtGn1wSFenjXL6LD8y","Responses":null,"Type":6} + {"Extra":"","ID":"QmeWdgoZezpdHz1PX8Ly8AeDQahFkBNtHn6qKeNtWP1jB6","Responses":null,"Type":2} + {"Extra":"","ID":"QmPvYDTzGoJc6oRL9tDpqudF3CJzUfwoftfPnoAhbbSsfR","Responses":null,"Type":6} + {"Extra":"","ID":"QmeqnZVvHbP6BoLsE4pqCBRdTjvLvuEtAsf644YYXKb9ZU","Responses":null,"Type":6} + {"Extra":"","ID":"QmeWdgoZezpdHz1PX8Ly8AeDQahFkBNtHn6qKeNtWP1jB6","Responses":null,"Type":6} + {"Extra":"","ID":"QmR6RQTtbGfzNqWTb4qvvovxpv8R5Fi1aC5YWUmE259ZDG","Responses":null,"Type":0} + {"Extra":"","ID":"QmP4HvpqhWDdfswxMoBkKW2LJjNeUKcQxKqpgmQuXnqrvX","Responses":null,"Type":0} + {"Extra":"","ID":"QmdAYL426boH1RRFR6JABaNT4JNfrEJV1coiPfKytpPVwP","Responses":null,"Type":0} + {"Extra":"","ID":"QmdAYL426boH1RRFR6JABaNT4JNfrEJV1coiPfKytpPVwP","Responses":[],"Type":1} + {"Extra":"","ID":"QmWvc4uZhqKKmPWyjt8f1o9V1Gu2SkB1YSAFoDhfGUENcJ","Responses":null,"Type":0} + {"Extra":"","ID":"QmR6RQTtbGfzNqWTb4qvvovxpv8R5Fi1aC5YWUmE259ZDG","Responses":[],"Type":1} + {"Extra":"","ID":"QmPBZAQmeEy4rVNGCCjY9tjJXmWURukfCRJRRgNKttNf3t","Responses":null,"Type":0} + {"Extra":"","ID":"QmWvc4uZhqKKmPWyjt8f1o9V1Gu2SkB1YSAFoDhfGUENcJ","Responses":[],"Type":1} + {"Extra":"","ID":"QmdWox4MybJu5SK5YgQiYpCirvWgPNvRNBtAUpv4hthVio","Responses":null,"Type":0} + {"Extra":"","ID":"QmP4HvpqhWDdfswxMoBkKW2LJjNeUKcQxKqpgmQuXnqrvX","Responses":[],"Type":1} + {"Extra":"","ID":"QmNRV7kyUxYaQ4KQxFXPYm8EfuzJbtGn1wSFenjXL6LD8y","Responses":null,"Type":0} + {"Extra":"","ID":"QmNRV7kyUxYaQ4KQxFXPYm8EfuzJbtGn1wSFenjXL6LD8y","Responses":[],"Type":1} + {"Extra":"","ID":"QmPvYDTzGoJc6oRL9tDpqudF3CJzUfwoftfPnoAhbbSsfR","Responses":null,"Type":0} + {"Extra":"","ID":"QmdWox4MybJu5SK5YgQiYpCirvWgPNvRNBtAUpv4hthVio","Responses":[],"Type":1} + {"Extra":"","ID":"QmeqnZVvHbP6BoLsE4pqCBRdTjvLvuEtAsf644YYXKb9ZU","Responses":null,"Type":0} + {"Extra":"","ID":"QmPBZAQmeEy4rVNGCCjY9tjJXmWURukfCRJRRgNKttNf3t","Responses":[],"Type":1} + {"Extra":"","ID":"QmeWdgoZezpdHz1PX8Ly8AeDQahFkBNtHn6qKeNtWP1jB6","Responses":null,"Type":0} + {"Extra":"","ID":"QmeqnZVvHbP6BoLsE4pqCBRdTjvLvuEtAsf644YYXKb9ZU","Responses":[],"Type":1} + {"Extra":"","ID":"QmPvYDTzGoJc6oRL9tDpqudF3CJzUfwoftfPnoAhbbSsfR","Responses":[],"Type":1} + {"Extra":"","ID":"QmeWdgoZezpdHz1PX8Ly8AeDQahFkBNtHn6qKeNtWP1jB6","Responses":[],"Type":1} + ``` + # Group diag Generate diagnostic reports. @@ -596,7 +666,7 @@ Print out information about your computer to aid in debugging. - `used_space`: 113462611968 (number) - environment (object) - GOPATH: `/Users/dignifiedquire/.go` (string) - - IPFS_PATH: (string, nullable) + - IPFS_PATH (string, nullable) - `ipfs_git_sha` (string) - `ipfs_version`: `0.3.9` (string) - memory (object) @@ -672,14 +742,14 @@ is the total size of the file contents. For directories, the child size is the IPFS link size. + Parameters - + arg (string, required) - The path to the IPFS object(s) to list links from + + arg (string, required) - The path to the IPFS object or objects to list links from + Response 200 (application/json) + Attributes + `Arguments` (object) - The key is the provided path, the value its hash + `Objects` (object) - + Key (object) - The key is the hash of the IPFS object(s) + + Key (object) - The key is the hash of the IPFS object or objects - `Hash` (string) - The hash - `Size` (number) - `Type` (string) @@ -710,7 +780,7 @@ size is the IPFS link size. # Group get -## get [GET /get{?arg,&output,archive,compress,compression-level}] +## get [GET /get{?arg}{&output,archive,compress,compression%2Dlevel}] Download IPFS objects Retrieves the object named by and stores the data to disk. @@ -724,7 +794,7 @@ To compress the output with GZIP compression, use '--compress' or '-C'. You may also specify the level of compression by specifying '-l=<1-9>'. + Parameters - + arg (string, required) - The path to the IPFS object(s) to tbe outputted + + arg (string, required) - The path to the IPFS object or objects to be outputted + output (string, optional) - The path where output should be stored + archive (boolean, optional) - Output a TAR archive + compress (boolean, optional) - Compress the output with GZIP compression @@ -735,7 +805,6 @@ may also specify the level of compression by specifying '-l=<1-9>'. + Headers ``` - Content-type: text/plain Access-Control-Allow-Headers: X-Stream-Output, X-Chunked-Output Access-Control-Expose-Headers: X-Stream-Output, X-Chunked-Output Date: Tue, 15 Dec 2015 00:38:02 GMT @@ -761,7 +830,7 @@ ipfs id supports the format option for output with the following keys: : public key : addresses (newline delimited) -## id [GET /id{?arg,&format}] +## id [GET /id{?arg}{&format}] Show IPFS Node ID info + Parameters @@ -834,15 +903,15 @@ output of a running daemon. # Group ls List links from an object. -## ls [GET /ls{?arg,&headers}] +## ls [GET /ls{?arg}{&headers}] Retrieves the object named by and displays the links it contains, with the following format: + Parameters - + arg (string, required) - The path to the IPFS object(s) to list links from - + headers (boolean, optional) - Print table headers (Hash, Name, Size) + + arg (string, required) - The path to the IPFS object or objects to list links from + + headers (boolean, optional) - Print table headers, with Hash, Name, Size + Response 200 (application/json) @@ -859,29 +928,29 @@ it contains, with the following format: + Body - ``` - { - "Objects": [ + ``` { - "Hash": "/ipfs/QmW2WQi7j6c7UgJTarActp7tDNikE4B2qXtFCfLPdsgaTQ/cat.jpg", - "Links": [ - { - "Name": "", - "Hash": "QmPEKipMh6LsXzvtLxunSPP7ZsBM8y9xQ2SQQwBXy5UY6e", - "Size": 262158, - "Type": 2 - }, + "Objects": [ { - "Name": "", - "Hash": "QmT8onRUfPgvkoPMdMvCHPYxh98iKCfFkBYM1ufYpnkHJn", - "Size": 181100, - "Type": 2 + "Hash": "/ipfs/QmW2WQi7j6c7UgJTarActp7tDNikE4B2qXtFCfLPdsgaTQ/cat.jpg", + "Links": [ + { + "Name": "", + "Hash": "QmPEKipMh6LsXzvtLxunSPP7ZsBM8y9xQ2SQQwBXy5UY6e", + "Size": 262158, + "Type": 2 + }, + { + "Name": "", + "Hash": "QmT8onRUfPgvkoPMdMvCHPYxh98iKCfFkBYM1ufYpnkHJn", + "Size": 181100, + "Type": 2 + } + ] } ] } - ] - } - ``` + ``` # Group mount Mounts IPFS to the filesystem (read-only) @@ -903,7 +972,7 @@ IPNS is a PKI namespace, where names are the hashes of public keys, and the private key enables publishing new (signed) values. In publish, the default value of is your own identity public key. -## publish [GET /name/publish{?arg,&resolve,lifetime,ttl}] +## publish [GET /name/publish{?arg}{&resolve,lifetime,ttl}] Publish an object to IPNS + Parameters @@ -958,7 +1027,7 @@ output is the raw data of the object. + Response 200 (text/plain) -## get [GET /object/get{?arg,&encoding}] +## get [GET /object/get{?arg}{&encoding}] Get and serialize the DAG node named by `ipfs object get` is a plumbing command for retreiving DAG nodes. @@ -969,7 +1038,7 @@ flag. It outputs to stdout, and is a base58 encoded multihash. + arg (string, required) - Key of the object to retrieve (in base58-encoded multihash format) + encoding (enum[string], optional) - Serializes the DAG node to the format specified + Default: `protobuf` - + Members: + + Members + `protobuf` + `json` + `xml` @@ -1005,7 +1074,7 @@ node. + Response 200 (text/plain) -## patch [GET /object/patch{?arg1,arg2,&name,ref}] +## patch [GET /object/patch{?arg1,arg2}{&name,ref}] Create a new merkledag object based on an existing one `ipfs object patch ` is a plumbing command used to @@ -1025,7 +1094,7 @@ build custom DAG objects. It adds and removes links from objects, creating a new + Response 200 (text/plain) -## put [GET /object/put{?arg,&inputenc}] +## put [GET /object/put{?arg}{&inputenc}] Stores input as a DAG object, outputs its key `ipfs object put` is a plumbing command for storing DAG nodes. @@ -1037,7 +1106,7 @@ Data should be in the format specified by the --inputenc flag. + arg (string, required) - Data to be stored as a DAG object + inputenc (enum[string], optional) - Encoding type of input data + Default: `json` - + Members: + + Members + `protobuf` + `json` @@ -1045,9 +1114,10 @@ Data should be in the format specified by the --inputenc flag. + Body - ``` - added QmXg9Pp2ytZ14xgmQjYEiHjVjMFXzCVVEcRTWJBmLgR39V - ``` + ``` + added QmXg9Pp2ytZ14xgmQjYEiHjVjMFXzCVVEcRTWJBmLgR39V + ``` + ## stat [GET /object/stat{?arg}] Get stats for the DAG node named by @@ -1070,15 +1140,15 @@ Get stats for the DAG node named by # Group pin Pin (and unpin) objects to local storage -## add [GET /pin/add{?arg,&recursive}] +## add [GET /pin/add{?arg}{&recursive}] Pins objects to local storage Retrieves the object named by and stores it locally on disk. + Parameters - + arg (string, required) - Path to object(s) to be pinned - + recursive (boolean, optional) - Recursively pin the object linked to by the specified object(s) + + arg (string, required) - Path to object or objects to be pinned + + recursive (boolean, optional) - Recursively pin the object linked to by the specified object or objects + Response 200 (application/json) @@ -1118,14 +1188,14 @@ List objects pinned to local storage - `Type`: "recursive" (string) - `Coun`: 1 (number) -## rm [GET /pin/rm{?arg,&recursive}] +## rm [GET /pin/rm{?arg}{&recursive}] Removes the pinned object from local storage. By default, recursively. Use `-r=false` for direct pins. + Parameters - + arg (string, required) - Path to object(s) to be unpinned - + recursive (boolean, optional) - Recursively unpin the object linked to by the specified object(s) + + arg (string, required) - Path to object or objects to be unpinned + + recursive (boolean, optional) - Recursively unpin the object linked to by the specified object or objects Default: true + Response 200 (application/json) @@ -1153,7 +1223,7 @@ By default, recursively. Use `-r=false` for direct pins. # Group ping Send echo request packets to IPFS hosts -## ping [GET /ping{?arg,&count}] +## ping [GET /ping{?arg}{&count}] 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. @@ -1191,7 +1261,7 @@ trip latency information. # Group refs -## refs [GET /refs{?arg,&format,edges,unique,recursive}] +## refs [GET /refs{?arg}{&format,edges,unique,recursive}] Lists links (references) from an object Retrieves the object named by and displays the link @@ -1202,7 +1272,7 @@ hashes it contains, with the following format: Note: list all refs recursively with -r. + Parameters - + arg (string, required) - Path to the object(s) to list refs from + + arg (string, required) - Path to the object or objects to list refs from + format (string, optional) - Emit edges with given format. tokens: ` ` + edges (boolean, optional) - Emit edge format: ` -> ` + unique (boolean, optional) - Omit duplicate refs from output @@ -1228,7 +1298,6 @@ Displays the hashes of all local objects. ``` Access-Control-Allow-Headers: X-Stream-Output, X-Chunked-Output Access-Control-Expose-Headers: X-Stream-Output, X-Chunked-Output - Content-Type: text/plain Trailer: X-Stream-Error Transfer-Encoding: chunked, chunked X-Stream-Output: 1 @@ -1254,7 +1323,7 @@ order to reclaim hard disk space. # Group resolve Resolve the value of names to IPFS. -## resolve [GET /resolve{?arg,&resolve}] +## resolve [GET /resolve{?arg}{&resolve}] There are a number of mutable name protocols that can link among themselves and into IPNS. For example IPNS references can (currently) point at IPFS object, and DNS links can point at other DNS links, IPNS @@ -1516,23 +1585,21 @@ QmNjRVohhWBX31EoaAXkrj5mPF9vQNcTVvQgWHNwdxweCN A list of swarm addresses. ### Sample -``` -"QmNRCEwFMgCcbjNk5bFud9oqjJduvjBNbkiM8SuxuLh3GS": [ - "/ip4/127.0.0.1/tcp/4001", - "/ip4/172.17.42.1/tcp/4001", - "/ip4/192.168.2.3/tcp/4001", - "/ip6/::1/tcp/4001" -], -"QmNRV7kyUxYaQ4KQxFXPYm8EfuzJbtGn1wSFenjXL6LD8y": [ - "/ip4/127.0.0.1/tcp/4001", - "/ip4/172.17.42.1/tcp/4001", - "/ip4/5.9.33.222/tcp/4001", - "/ip6/2a01:4f8:161:124a::1337:cafe/tcp/4001", - "/ip6/2a01:4f8:161:124a::2/tcp/4001", - "/ip6/::1/tcp/4001", - "/ip6/fcfc:762a:e12a:245d:8e5b:6a40:f65:acab/tcp/4001" -] -``` +- "QmNRCEwFMgCcbjNk5bFud9oqjJduvjBNbkiM8SuxuLh3GS": [ + "/ip4/127.0.0.1/tcp/4001", + "/ip4/172.17.42.1/tcp/4001", + "/ip4/192.168.2.3/tcp/4001", + "/ip6/::1/tcp/4001" + ], + "QmNRV7kyUxYaQ4KQxFXPYm8EfuzJbtGn1wSFenjXL6LD8y": [ + "/ip4/127.0.0.1/tcp/4001", + "/ip4/172.17.42.1/tcp/4001", + "/ip4/5.9.33.222/tcp/4001", + "/ip6/2a01:4f8:161:124a::1337:cafe/tcp/4001", + "/ip6/2a01:4f8:161:124a::2/tcp/4001", + "/ip6/::1/tcp/4001", + "/ip6/fcfc:762a:e12a:245d:8e5b:6a40:f65:acab/tcp/4001" + ] ## MultiAddr (string) From a2369ce5fbb351a5c5a0602e1d519f11d274d40a Mon Sep 17 00:00:00 2001 From: Richard Littauer Date: Wed, 16 Dec 2015 11:44:18 -0500 Subject: [PATCH 24/37] Remove test file --- test.tar | 0 1 file changed, 0 insertions(+), 0 deletions(-) delete mode 100644 test.tar diff --git a/test.tar b/test.tar deleted file mode 100644 index e69de29..0000000 From 291bcb781cab7881bff7e40d9cc1c633e20a9504 Mon Sep 17 00:00:00 2001 From: Richard Littauer Date: Wed, 16 Dec 2015 11:51:49 -0500 Subject: [PATCH 25/37] Changed nullable to string, nullable --- apiary.apib | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/apiary.apib b/apiary.apib index 857b9ca..b80041e 100644 --- a/apiary.apib +++ b/apiary.apib @@ -382,7 +382,7 @@ included in the output of this command. + `Datastore` (object) - `GCPeriod`: "" (string) - `NoSync`: false (boolean) - - `Params`: null (nullable) + - `Params`: null (string, nullable) - `Path`: "" (string) - `StorageGCWatermark`: 90 (number) - `StorageMax`: "10GB" (string) @@ -392,7 +392,7 @@ included in the output of this command. - `Enabled`: true (boolean) - `Interval`: 10 (number) + `Gateway` (object) - - `HTTPHeaders`: null (nullable) + - `HTTPHeaders`: null (string, nullable) - `RootRedirect`: "" (string) - `Writable`: false (boolean) + `Identity` (object) @@ -414,7 +414,7 @@ included in the output of this command. + `Servers` (array) - MultiAddr (string) + `Swarm` (object) - - `AddrFilters`: null (nullable) + - `AddrFilters`: null (string, nullable) + `Tour` (object) - `Last`: "" (string) @@ -753,7 +753,7 @@ size is the IPFS link size. - `Hash` (string) - The hash - `Size` (number) - `Type` (string) - - `Links` (nullable) + - `Links` (string, nullable) + Body From 266d53df93cc01184b2d2d0e3190326cffc44370 Mon Sep 17 00:00:00 2001 From: Richard Littauer Date: Wed, 16 Dec 2015 16:16:54 -0500 Subject: [PATCH 26/37] Single quotes to backticks --- apiary.apib | 32 ++++++++++++++++---------------- 1 file changed, 16 insertions(+), 16 deletions(-) diff --git a/apiary.apib b/apiary.apib index b80041e..3b0a164 100644 --- a/apiary.apib +++ b/apiary.apib @@ -38,7 +38,7 @@ remains to be implemented. + Body ``` - File argument 'path' is required + File argument `path` is required ``` # Group bitswap @@ -308,7 +308,7 @@ Lists all available commands (and subcommands) that are available. ## config [GET /config{?arg1,arg2}{&bool,json}] ipfs config controls configuration variables. It works -much like 'git config'. The configuration values are stored in a config +much like `git config`. The configuration values are stored in a config file inside your IPFS repository. **Examples:** @@ -342,7 +342,7 @@ Set the value of the 'datastore.path' key: ## edit [GET /config/edit] Opens the config file for editing in $EDITOR -To use 'ipfs config edit', you must have the $EDITOR environment +To use `ipfs config edit`, you must have the $EDITOR environment variable set to your preferred text editor. + Response 200 (buffer) @@ -495,7 +495,7 @@ future version, along with this notice. Please move to setting the HTTP Headers. Issue commands directly through the DHT ## findpeer [GET /dht/findpeer{?arg}] -Run a 'FindPeer' query through the DHT +Run a `FindPeer` query through the DHT + Parameters + arg (string, required) - The peer to search for @@ -503,7 +503,7 @@ Run a 'FindPeer' query through the DHT + Response 200 ## findprovs [GET /dht/findprovs{?arg}{&verbose}] -Run a 'FindProviders' query through the DHT +Run a `FindProviders` query through the DHT FindProviders will return a list of peers who are able to provide the value requested. @@ -514,7 +514,7 @@ FindProviders will return a list of peers who are able to provide the value requ + Response 200 ## get [GET /dht/get{?arg}{&verbose}] -Run a 'GetValue' query through the DHT +Run a `GetValue` query through the DHT GetValue will return the value stored in the dht at the given key. @@ -525,7 +525,7 @@ GetValue will return the value stored in the dht at the given key. + Response 200 ## put [GET /dht/put{?arg1,arg2}{&verbose}] -Run a 'PutValue' query through the DHT +Run a `PutValue` query through the DHT PutValue will store the given key value pair in the dht. @@ -537,7 +537,7 @@ PutValue will store the given key value pair in the dht. + Response 200 ## query [GET /dht/query{?arg}{&verbose}] -Run a 'findClosestPeers' query through the DHT +Run a `findClosestPeers` query through the DHT + Parameters + arg (string, required) - The peerID to run the query against @@ -624,7 +624,7 @@ The default timeout is 20 seconds. /ipfs/QmbesKpGyQGd5jtJFUGEB1ByPjNFpukhnKZDnkfxUiKn38 ``` - To view your diag output, 'ipfs add' the d3 vis output, and + To view your diag output, `ipfs add` the d3 vis output, and open the following link: ``` @@ -727,7 +727,7 @@ ipfs.io. TXT "dnslink=/ipfs/QmRzTuh2Lpuz7Gr39stNr6mTFdqAghsZec1JoUnfySUzcy ..." # Group file Interact with ipfs objects representing Unix filesystems -'ipfs file' provides a familar interface to filesystems represtented +`ipfs file` provides a familar interface to filesystems represtented by IPFS objects that hides IPFS-implementation details like layout objects (e.g. fanout and chunking). @@ -786,12 +786,12 @@ Download IPFS objects Retrieves the object named by and stores the data to disk. By default, the output will be stored at ./, but an alternate path -can be specified with '--output=' or '-o='. +can be specified with `--output=` or `-o=`. -To output a TAR archive instead of unpacked files, use '--archive' or '-a'. +To output a TAR archive instead of unpacked files, use `--archive` or `-a`. -To compress the output with GZIP compression, use '--compress' or '-C'. You -may also specify the level of compression by specifying '-l=<1-9>'. +To compress the output with GZIP compression, use `--compress` or `-C`. You +may also specify the level of compression by specifying `-l=<1-9>`. + Parameters + arg (string, required) - The path to the IPFS object or objects to be outputted @@ -883,7 +883,7 @@ output of a running daemon. output of a running daemon. + Parameters - + arg1 (string) - the subsystem logging identifier. Use 'all' for all subsystems. + + arg1 (string) - the subsystem logging identifier. Use `all` for all subsystems. + arg2 (enum[string]) + Members + debug @@ -896,7 +896,7 @@ output of a running daemon. + Response 200 (text/plain) ## tail [GET /log/tail] -'ipfs log tail' is a utility command used to read log output as it is written. +`ipfs log tail` is a utility command used to read log output as it is written. + Response 200 (text/plain) From 01123a56ece6d95755ba0ffa732a24fe8982495b Mon Sep 17 00:00:00 2001 From: Richard Littauer Date: Fri, 25 Dec 2015 20:38:19 -0500 Subject: [PATCH 27/37] Update add with new curl result This is not the result I got back from Postman, as I wasn't able to make it work there. Here is the curl response. --- apiary.apib | 9 ++++++++- 1 file changed, 8 insertions(+), 1 deletion(-) diff --git a/apiary.apib b/apiary.apib index 3b0a164..29fe4f4 100644 --- a/apiary.apib +++ b/apiary.apib @@ -27,10 +27,17 @@ remains to be implemented. + Response 200 (text/plain) + + Attributes + + Name (string) + + Hash (Multihash) + + Body ``` - added QmbFMke1KXqnYyBBWxB74N4c5SBnJMVAiMNRcGu6x1AwQH test + { + "Name":"test", + "Hash":"QmePw8gVcBMb8x6kAep6aMBAX23hCSk6iZW3i9VKkiFhu1" + } ``` + Response 400 (text/plain) From b10cde3a710471b38ccbd4c7806fda1f046a82c6 Mon Sep 17 00:00:00 2001 From: Richard Littauer Date: Fri, 25 Dec 2015 20:41:25 -0500 Subject: [PATCH 28/37] Using a data structure for error messages --- apiary.apib | 80 +++++++++++++++++++++++++++++++++++------------------ 1 file changed, 53 insertions(+), 27 deletions(-) diff --git a/apiary.apib b/apiary.apib index 29fe4f4..ae697b8 100644 --- a/apiary.apib +++ b/apiary.apib @@ -187,9 +187,7 @@ in the bootstrap list). + Response 400 (application/json) - + Attributes (object) - + Message: no bootstrap peers to add (string) - + Code: 1 (number) + + Attributes (Err) + Body @@ -202,9 +200,7 @@ in the bootstrap list). + Response 500 (application/json) - + Attributes (object) - + Message: invalid multiaddr, must begin with / (string) - + Code: 0 (number) + + Attributes (Err) + Body @@ -269,9 +265,7 @@ Outputs the list of peers that were removed. + Response 500 (application/json) - + Attributes (object) - + Message: invalid ipfs address (string) - + Code: 0 (number) + + Attributes (Err) + Body @@ -342,9 +336,7 @@ Set the value of the 'datastore.path' key: + Response 500 (application/json) - + Attributes (object) - + `Message` (string) - + `Code`: 0 (number) + + Attributes (Err) ## edit [GET /config/edit] Opens the config file for editing in $EDITOR @@ -781,9 +773,7 @@ size is the IPFS link size. ``` + Response 500 (application/json) - + Attributes - + `Message` (string) - + `Code` (number) + + Attributes (Err) # Group get @@ -821,9 +811,17 @@ may also specify the level of compression by specifying `-l=<1-9>`. ``` + Response 500 (application/json) - + Attributes - + `Message`: "context canceled" (string) - + `Code`: 0 (number) + + + Attributes (Err) + + + Body + + ``` + { + "Message": "context canceled", + "Code": 0 + } + ``` # Group id @@ -877,9 +875,16 @@ Show IPFS Node ID info + Response 400 - + Attributes - + `Message`: "Invalid peer id" (string) - + `Code`: 1 (number) + + Attributes (Err) + + + Body + + ``` + { + "Message": "Invalid peer id", + "Code": 1 + } + ``` # Group log `ipfs log` contains utility commands to affect or read the logging @@ -1009,9 +1014,16 @@ Gets the value currently published at an IPNS name + Response 500 - + Attributes - + `Message`: "could not resolve name" (string) - + `Code`: 0 (number) + + Attributes (Err) + + + Body + + ``` + { + "Message": "could not resolve name", + "Code": 0 + } + ``` # Group object Interact with ipfs objects. @@ -1223,9 +1235,16 @@ By default, recursively. Use `-r=false` for direct pins. + Response 500 (application/json) - + Attributes - - `Message`: "Qmd286K6pohQcTKYqnS1YhWrCiS4gz7Xi34sdwMe9USZ7u is not pinned" (string) - - `Code`: 0 (number) + + Attributes (Err) + + + Body + + ``` + { + "Message": "Qmd286K6pohQcTKYqnS1YhWrCiS4gz7Xi34sdwMe9USZ7u is not pinned", + "Code": 9 + } + ``` # Group ping Send echo request packets to IPFS hosts @@ -1581,6 +1600,13 @@ Returns the current version of ipfs and exits. # Data Structures +## Err (object) ++ Message (string) ++ Code (enum[number]) + + Members + + 0 + + 1 + ## Multihash (string) An hash as defined [here](https://github.com/jbenet/multihash) From 99a336ebbaaa53d917e6cebf3acceeb26cd0bdf7 Mon Sep 17 00:00:00 2001 From: Richard Littauer Date: Fri, 25 Dec 2015 20:43:33 -0500 Subject: [PATCH 29/37] Remove CLI docs --- apiary.apib | 68 +++-------------------------------------------------- 1 file changed, 3 insertions(+), 65 deletions(-) diff --git a/apiary.apib b/apiary.apib index ae697b8..6e7b1b0 100644 --- a/apiary.apib +++ b/apiary.apib @@ -312,19 +312,10 @@ ipfs config controls configuration variables. It works much like `git config`. The configuration values are stored in a config file inside your IPFS repository. -**Examples:** - -Get the value of the 'datastore.path' key: - - `ipfs config datastore.path` - -Set the value of the 'datastore.path' key: - - `ipfs config datastore.path ~/.ipfs/datastore` + Parameters - + arg1: "Addresses.API" (string, required) - The key of the config entry - + arg2 (string, required) - The value to set the config entry to + + arg1: "Datastore.Path" (string, required) - The key of the config entry + + arg2: "~/.ipfs/datastore" (string, required) - The value to set the config entry to + bool (boolean, optional) - Set a boolean + json (boolean, optional) - Parse stringified JSON @@ -426,59 +417,6 @@ communicating with a daemon over the HTTP API. While the daemon is running, calls to `ipfs` commands will be sent over the network to the daemon. -The daemon will start listening on ports on the network, which are -documented in (and can be modified through) `ipfs config Addresses`. -For example, to change the `Gateway` port: - - ipfs config Addresses.Gateway /ip4/127.0.0.1/tcp/8082 - -The API address can be changed the same way: - - ipfs config Addresses.API /ip4/127.0.0.1/tcp/5002 - -Make sure to restart the daemon after changing addresses. - -By default, the gateway is only accessible locally. To expose it to -other computers in the network, use 0.0.0.0 as the ip address: - - ipfs config Addresses.Gateway /ip4/0.0.0.0/tcp/8080 - -Be careful if you expose the API. It is a security risk, as anyone could -control your node remotely. If you need to control the node remotely, -make sure to protect the port as you would other services or database -(firewall, authenticated proxy, etc). - -HTTP Headers - -IPFS supports passing arbitrary headers to the API and Gateway. You can -do this by setting headers on the API.HTTPHeaders and Gateway.HTTPHeaders -keys: - - ipfs config --json API.HTTPHeaders.X-Special-Header '["so special :)"]' - ipfs config --json Gateway.HTTPHeaders.X-Special-Header '["so special :)"]' - -Note that the value of the keys is an _array_ of strings. This is because -headers can have more than one value, and it is convenient to pass through -to other libraries. - -CORS Headers (for API) - -You can setup CORS headers the same way: - - ipfs config --json API.HTTPHeaders.Access-Control-Allow-Origin '["*"]' - ipfs config --json API.HTTPHeaders.Access-Control-Allow-Methods '["PUT", "GET", "POST"]' - ipfs config --json API.HTTPHeaders.Access-Control-Allow-Credentials '["true"]' - - -**Deprecation Notice** - -Previously, IPFS used an environment variable as seen below: - - export API_ORIGIN="http://localhost:8888/" - -This is deprecated. It is still honored in this version, but will be removed in a -future version, along with this notice. Please move to setting the HTTP Headers. - + Parameters + init (boolean, optional) - Initialize IPFS with default settings if not already initialized + routing (string, optional) - Overrides the routing option (dht, supernode) @@ -1608,7 +1546,7 @@ Returns the current version of ipfs and exits. + 1 ## Multihash (string) -An hash as defined [here](https://github.com/jbenet/multihash) +An hash as defined [here](https://github.com/jbenet/multihash). ### Sample QmNjRVohhWBX31EoaAXkrj5mPF9vQNcTVvQgWHNwdxweCN From 02ee57ebe6aff9f11b8fbff9a6bbba052f6581dd Mon Sep 17 00:00:00 2001 From: Richard Littauer Date: Fri, 25 Dec 2015 21:19:23 -0500 Subject: [PATCH 30/37] Added example curl requests --- apiary.apib | 10 ++++++++++ 1 file changed, 10 insertions(+) diff --git a/apiary.apib b/apiary.apib index 6e7b1b0..1f61b11 100644 --- a/apiary.apib +++ b/apiary.apib @@ -12,6 +12,10 @@ Note that directories are added recursively, to form the ipfs MerkleDAG. A smarter partial add with a staging area (like git) remains to be implemented. +#### curl + + curl -F "file=@test/" -r http://localhost:5001/api/v0/add + + Parameters + arg (string, required) - The path to a file to be added to IPFS + recursive (boolean, optional) - Add directory paths recursively @@ -128,6 +132,12 @@ Stores input as an IPFS block ipfs block put is a plumbing command for storing raw ipfs blocks. It reads from stdin, and is a base58 encoded multihash. +#### curl + + curl -i -F "file=@test" http://localhost:5001/api/v0/block/put + + + + Parameters + arg (string, required) - The path to the data to be stored as an IPFS block From afc33e5ba28de46aba50cca74a8e71084b4cee9e Mon Sep 17 00:00:00 2001 From: Richard Littauer Date: Fri, 25 Dec 2015 21:20:21 -0500 Subject: [PATCH 31/37] Filled out block/put example --- apiary.apib | 31 ++++++++++++++++++++++++++++--- dredd.yml | 25 +++++++++++++++++++++++++ test | 0 3 files changed, 53 insertions(+), 3 deletions(-) create mode 100644 dredd.yml create mode 100644 test diff --git a/apiary.apib b/apiary.apib index 1f61b11..be302c5 100644 --- a/apiary.apib +++ b/apiary.apib @@ -130,7 +130,6 @@ Store data as a raw ipfs block. Stores input as an IPFS block ipfs block put is a plumbing command for storing raw ipfs blocks. -It reads from stdin, and is a base58 encoded multihash. #### curl @@ -141,12 +140,38 @@ It reads from stdin, and is a base58 encoded multihash. + Parameters + arg (string, required) - The path to the data to be stored as an IPFS block -+ Response 200 (text/plain) ++ Response 200 (application/json) + + + Headers + + ``` + Access-Control-Allow-Headers: X-Stream-Output, X-Chunked-Output + Access-Control-Expose-Headers: X-Stream-Output, X-Chunked-Output + Trailer: X-Stream-Error + Transfer-Encoding: chunked + Date: Sat, 26 Dec 2015 02:13:34 GMT + Transfer-Encoding: chunked + ``` + + + Attributes + + Key (Multihash) + + Size (number) + + + Body + + ``` + { + "Key":"QmdfTbBqBPQ7VNxZEYEj14VmRuZBkqFbiwReogJgS1zR1n", + "Size":0 + } + ``` + ++ Response 400 (text/plain) + Body ``` - QmdfTbBqBPQ7VNxZEYEj14VmRuZBkqFbiwReogJgS1zR1n + File argument 'data' is required ``` + Response 403 (text/plain) diff --git a/dredd.yml b/dredd.yml new file mode 100644 index 0000000..1b5abb0 --- /dev/null +++ b/dredd.yml @@ -0,0 +1,25 @@ +dry-run: null +hookfiles: null +language: nodejs +sandbox: false +server: ipfs daemon +server-wait: 3 +init: false +custom: {} +names: false +only: [] +reporter: apiary +output: [] +header: [] +sorted: false +user: null +inline-errors: false +details: false +method: [] +color: true +level: info +timestamp: false +silent: false +path: [] +blueprint: apiary.apib +endpoint: 'http://localhost:4001' diff --git a/test b/test new file mode 100644 index 0000000..e69de29 From 425f737d6e5fde8af40751e991a937372692dc86 Mon Sep 17 00:00:00 2001 From: Richard Littauer Date: Fri, 25 Dec 2015 21:29:22 -0500 Subject: [PATCH 32/37] Added curl and headers and 500 to config/replace --- apiary.apib | 29 ++++++++++++++++++++++++++++- 1 file changed, 28 insertions(+), 1 deletion(-) diff --git a/apiary.apib b/apiary.apib index be302c5..ee4528d 100644 --- a/apiary.apib +++ b/apiary.apib @@ -378,11 +378,38 @@ Replaces the config with Make sure to back up the config file first if neccessary, this operation can't be undone. +#### curl + + curl -i -F "file=@test" http://localhost:5001/api/v0/config/replace + + Parameters + arg (string, required) - The file to use as the new config -+ Response 200 () ++ Response 200 (application/json) + + + Headers + + ``` + Access-Control-Allow-Headers: X-Stream-Output, X-Chunked-Output + Access-Control-Expose-Headers: X-Stream-Output, X-Chunked-Output + Trailer: X-Stream-Error + Transfer-Encoding: chunked + Date: Sat, 26 Dec 2015 02:26:19 GMT + ``` + ++ Response 500 () + + + Attributes (Err) + + + Body + + ``` + { + "Message":"Failed to decode file as config", + "Code":0 + } + ``` ## show [GET /config/show] Outputs the content of the config file From dcfe5be3f0eaf72922da5b493593fef9af638989 Mon Sep 17 00:00:00 2001 From: Richard Littauer Date: Fri, 25 Dec 2015 21:30:05 -0500 Subject: [PATCH 33/37] Spelling --- apiary.apib | 2 +- test | 82 +++++++++++++++++++++++++++++++++++++++++++++++++++++ 2 files changed, 83 insertions(+), 1 deletion(-) diff --git a/apiary.apib b/apiary.apib index ee4528d..5c19ba1 100644 --- a/apiary.apib +++ b/apiary.apib @@ -988,7 +988,7 @@ default value of is your own identity public key. Publish an object to IPNS + Parameters - + arg (string, required) - IPFS path of the obejct to be published + + arg (string, required) - IPFS path of the object to be published + resolve (boolean, optional) - Resolve given path before publishing + Default: `true` + lifetime (string, optional) - time duration that the record will be valid for diff --git a/test b/test index e69de29..8a55e87 100644 --- a/test +++ b/test @@ -0,0 +1,82 @@ +{ + "API": { + "HTTPHeaders": null + }, + "Addresses": { + "API": "/ip4/127.0.0.1/tcp/5001", + "Gateway": "/ip4/127.0.0.1/tcp/8080", + "Swarm": [ + "/ip4/0.0.0.0/tcp/4001", + "/ip6/::/tcp/4001" + ] + }, + "Bootstrap": [ + "/ipfs/QmePw8gVcBMb8x6kAep6aMBAX23hCSk6iZW3i9VKkiFhu1", + "/ip4/104.131.131.82/tcp/4001/ipfs/QmaCpDMGvV2BGHeYERUEnRQAwe3N8SzbUtfsmvsqQLuvuJ", + "/ip4/104.236.176.52/tcp/4001/ipfs/QmSoLnSGccFuZQJzRadHn95W2CrSFmZuTdDWP8HXaHca9z", + "/ip4/104.236.179.241/tcp/4001/ipfs/QmSoLPppuBtQSGwKDZT2M73ULpjvfd3aZ6ha4oFGL1KrGM", + "/ip4/162.243.248.213/tcp/4001/ipfs/QmSoLueR4xBeUbY9WZ9xGUUxunbKWcrNFTDAadQJmocnWm", + "/ip4/128.199.219.111/tcp/4001/ipfs/QmSoLSafTMBsPKadTEgaXctDQVcqN88CNLHXMkTNwMKPnu", + "/ip4/104.236.76.40/tcp/4001/ipfs/QmSoLV4Bbm51jM9C4gDYZQ9Cy3U6aXMJDAbzgu2fzaDs64", + "/ip4/178.62.158.247/tcp/4001/ipfs/QmSoLer265NRgSp2LA3dPaeykiS1J6DifTC88f5uVQKNAd", + "/ip4/178.62.61.185/tcp/4001/ipfs/QmSoLMeWqB7YGVLJN3pNLQpmmEk35v6wYtsMGLzSr5QBU3", + "/ip4/104.236.151.122/tcp/4001/ipfs/QmSoLju6m7xTh3DuokvT3886QRYqxAzb1kShaanJgW36yx" + ], + "Datastore": { + "GCPeriod": "1h", + "Path": "/Users/richard/.ipfs/datastore", + "StorageGCWatermark": 90, + "StorageMax": "10GB", + "Type": "leveldb" + }, + "Discovery": { + "MDNS": { + "Enabled": true, + "Interval": 10 + } + }, + "Gateway": { + "HTTPHeaders": null, + "RootRedirect": "", + "Writable": false + }, + "Identity": { + "PeerID": "QmZ93LBubp1Xhg4eDRBNE1zHHFTz6XMCv9urJzjeowMSxn", + "PrivKey": "CAASqAkwggSkAgEAAoIBAQDAQTx2N+dbaUEDnfDVDPqaig6QFa6M4cekxbEFwBPFCiJkyZXcx69BlL8o7Bcahn9Y2KyVyL/ZEclQuCv2PJY0+69UpTIcFS9AX9iyiSwzYOzcL8vhSC2oPFoOakH0VU4Qc67x+mzpQO1IIi01BgSWZCG+sajZyA+/pVaqR5WZWaKulfJtaAOGYbULm1bDIBnG6BtX/fIu5d30Hu8UB5KqAItC//IU4aeUPTAJU/2j9WScIWCPw5jeFzOxEHC5HqK4DSPZPma/OLtKu+OkbI5IEE8tqFcGLe0uvPnTX3yhv0zC1Q/7gveRr/EAMd79MEiW7WR2AykSix4QdnmQX6J5AgMBAAECggEBAI4qL1mD8VMJPAg+rK3+0PmiCS7GubJ36rePcF2+MWBNJC2/W1BNYO1v3wOVwWfd+SFr6ANC1Yrguis0ZV3KY5B+ZKKFHc7iY3SI66bqBINhswUHWw4V350+M6HhNTBGPFmyEbXh5tN9LXlfvGovLwk+ti1bFm8kn3CqBLIaCSfBddiX56i28H3vPVNhv7OC0+RLNEtLS6Grg1mz+KSoXWrz5jEOtU9DwV9WlDsxhGYCxuKzhhzMyIo5M4qgOtH9S/D/6lmn4EZ1Moxn+nQ5AUqOLFdkxqBp+QTGsWdPWDG4Kv8IGJhdXf4T0Uoht2rojeWSWdYQLdIGbhmiVCf9f/kCgYEAz7cRKJw16muNeuwoGSvd2madNsPd33AQA1pbDcYuty2PNHWfU2wgXI3YODVyJpSm3ja7FjMcRDw/oruWCfGShIcrrqZv9E4kEh7cF9j5ladwLbRlmhzYt6YsRbjrXFPCqNJit5ymbXw2bWZ6h85uDF2kEAHOl5CQ25O8n427i6MCgYEA7PIkd1KSPlowSJqp8LlWrvJr6nijK03OICIGeCXE0LE6nfPMKKNRq7MGwy7+8uE/bvc5zr/9zEEOwkmmiMl4NAxebzMnZNp4GokjmPniklbyu8xxhQGAmjwhD/yoC4ylVpN9fkPDM+McxyygoNPr00f7JEEaOwLbwgmxNece+zMCgYBnoYUtBqqblydSEap7zHf2M8XyAcybYnSKx7Sv7ZV3DILrAFgKLeMDaj1a5cda2kVajmHO1JcgsBJrpT1ZHq4j8rBnhWBLugSjCcRzHWyALrZ4Bw290vCIx55E9tpuCNgQlE5uHvilnRgmgr9VLDeZccqdtdkVoymyc0XjMLpGEwKBgBml5FieMYJaVNunEjoidcWeLBxHTrJDS8qipDyhKfrFFGlAmJrVguOpD1RVY/d6dllWnYVJtvlDGYviWQp5dG9930L+MId0Nof4zEek1OeuTbwSVz9keD05wQJwAOivIr6KXI0sXJbjQJw2snR2PBK0ufSkr2gv2QXZ8rq499uNAoGBAMfus5r35VgZrL+GVvL72bI0OXlbBcELIefilL5OxCkTK9zzloKr602RggXUsMkhU9VRp7JzJI7+YhhWbXRPORhuZMiIjBbpOoeHyOWFvrbH5z9ug+53mM5UMoslLAdDSEMCZiviv58N6Wk+zFo5SsHVB2rvhTlu4jFvJNeNg4jy" + }, + "Ipns": { + "RecordLifetime": "", + "RepublishPeriod": "", + "ResolveCacheSize": 128 + }, + "Mounts": { + "FuseAllowOther": false, + "IPFS": "/ipfs", + "IPNS": "/ipns" + }, + "SupernodeRouting": { + "Servers": [ + "/ip4/104.236.176.52/tcp/4002/ipfs/QmXdb7tWTxdFEQEFgWBqkuYSrZd3mXrC7HxkD4krGNYx2U", + "/ip4/104.236.179.241/tcp/4002/ipfs/QmVRqViDByUxjUMoPnjurjKvZhaEMFDtK35FJXHAM4Lkj6", + "/ip4/104.236.151.122/tcp/4002/ipfs/QmSZwGx8Tn8tmcM4PtDJaMeUQNRhNFdBLVGPzRiNaRJtFH", + "/ip4/162.243.248.213/tcp/4002/ipfs/QmbHVEEepCi7rn7VL7Exxpd2Ci9NNB6ifvqwhsrbRMgQFP", + "/ip4/128.199.219.111/tcp/4002/ipfs/Qmb3brdCYmKG1ycwqCbo6LUwWxTuo3FisnJV2yir7oN92R", + "/ip4/104.236.76.40/tcp/4002/ipfs/QmdRBCV8Cz2dGhoKLkD3YjPwVFECmqADQkx5ZteF2c6Fy4", + "/ip4/178.62.158.247/tcp/4002/ipfs/QmUdiMPci7YoEUBkyFZAh2pAbjqcPr7LezyiPD2artLw3v", + "/ip4/178.62.61.185/tcp/4002/ipfs/QmVw6fGNqBixZE4bewRLT2VXX7fAHUHs8JyidDiJ1P7RUN" + ] + }, + "Swarm": { + "AddrFilters": null + }, + "Tour": { + "Last": "" + }, + "Version": { + "AutoUpdate": "minor", + "Check": "error", + "CheckDate": "0001-01-01T00:00:00Z", + "CheckPeriod": "172800000000000", + "Current": "0.3.11-dev" + } +} \ No newline at end of file From 13ff0c92e7580a64466e8f58aef3b4fcdf3a665e Mon Sep 17 00:00:00 2001 From: Richard Littauer Date: Fri, 25 Dec 2015 21:36:59 -0500 Subject: [PATCH 34/37] Remove cli speak --- apiary.apib | 41 ++++----------------------- test | 82 ----------------------------------------------------- 2 files changed, 6 insertions(+), 117 deletions(-) delete mode 100644 test diff --git a/apiary.apib b/apiary.apib index 5c19ba1..f7ae9ac 100644 --- a/apiary.apib +++ b/apiary.apib @@ -95,10 +95,6 @@ Show blocks currently on the wantlist # Group block Manipulate raw IPFS blocks -`ipfs block` is a plumbing command used to manipulate raw ipfs blocks. -Reads from stdin or writes to stdout, and is a base58 encoded -multihash. - ## stat [GET /block/stat?{arg}] Retrieve information on a raw ipfs block. @@ -1034,13 +1030,6 @@ directly. ## data [GET /object/data{?arg}] Outputs the raw bytes in an IPFS object -`ipfs object data` is a plumbing command for retreiving the raw bytes stored in -a DAG node. It outputs to stdout, and is a base58 encoded -multihash. - -Note that the "--encoding" option does not affect the output, since the -output is the raw data of the object. - + Parameters + arg (string, optional) - Key of the object to retrieve, in base58-encoded multihash format @@ -1049,10 +1038,6 @@ output is the raw data of the object. ## get [GET /object/get{?arg}{&encoding}] Get and serialize the DAG node named by -`ipfs object get` is a plumbing command for retreiving DAG nodes. -It serializes the DAG node to the format specified by the "--encoding" -flag. It outputs to stdout, and is a base58 encoded multihash. - + Parameters + arg (string, required) - Key of the object to retrieve (in base58-encoded multihash format) + encoding (enum[string], optional) - Serializes the DAG node to the format specified @@ -1067,10 +1052,6 @@ flag. It outputs to stdout, and is a base58 encoded multihash. ## links [GET /object/links{?arg}] Outputs the links pointed to by the specified object -`ipfs object links` is a plumbing command for retreiving the links from -a DAG node. It outputs to stdout, and is a base58 encoded -multihash. - + Parameters + arg (string, required) - Key of the object to retrieve, in base58-encoded multihash format @@ -1079,16 +1060,14 @@ multihash. ## new [GET /object/new{?arg}] Creates a new object from an ipfs template -`ipfs object new` is a plumbing command for creating new DAG nodes. By default it creates and returns a new empty merkledag node, but you may pass an optional template argument to create a preformatted node. + Parameters - + arg (string, required) - optional template to use - - Available templates: - * unixfs-dir + + arg (enum[string], optional) - template used to create a prefomatted node + + Members + - unixfs-dir + Response 200 (text/plain) @@ -1096,8 +1075,7 @@ node. ## patch [GET /object/patch{?arg1,arg2}{&name,ref}] Create a new merkledag object based on an existing one -`ipfs object patch ` is a plumbing command used to -build custom DAG objects. It adds and removes links from objects, creating a new object as a result. This is the merkle-dag version of modifying an object. It can also set the data inside a node with `set-data` and append to that data as well with `append-data`. +`patch` adds and removes links from objects, creating a new object as a result. This is the merkle-dag version of modifying an object. It can also set the data inside a node with `set-data` and append to that data as well with `append-data`. + Parameters + arg1 (string, required) - the hash of the node to modify @@ -1105,8 +1083,8 @@ build custom DAG objects. It adds and removes links from objects, creating a new + Members: + `add-link` - with ` `, adds a link to a node + `rm-link` - with ``, removes a link from a node - + `set-data` - sets a nodes data from stdin - + `append-data` - appends to a nodes data from stdin + + `set-data` - sets a node's data + + `append-data` - appends to a node's data + name (string, optional) - used with `` and `` + ref (string, optional) - used with ` ` + create (boolean, optional) - create intermediate directories on `` @@ -1116,11 +1094,6 @@ build custom DAG objects. It adds and removes links from objects, creating a new ## put [GET /object/put{?arg}{&inputenc}] Stores input as a DAG object, outputs its key -`ipfs object put` is a plumbing command for storing DAG nodes. -It reads from stdin, and the output is a base58 encoded multihash. - -Data should be in the format specified by the --inputenc flag. - + Parameters + arg (string, required) - Data to be stored as a DAG object + inputenc (enum[string], optional) - Encoding type of input data @@ -1210,8 +1183,6 @@ List objects pinned to local storage ## rm [GET /pin/rm{?arg}{&recursive}] Removes the pinned object from local storage. -By default, recursively. Use `-r=false` for direct pins. - + Parameters + arg (string, required) - Path to object or objects to be unpinned + recursive (boolean, optional) - Recursively unpin the object linked to by the specified object or objects diff --git a/test b/test deleted file mode 100644 index 8a55e87..0000000 --- a/test +++ /dev/null @@ -1,82 +0,0 @@ -{ - "API": { - "HTTPHeaders": null - }, - "Addresses": { - "API": "/ip4/127.0.0.1/tcp/5001", - "Gateway": "/ip4/127.0.0.1/tcp/8080", - "Swarm": [ - "/ip4/0.0.0.0/tcp/4001", - "/ip6/::/tcp/4001" - ] - }, - "Bootstrap": [ - "/ipfs/QmePw8gVcBMb8x6kAep6aMBAX23hCSk6iZW3i9VKkiFhu1", - "/ip4/104.131.131.82/tcp/4001/ipfs/QmaCpDMGvV2BGHeYERUEnRQAwe3N8SzbUtfsmvsqQLuvuJ", - "/ip4/104.236.176.52/tcp/4001/ipfs/QmSoLnSGccFuZQJzRadHn95W2CrSFmZuTdDWP8HXaHca9z", - "/ip4/104.236.179.241/tcp/4001/ipfs/QmSoLPppuBtQSGwKDZT2M73ULpjvfd3aZ6ha4oFGL1KrGM", - "/ip4/162.243.248.213/tcp/4001/ipfs/QmSoLueR4xBeUbY9WZ9xGUUxunbKWcrNFTDAadQJmocnWm", - "/ip4/128.199.219.111/tcp/4001/ipfs/QmSoLSafTMBsPKadTEgaXctDQVcqN88CNLHXMkTNwMKPnu", - "/ip4/104.236.76.40/tcp/4001/ipfs/QmSoLV4Bbm51jM9C4gDYZQ9Cy3U6aXMJDAbzgu2fzaDs64", - "/ip4/178.62.158.247/tcp/4001/ipfs/QmSoLer265NRgSp2LA3dPaeykiS1J6DifTC88f5uVQKNAd", - "/ip4/178.62.61.185/tcp/4001/ipfs/QmSoLMeWqB7YGVLJN3pNLQpmmEk35v6wYtsMGLzSr5QBU3", - "/ip4/104.236.151.122/tcp/4001/ipfs/QmSoLju6m7xTh3DuokvT3886QRYqxAzb1kShaanJgW36yx" - ], - "Datastore": { - "GCPeriod": "1h", - "Path": "/Users/richard/.ipfs/datastore", - "StorageGCWatermark": 90, - "StorageMax": "10GB", - "Type": "leveldb" - }, - "Discovery": { - "MDNS": { - "Enabled": true, - "Interval": 10 - } - }, - "Gateway": { - "HTTPHeaders": null, - "RootRedirect": "", - "Writable": false - }, - "Identity": { - "PeerID": "QmZ93LBubp1Xhg4eDRBNE1zHHFTz6XMCv9urJzjeowMSxn", - "PrivKey": "CAASqAkwggSkAgEAAoIBAQDAQTx2N+dbaUEDnfDVDPqaig6QFa6M4cekxbEFwBPFCiJkyZXcx69BlL8o7Bcahn9Y2KyVyL/ZEclQuCv2PJY0+69UpTIcFS9AX9iyiSwzYOzcL8vhSC2oPFoOakH0VU4Qc67x+mzpQO1IIi01BgSWZCG+sajZyA+/pVaqR5WZWaKulfJtaAOGYbULm1bDIBnG6BtX/fIu5d30Hu8UB5KqAItC//IU4aeUPTAJU/2j9WScIWCPw5jeFzOxEHC5HqK4DSPZPma/OLtKu+OkbI5IEE8tqFcGLe0uvPnTX3yhv0zC1Q/7gveRr/EAMd79MEiW7WR2AykSix4QdnmQX6J5AgMBAAECggEBAI4qL1mD8VMJPAg+rK3+0PmiCS7GubJ36rePcF2+MWBNJC2/W1BNYO1v3wOVwWfd+SFr6ANC1Yrguis0ZV3KY5B+ZKKFHc7iY3SI66bqBINhswUHWw4V350+M6HhNTBGPFmyEbXh5tN9LXlfvGovLwk+ti1bFm8kn3CqBLIaCSfBddiX56i28H3vPVNhv7OC0+RLNEtLS6Grg1mz+KSoXWrz5jEOtU9DwV9WlDsxhGYCxuKzhhzMyIo5M4qgOtH9S/D/6lmn4EZ1Moxn+nQ5AUqOLFdkxqBp+QTGsWdPWDG4Kv8IGJhdXf4T0Uoht2rojeWSWdYQLdIGbhmiVCf9f/kCgYEAz7cRKJw16muNeuwoGSvd2madNsPd33AQA1pbDcYuty2PNHWfU2wgXI3YODVyJpSm3ja7FjMcRDw/oruWCfGShIcrrqZv9E4kEh7cF9j5ladwLbRlmhzYt6YsRbjrXFPCqNJit5ymbXw2bWZ6h85uDF2kEAHOl5CQ25O8n427i6MCgYEA7PIkd1KSPlowSJqp8LlWrvJr6nijK03OICIGeCXE0LE6nfPMKKNRq7MGwy7+8uE/bvc5zr/9zEEOwkmmiMl4NAxebzMnZNp4GokjmPniklbyu8xxhQGAmjwhD/yoC4ylVpN9fkPDM+McxyygoNPr00f7JEEaOwLbwgmxNece+zMCgYBnoYUtBqqblydSEap7zHf2M8XyAcybYnSKx7Sv7ZV3DILrAFgKLeMDaj1a5cda2kVajmHO1JcgsBJrpT1ZHq4j8rBnhWBLugSjCcRzHWyALrZ4Bw290vCIx55E9tpuCNgQlE5uHvilnRgmgr9VLDeZccqdtdkVoymyc0XjMLpGEwKBgBml5FieMYJaVNunEjoidcWeLBxHTrJDS8qipDyhKfrFFGlAmJrVguOpD1RVY/d6dllWnYVJtvlDGYviWQp5dG9930L+MId0Nof4zEek1OeuTbwSVz9keD05wQJwAOivIr6KXI0sXJbjQJw2snR2PBK0ufSkr2gv2QXZ8rq499uNAoGBAMfus5r35VgZrL+GVvL72bI0OXlbBcELIefilL5OxCkTK9zzloKr602RggXUsMkhU9VRp7JzJI7+YhhWbXRPORhuZMiIjBbpOoeHyOWFvrbH5z9ug+53mM5UMoslLAdDSEMCZiviv58N6Wk+zFo5SsHVB2rvhTlu4jFvJNeNg4jy" - }, - "Ipns": { - "RecordLifetime": "", - "RepublishPeriod": "", - "ResolveCacheSize": 128 - }, - "Mounts": { - "FuseAllowOther": false, - "IPFS": "/ipfs", - "IPNS": "/ipns" - }, - "SupernodeRouting": { - "Servers": [ - "/ip4/104.236.176.52/tcp/4002/ipfs/QmXdb7tWTxdFEQEFgWBqkuYSrZd3mXrC7HxkD4krGNYx2U", - "/ip4/104.236.179.241/tcp/4002/ipfs/QmVRqViDByUxjUMoPnjurjKvZhaEMFDtK35FJXHAM4Lkj6", - "/ip4/104.236.151.122/tcp/4002/ipfs/QmSZwGx8Tn8tmcM4PtDJaMeUQNRhNFdBLVGPzRiNaRJtFH", - "/ip4/162.243.248.213/tcp/4002/ipfs/QmbHVEEepCi7rn7VL7Exxpd2Ci9NNB6ifvqwhsrbRMgQFP", - "/ip4/128.199.219.111/tcp/4002/ipfs/Qmb3brdCYmKG1ycwqCbo6LUwWxTuo3FisnJV2yir7oN92R", - "/ip4/104.236.76.40/tcp/4002/ipfs/QmdRBCV8Cz2dGhoKLkD3YjPwVFECmqADQkx5ZteF2c6Fy4", - "/ip4/178.62.158.247/tcp/4002/ipfs/QmUdiMPci7YoEUBkyFZAh2pAbjqcPr7LezyiPD2artLw3v", - "/ip4/178.62.61.185/tcp/4002/ipfs/QmVw6fGNqBixZE4bewRLT2VXX7fAHUHs8JyidDiJ1P7RUN" - ] - }, - "Swarm": { - "AddrFilters": null - }, - "Tour": { - "Last": "" - }, - "Version": { - "AutoUpdate": "minor", - "Check": "error", - "CheckDate": "0001-01-01T00:00:00Z", - "CheckPeriod": "172800000000000", - "Current": "0.3.11-dev" - } -} \ No newline at end of file From 40ad96ef660825617f9708a5f18b7a4e30be4ad4 Mon Sep 17 00:00:00 2001 From: Richard Littauer Date: Fri, 25 Dec 2015 21:54:00 -0500 Subject: [PATCH 35/37] Update refs with better responses --- apiary.apib | 38 ++++++++++++++++++++++++++++++-------- test | 0 2 files changed, 30 insertions(+), 8 deletions(-) create mode 100644 test diff --git a/apiary.apib b/apiary.apib index f7ae9ac..adb4e75 100644 --- a/apiary.apib +++ b/apiary.apib @@ -1261,12 +1261,8 @@ trip latency information. ## refs [GET /refs{?arg}{&format,edges,unique,recursive}] Lists links (references) from an object -Retrieves the object named by and displays the link -hashes it contains, with the following format: - - - -Note: list all refs recursively with -r. +#### curl + curl -i http://localhost:5001/api/v0/refs?arg=/ipfs/QmW2WQi7j6c7UgJTarActp7tDNikE4B2qXtFCfLPdsgaTQ/cat.jpg + Parameters + arg (string, required) - Path to the object or objects to list refs from @@ -1275,12 +1271,38 @@ Note: list all refs recursively with -r. + unique (boolean, optional) - Omit duplicate refs from output + recursive (boolean, optional) - Recursively list links of child nodes -+ Response 200 (text/plain) ++ Response 200 (application/json) + + + Headers + + ``` + Access-Control-Allow-Headers: X-Stream-Output, X-Chunked-Output + Access-Control-Expose-Headers: X-Stream-Output, X-Chunked-Output + Trailer: X-Stream-Error + Transfer-Encoding: chunked + X-Chunked-Output: 1 + Date: Sat, 26 Dec 2015 02:46:43 GMT + ``` + + + Body + + ``` + { + "Ref":"QmPEKipMh6LsXzvtLxunSPP7ZsBM8y9xQ2SQQwBXy5UY6e", + "Err":"" + } + { + "Ref":"QmT8onRUfPgvkoPMdMvCHPYxh98iKCfFkBYM1ufYpnkHJn", + "Err":"" + } + ``` + ++ Response 400 (text/plain) + Body ``` - Qmd286K6pohQcTKYqnS1YhWrCiS4gz7Xi34sdwMe9USZ7u + Argument 'ipfs-path' is required ``` ## local [GET /refs/local] diff --git a/test b/test new file mode 100644 index 0000000..e69de29 From 8c64bec4182ab6c86ae59af5e580811a64164161 Mon Sep 17 00:00:00 2001 From: Richard Littauer Date: Sun, 27 Dec 2015 11:52:40 -0500 Subject: [PATCH 36/37] Edited dredd.yml to match @Dignifiedquire --- dredd.yml | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/dredd.yml b/dredd.yml index 1b5abb0..f3b3133 100644 --- a/dredd.yml +++ b/dredd.yml @@ -3,8 +3,8 @@ hookfiles: null language: nodejs sandbox: false server: ipfs daemon -server-wait: 3 -init: false +server-wait: 10 +init: true custom: {} names: false only: [] @@ -22,4 +22,4 @@ timestamp: false silent: false path: [] blueprint: apiary.apib -endpoint: 'http://localhost:4001' +endpoint: 'http://localhost:5001/api/v0' From d91fba093ff7572d2156dd4c0ab50532d81ef21d Mon Sep 17 00:00:00 2001 From: Richard Littauer Date: Fri, 8 Jan 2016 10:53:46 -0500 Subject: [PATCH 37/37] Filled out the ipfs add further --- apiary.apib | 64 +++++++++++++++++++++++++++++++++++++++++++---- test => test/test | 0 2 files changed, 59 insertions(+), 5 deletions(-) rename test => test/test (100%) diff --git a/apiary.apib b/apiary.apib index adb4e75..04d7ff9 100644 --- a/apiary.apib +++ b/apiary.apib @@ -4,10 +4,9 @@ FORMAT: 1A The API for interacting with IPFS nodes. -# Group add [GET /add{?arg}{&recursive,quiet,silent,progress,trickle,only%2Dhash,wrap%2Dwith%2Ddirectory,hidden,chunker,pin}] -Add an object to ipfs. +# Group add [POST /add{?arg}{&recursive,quiet,silent,progress,trickle,only%2Dhash,wrap%2Dwith%2Ddirectory,hidden,chunker,pin}] +Add an object to IPFS. -Adds contents of to ipfs. Use -r to add directories. Note that directories are added recursively, to form the ipfs MerkleDAG. A smarter partial add with a staging area (like git) remains to be implemented. @@ -29,7 +28,35 @@ remains to be implemented. + chunker (boolean, optional) - chunking algorithm to use + pin (boolean, optional) - Pin this object when adding. Default true -+ Response 200 (text/plain) ++ Request Single File (application/json) + + #### Curl + + curl -F "file=test" http://localhost:5001/api/v0/add + + + Body + + ``` + curl -F "file=test" http://localhost:5001/api/v0/add + ``` + ++ Response 200 (application/json) + + + Headers + + ``` + HTTP/1.1 100 Continue + + HTTP/1.1 200 OK + Access-Control-Allow-Headers: X-Stream-Output, X-Chunked-Output + Access-Control-Expose-Headers: X-Stream-Output, X-Chunked-Output + Content-Type: application/json + Trailer: X-Stream-Error + Transfer-Encoding: chunked + X-Chunked-Output: 1 + Date: Fri, 08 Jan 2016 14:48:18 GMT + Transfer-Encoding: chunked + ``` + Attributes + Name (string) @@ -44,7 +71,34 @@ remains to be implemented. } ``` -+ Response 400 (text/plain) ++ Request Recursive files (text/plain) + + I am currently unable to get this working. + + #### Curl + + curl -F "file=@test/" -x POST -r http://localhost:5001/api/v0/add + + + Headers + + ++ Request Empty Arguments (text/plain) + + #### curl + + curl -i http://localhost:5001/api/v0/add` + + + Body + ++ Response 400 + + + Headers + + ``` + Date: Fri, 08 Jan 2016 15:22:01 GMT + Content-Length: 32 + Content-Type: text/plain; charset=utf-8 + ``` + Body diff --git a/test b/test/test similarity index 100% rename from test rename to test/test