From e17d9990bebc510162dc1af766b3c2532a126468 Mon Sep 17 00:00:00 2001 From: Richard Littauer Date: Fri, 5 Feb 2016 12:52:20 -0500 Subject: [PATCH 1/5] Added Group `refs` Bugs: - [ ] The `format` option has no effect on the output. - [ ] If an argument is included, an `invalid ipfs paths ref` error is thrown, although there is no possible valid ipfs paths ref. --- apiary.apib | 326 ++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 326 insertions(+) diff --git a/apiary.apib b/apiary.apib index 55ee94e..da793f8 100644 --- a/apiary.apib +++ b/apiary.apib @@ -4460,6 +4460,332 @@ trip latency information. # Group refs +Retrieves the object named by and displays the link +hashes it contains. + +## refs [GET /refs{?arg}{&format,edges,unique,recursive}] +Lists links (references) from an object + +#### 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. + + format (string, optional) - Emit edges with given format. Tokens: ` `. + + edges (boolean, optional) - Emit edge format: ` -> `. Alias: e. + + unique (boolean, optional) - Omit duplicate refs from output. Alias: u. + + recursive (boolean, optional) - Recursively list links of child nodes. Alias: r. + ++ Request Without Arguments + + #### curl + + curl -i "http://localhost:5001/api/v0/refs" + + + Body + + ``` + curl -i "http://localhost:5001/api/v0/refs" + ``` + ++ Response 400 + + + Headers + + ``` + Date: Fri, 05 Feb 2016 17:30:09 GMT + Content-Length: 32 + Content-Type: text/plain; charset=utf-8 + ``` + + + Attributes (string) + + + Body + + ``` + Argument 'ipfs-path' is required + ``` + ++ Request With Empty Argument + + The response is the same if there is an invalid argument. For example: + + curl -i "http://localhost:5001/api/v0/refs?arg=kitten" + + #### curl + + curl -i "http://localhost:5001/api/v0/refs?arg=" + + + Body + + ``` + curl -i "http://localhost:5001/api/v0/refs?arg=" + ``` + ++ Response 500 + + + Headers + + ``` + Content-Type: application/json + Trailer: X-Stream-Error + Transfer-Encoding: chunked + Date: Fri, 05 Feb 2016 17:30:51 GMT + Transfer-Encoding: chunked + ``` + + + Attributes (Error) + - Message: "invalid ipfs ref path" + - Code: 0 + + + Body + + ``` + { + "Message": "invalid ipfs ref path", + "Code": 0 + } + ``` + ++ Request With Argument + + #### curl + + curl -i "http://localhost:5001/api/v0/refs?arg=QmPEKipMh6LsXzvtLxunSPP7ZsBM8y9xQ2SQQwBXy5UY6e" + + + Body + + ``` + curl -i "http://localhost:5001/api/v0/refs?arg=QmPEKipMh6LsXzvtLxunSPP7ZsBM8y9xQ2SQQwBXy5UY6e" + ``` + ++ Response 200 + + + Headers + + ``` + Content-Type: application/json + Trailer: X-Stream-Error + Transfer-Encoding: chunked + X-Chunked-Output: 1 + Date: Fri, 05 Feb 2016 17:31:52 GMT + Transfer-Encoding: chunked + ``` + + + Attributes + + + Body + + ``` + ``` + ++ Request With Argument + + #### curl + + curl -i "http://localhost:5001/api/v0/refs?arg=QmW2WQi7j6c7UgJTarActp7tDNikE4B2qXtFCfLPdsgaTQ" + + + Body + + ``` + curl -i "http://localhost:5001/api/v0/refs?arg=QmW2WQi7j6c7UgJTarActp7tDNikE4B2qXtFCfLPdsgaTQ" + ``` + ++ Response 200 + + + Headers + + ``` + Content-Type: application/json + Trailer: X-Stream-Error + Transfer-Encoding: chunked + X-Chunked-Output: 1 + Date: Fri, 05 Feb 2016 17:33:49 GMT + Transfer-Encoding: chunked + ``` + + + Attributes (ndjson) + - Ref (Multihash) + - Err (string) + + + Body + + ``` + { + "Ref": "Qmd286K6pohQcTKYqnS1YhWrCiS4gz7Xi34sdwMe9USZ7u", + "Err": "" + } + ``` + ++ Request With Argument And Format Option + + #### curl + + curl -i "http://localhost:5001/api/v0/refs?arg=QmW2WQi7j6c7UgJTarActp7tDNikE4B2qXtFCfLPdsgaTQ&format=" + + + Body + + ``` + curl -i "http://localhost:5001/api/v0/refs?arg=QmW2WQi7j6c7UgJTarActp7tDNikE4B2qXtFCfLPdsgaTQ&format=" + ``` + ++ Response 200 + + + Headers + + ``` + Content-Type: application/json + Trailer: X-Stream-Error + Transfer-Encoding: chunked + X-Chunked-Output: 1 + Date: Fri, 05 Feb 2016 17:36:20 GMT + Transfer-Encoding: chunked + ``` + + + Attributes (ndjson) + - Ref (string) + - Err (string) + + + Body + + ``` + { + "Ref": "cat.jpg", + "Err": "" + } + ``` + ++ Request With Argument And Edge Option + + #### curl + + curl -i "http://localhost:5001/api/v0/refs?arg=QmW2WQi7j6c7UgJTarActp7tDNikE4B2qXtFCfLPdsgaTQ&edges" + + + Body + + ``` + curl -i "http://localhost:5001/api/v0/refs?arg=QmW2WQi7j6c7UgJTarActp7tDNikE4B2qXtFCfLPdsgaTQ&edges" + ``` + ++ Response 200 + + + Headers + + ``` + Content-Type: application/json + Trailer: X-Stream-Error + Transfer-Encoding: chunked + X-Chunked-Output: 1 + Date: Fri, 05 Feb 2016 17:37:42 GMT + Transfer-Encoding: chunked + ``` + + + Attributes (ndjson) + - Ref (string) + - Err (string) + + + Body + + ``` + { + "Ref": "QmW2WQi7j6c7UgJTarActp7tDNikE4B2qXtFCfLPdsgaTQ -\u003e Qmd286K6pohQcTKYqnS1YhWrCiS4gz7Xi34sdwMe9USZ7u", + "Err": "" + } + ``` + ++ Request With Argument And Recursive Option + + #### curl + + curl -i "http://localhost:5001/api/v0/refs?arg=QmW2WQi7j6c7UgJTarActp7tDNikE4B2qXtFCfLPdsgaTQ&recursive" + + + Body + + ``` + curl -i "http://localhost:5001/api/v0/refs?arg=QmW2WQi7j6c7UgJTarActp7tDNikE4B2qXtFCfLPdsgaTQ&recursive" + ``` + ++ Response 200 + + + Headers + + ``` + Content-Type: application/json + Trailer: X-Stream-Error + Transfer-Encoding: chunked + X-Chunked-Output: 1 + Date: Fri, 05 Feb 2016 17:39:22 GMT + Transfer-Encoding: chunked + ``` + + + Attributes (ndjson) + - Ref (Multihash) + - Err (string) + + + Body + + ``` + { + "Ref": "Qmd286K6pohQcTKYqnS1YhWrCiS4gz7Xi34sdwMe9USZ7u", + "Err": "" + } + { + "Ref": "QmPEKipMh6LsXzvtLxunSPP7ZsBM8y9xQ2SQQwBXy5UY6e", + "Err": "" + } + { + "Ref": "QmT8onRUfPgvkoPMdMvCHPYxh98iKCfFkBYM1ufYpnkHJn", + "Err": "" + } + ``` + +## local [GET /refs/local] + +Lists all local references. + +Displays the hashes of all local objects. + +#### Bugs + + - The `format` option has no effect on the output. + - If an argument is included, an `invalid ipfs paths ref` error is thrown, + although there is no possible valid ipfs paths ref. + ++ Request + + #### curl + + curl -i http://localhost:5001/api/v0/refs/local + + + Body + + ``` + curl -i http://localhost:5001/api/v0/refs/local + ``` + ++ Response 200 + + + Headers + + ``` + Content-Type: text/plain + Trailer: X-Stream-Error + Transfer-Encoding: chunked + X-Stream-Output: 1 + Date: Fri, 05 Feb 2016 17:46:36 GMT + Transfer-Encoding: chunked + ``` + + + Attributes (string) + - (Multihash) - Newline delimited multihashes + + + Body + + ``` + QmNLjhs2cWVGopVTE5KqCZBdX7TE6i9AU1y8pwytt7cyzC + QmNLwdgyRiTuMf9M3Fjtu2TpMjz2CgZS4YgeuqjLHv3rjq + ``` + ## local # Group repo From 5a9406dd93aa109d0191d5f9cca6f24c212f0302 Mon Sep 17 00:00:00 2001 From: Richard Littauer Date: Wed, 17 Feb 2016 13:52:54 -0500 Subject: [PATCH 2/5] Removed errant curl, added period --- apiary.apib | 5 +---- 1 file changed, 1 insertion(+), 4 deletions(-) diff --git a/apiary.apib b/apiary.apib index da793f8..a4ce087 100644 --- a/apiary.apib +++ b/apiary.apib @@ -4464,10 +4464,7 @@ Retrieves the object named by and displays the link hashes it contains. ## refs [GET /refs{?arg}{&format,edges,unique,recursive}] -Lists links (references) from an object - -#### curl - curl -i http://localhost:5001/api/v0/refs?arg=/ipfs/QmW2WQi7j6c7UgJTarActp7tDNikE4B2qXtFCfLPdsgaTQ/cat.jpg +Lists links (references) from an object. + Parameters + arg (string, required) - Path to the object or objects to list refs from. From 34b08504056425f5edf33fe9bbf8a7227627ab23 Mon Sep 17 00:00:00 2001 From: Richard Littauer Date: Wed, 2 Mar 2016 18:02:22 -0500 Subject: [PATCH 3/5] Update given go-ipfs#2366 --- apiary.apib | 5 +++-- 1 file changed, 3 insertions(+), 2 deletions(-) diff --git a/apiary.apib b/apiary.apib index a4ce087..0a9ae7f 100644 --- a/apiary.apib +++ b/apiary.apib @@ -4460,8 +4460,9 @@ trip latency information. # Group refs -Retrieves the object named by and displays the link -hashes it contains. +Displays the link hashes an IPFS or IPNS object(s) contains, with the following format: + + ## refs [GET /refs{?arg}{&format,edges,unique,recursive}] Lists links (references) from an object. From cf91a39e1b00fd12c18d66ad4631da96e39478a7 Mon Sep 17 00:00:00 2001 From: Richard Littauer Date: Tue, 19 Apr 2016 10:13:46 -0400 Subject: [PATCH 4/5] Removed format option --- apiary.apib | 45 --------------------------------------------- 1 file changed, 45 deletions(-) diff --git a/apiary.apib b/apiary.apib index 0a9ae7f..0c87a24 100644 --- a/apiary.apib +++ b/apiary.apib @@ -4469,7 +4469,6 @@ Lists links (references) from an object. + Parameters + 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: ` -> `. Alias: e. + unique (boolean, optional) - Omit duplicate refs from output. Alias: u. + recursive (boolean, optional) - Recursively list links of child nodes. Alias: r. @@ -4615,44 +4614,6 @@ Lists links (references) from an object. } ``` -+ Request With Argument And Format Option - - #### curl - - curl -i "http://localhost:5001/api/v0/refs?arg=QmW2WQi7j6c7UgJTarActp7tDNikE4B2qXtFCfLPdsgaTQ&format=" - - + Body - - ``` - curl -i "http://localhost:5001/api/v0/refs?arg=QmW2WQi7j6c7UgJTarActp7tDNikE4B2qXtFCfLPdsgaTQ&format=" - ``` - -+ Response 200 - - + Headers - - ``` - Content-Type: application/json - Trailer: X-Stream-Error - Transfer-Encoding: chunked - X-Chunked-Output: 1 - Date: Fri, 05 Feb 2016 17:36:20 GMT - Transfer-Encoding: chunked - ``` - - + Attributes (ndjson) - - Ref (string) - - Err (string) - - + Body - - ``` - { - "Ref": "cat.jpg", - "Err": "" - } - ``` - + Request With Argument And Edge Option #### curl @@ -4743,12 +4704,6 @@ Lists all local references. Displays the hashes of all local objects. -#### Bugs - - - The `format` option has no effect on the output. - - If an argument is included, an `invalid ipfs paths ref` error is thrown, - although there is no possible valid ipfs paths ref. - + Request #### curl From 57ffc5a14ce52de4b8ffaaec2f12af696162ebb0 Mon Sep 17 00:00:00 2001 From: Richard Littauer Date: Tue, 19 Apr 2016 10:13:51 -0400 Subject: [PATCH 5/5] Update headers --- apiary.apib | 38 +++++++++++++++++++++++++------------- 1 file changed, 25 insertions(+), 13 deletions(-) diff --git a/apiary.apib b/apiary.apib index 0c87a24..a082b38 100644 --- a/apiary.apib +++ b/apiary.apib @@ -4490,7 +4490,7 @@ Lists links (references) from an object. + Headers ``` - Date: Fri, 05 Feb 2016 17:30:09 GMT + Date: Tue, 19 Apr 2016 14:12:30 GMT Content-Length: 32 Content-Type: text/plain; charset=utf-8 ``` @@ -4524,10 +4524,12 @@ Lists links (references) from an object. + Headers ``` + Access-Control-Allow-Headers: X-Stream-Output, X-Chunked-Output, X-Content-Length + Access-Control-Expose-Headers: X-Stream-Output, X-Chunked-Output, X-Content-Length Content-Type: application/json + Server: go-ipfs/0.4.1-dev Trailer: X-Stream-Error - Transfer-Encoding: chunked - Date: Fri, 05 Feb 2016 17:30:51 GMT + Date: Tue, 19 Apr 2016 14:12:20 GMT Transfer-Encoding: chunked ``` @@ -4561,11 +4563,13 @@ Lists links (references) from an object. + Headers ``` + Access-Control-Allow-Headers: X-Stream-Output, X-Chunked-Output, X-Content-Length + Access-Control-Expose-Headers: X-Stream-Output, X-Chunked-Output, X-Content-Length Content-Type: application/json + Server: go-ipfs/0.4.1-dev Trailer: X-Stream-Error - Transfer-Encoding: chunked X-Chunked-Output: 1 - Date: Fri, 05 Feb 2016 17:31:52 GMT + Date: Tue, 19 Apr 2016 14:12:09 GMT Transfer-Encoding: chunked ``` @@ -4593,11 +4597,13 @@ Lists links (references) from an object. + Headers ``` + Access-Control-Allow-Headers: X-Stream-Output, X-Chunked-Output, X-Content-Length + Access-Control-Expose-Headers: X-Stream-Output, X-Chunked-Output, X-Content-Length Content-Type: application/json + Server: go-ipfs/0.4.1-dev Trailer: X-Stream-Error - Transfer-Encoding: chunked X-Chunked-Output: 1 - Date: Fri, 05 Feb 2016 17:33:49 GMT + Date: Tue, 19 Apr 2016 14:11:59 GMT Transfer-Encoding: chunked ``` @@ -4631,11 +4637,13 @@ Lists links (references) from an object. + Headers ``` + Access-Control-Allow-Headers: X-Stream-Output, X-Chunked-Output, X-Content-Length + Access-Control-Expose-Headers: X-Stream-Output, X-Chunked-Output, X-Content-Length Content-Type: application/json + Server: go-ipfs/0.4.1-dev Trailer: X-Stream-Error - Transfer-Encoding: chunked X-Chunked-Output: 1 - Date: Fri, 05 Feb 2016 17:37:42 GMT + Date: Tue, 19 Apr 2016 14:11:46 GMT Transfer-Encoding: chunked ``` @@ -4669,11 +4677,13 @@ Lists links (references) from an object. + Headers ``` + Access-Control-Allow-Headers: X-Stream-Output, X-Chunked-Output, X-Content-Length + Access-Control-Expose-Headers: X-Stream-Output, X-Chunked-Output, X-Content-Length Content-Type: application/json + Server: go-ipfs/0.4.1-dev Trailer: X-Stream-Error - Transfer-Encoding: chunked X-Chunked-Output: 1 - Date: Fri, 05 Feb 2016 17:39:22 GMT + Date: Tue, 19 Apr 2016 14:11:36 GMT Transfer-Encoding: chunked ``` @@ -4721,11 +4731,13 @@ Displays the hashes of all local objects. + Headers ``` + Access-Control-Allow-Headers: X-Stream-Output, X-Chunked-Output, X-Content-Length + Access-Control-Expose-Headers: X-Stream-Output, X-Chunked-Output, X-Content-Length Content-Type: text/plain + Server: go-ipfs/0.4.1-dev Trailer: X-Stream-Error - Transfer-Encoding: chunked X-Stream-Output: 1 - Date: Fri, 05 Feb 2016 17:46:36 GMT + Date: Tue, 19 Apr 2016 14:11:14 GMT Transfer-Encoding: chunked ```