From b5f4f04800e81c92095ac51f93960eee3401c40b Mon Sep 17 00:00:00 2001 From: Richard Littauer Date: Sat, 6 Feb 2016 18:19:14 -0500 Subject: [PATCH 1/2] Added Group `file` --- apiary.apib | 156 +++++++++++++++++++++++++++++++++++++++++++++++++++- 1 file changed, 155 insertions(+), 1 deletion(-) diff --git a/apiary.apib b/apiary.apib index f9c5037..4e44c45 100644 --- a/apiary.apib +++ b/apiary.apib @@ -981,7 +981,161 @@ Outputs the list of peers that were removed. # Group file -## ls +Interact with IPFS objects representing Unix filesystems. + +This provides a familiar interface to file systems represented +by IPFS objects, which hides IPFS implementation details like layout +objects (e.g. fanout and chunking). + +This command can't be called directly. + +## 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 or objects to list links from + ++ Request Without Arguments + + #### curl + + curl -i "http://localhost:5001/api/v0/file/ls" + + + Body + + ``` + curl -i "http://localhost:5001/api/v0/file/ls" + ``` + ++ Response 400 + + + Headers + + ``` + Date: Sat, 06 Feb 2016 23:13:03 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 the argument is invalid. For example: + + curl -i "http://localhost:5001/api/v0/file/ls?arg=kitten" + + #### curl + + curl -i "http://localhost:5001/api/v0/file/ls?arg=" + + + Body + + ``` + curl -i "http://localhost:5001/api/v0/file/ls?arg=" + ``` + ++ Response 500 + + + Headers + + ``` + Content-Type: application/json + Trailer: X-Stream-Error + Transfer-Encoding: chunked + Date: Sat, 06 Feb 2016 23:13:43 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/file/ls?arg=QmW2WQi7j6c7UgJTarActp7tDNikE4B2qXtFCfLPdsgaTQ" + + + Body + + ``` + curl -i "http://localhost:5001/api/v0/file/ls?arg=QmW2WQi7j6c7UgJTarActp7tDNikE4B2qXtFCfLPdsgaTQ" + ``` + ++ Response 200 + + + Headers + + ``` + Content-Type: application/json + Trailer: X-Stream-Error + Transfer-Encoding: chunked + Date: Sat, 06 Feb 2016 23:15:00 GMT + Transfer-Encoding: chunked + ``` + + + Attributes + + Argument (object) + - Key (Multihash) - Where 'Key' is the IPFS object's multihash + + Objects (object) + + Key (object) - Where 'Key' is the IPFS object's multihash + - Hash (Multihash) + - Size (number) + - Type (string) + - Links (array) + - (object) + - Name (string) + - Hash (Multihash) + - Size (number) + - Type (string) + + + Body + + ``` + { + "Arguments": { + "QmW2WQi7j6c7UgJTarActp7tDNikE4B2qXtFCfLPdsgaTQ": "QmW2WQi7j6c7UgJTarActp7tDNikE4B2qXtFCfLPdsgaTQ" + }, + "Objects": { + "QmW2WQi7j6c7UgJTarActp7tDNikE4B2qXtFCfLPdsgaTQ": { + "Hash": "QmW2WQi7j6c7UgJTarActp7tDNikE4B2qXtFCfLPdsgaTQ", + "Size": 0, + "Type": "Directory", + "Links": [ + { + "Name": "cat.jpg", + "Hash": "Qmd286K6pohQcTKYqnS1YhWrCiS4gz7Xi34sdwMe9USZ7u", + "Size": 443230, + "Type": "File" + } + ] + } + } + } + ``` # Group get From d155664773fe4d52cdd5711ccd04900b92f379d9 Mon Sep 17 00:00:00 2001 From: Richard Littauer Date: Wed, 17 Feb 2016 13:19:33 -0500 Subject: [PATCH 2/2] Small doc fixes See https://github.com/ipfs/go-ipfs/pull/2352 too --- apiary.apib | 12 ++++++------ 1 file changed, 6 insertions(+), 6 deletions(-) diff --git a/apiary.apib b/apiary.apib index 4e44c45..b8aba8b 100644 --- a/apiary.apib +++ b/apiary.apib @@ -990,17 +990,17 @@ objects (e.g. fanout and chunking). This command can't be called directly. ## ls [GET /file/ls{?arg}] -List directory contents for Unix-filesystem object +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 +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 or objects to list links from + + arg (string, required) - The path to the IPFS object or objects to list links from. + Request Without Arguments @@ -1099,9 +1099,9 @@ size is the IPFS link size. + Attributes + Argument (object) - - Key (Multihash) - Where 'Key' is the IPFS object's multihash + - Key (Multihash) - Where 'Key' is the IPFS object's multihash. + Objects (object) - + Key (object) - Where 'Key' is the IPFS object's multihash + + Key (object) - Where 'Key' is the IPFS object's multihash. - Hash (Multihash) - Size (number) - Type (string)