Skip to content
This repository has been archived by the owner on Apr 29, 2020. It is now read-only.

Added more documentation #13

Closed
wants to merge 37 commits into from
Closed

Added more documentation #13

Changes from 1 commit
Commits
Show all changes
37 commits
Select commit Hold shift + click to select a range
2ec619e
Added Group add
RichardLitt Dec 14, 2015
4efdaf8
Added block put
RichardLitt Dec 14, 2015
99aba1c
Added config
RichardLitt Dec 14, 2015
e870bf2
Added ipfs daemon
RichardLitt Dec 14, 2015
438dd5d
Added dht
RichardLitt Dec 14, 2015
55eaa43
Added ipfs file
RichardLitt Dec 15, 2015
f11186d
Added ipfs get
RichardLitt Dec 15, 2015
e02fe5e
Filled out ipfs id
RichardLitt Dec 15, 2015
b6da282
Added in args to calls
RichardLitt Dec 15, 2015
99b4397
Added ipfs log
RichardLitt Dec 15, 2015
51b7ec2
Added ipfs ls
RichardLitt Dec 15, 2015
8f5337a
Added content to mount
RichardLitt Dec 15, 2015
4089955
Added ipfs name as much as possible
RichardLitt Dec 15, 2015
3804212
Added ipfs object
RichardLitt Dec 15, 2015
096a0d3
Added `ipfs pin` group
RichardLitt Dec 15, 2015
729117b
Added options and args to ipfs ping
RichardLitt Dec 15, 2015
71e5f60
Added `ipfs refs`
RichardLitt Dec 15, 2015
633ebdb
Added params to resolve
RichardLitt Dec 15, 2015
1001645
Added params to stats bw
RichardLitt Dec 15, 2015
f3d47ae
Added content to ipfs swarm
RichardLitt Dec 15, 2015
1e6dc95
Added `ipfs tar`
RichardLitt Dec 15, 2015
8e1d586
Added params to version
RichardLitt Dec 15, 2015
2e59d1a
Linted according to API doc
RichardLitt Dec 16, 2015
a2369ce
Remove test file
RichardLitt Dec 16, 2015
291bcb7
Changed nullable to string, nullable
RichardLitt Dec 16, 2015
266d53d
Single quotes to backticks
RichardLitt Dec 16, 2015
01123a5
Update add with new curl result
RichardLitt Dec 26, 2015
b10cde3
Using a data structure for error messages
RichardLitt Dec 26, 2015
99a336e
Remove CLI docs
RichardLitt Dec 26, 2015
02ee57e
Added example curl requests
RichardLitt Dec 26, 2015
afc33e5
Filled out block/put example
RichardLitt Dec 26, 2015
425f737
Added curl and headers and 500 to config/replace
RichardLitt Dec 26, 2015
dcfe5be
Spelling
RichardLitt Dec 26, 2015
13ff0c9
Remove cli speak
RichardLitt Dec 26, 2015
40ad96e
Update refs with better responses
RichardLitt Dec 26, 2015
8c64bec
Edited dredd.yml to match @Dignifiedquire
RichardLitt Dec 27, 2015
d91fba0
Filled out the ipfs add further
RichardLitt Jan 8, 2016
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
36 changes: 34 additions & 2 deletions apiary.apib
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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 <path> 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
Copy link

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

We might want to indicate that there can be multiple arg values to add multiple files in one request

Copy link

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@mappum Excuse me, I realize this is OT for here, but just a brief inquiry, do you have a status or roadmap for Mercury?

Copy link

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@ABISprotocol Not sure why you're bringing that up here. My email address is on my profile, feel free to contact me there. 😄

+ 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
Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Not sure how to add shortcuts we use here, like -r for --recursive. Should I put them in the desc?

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

good question. desc works? not sure. others' thoughts?

Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Is there actually a need to have these shortcuts working/documented in the http api? Or should they simply be a bonus specific to the cli?

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I don't think we need them.

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

let's make the alias be only available through the CLI :)

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

👍


+ Response 200 (text/plain)
Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I was unable to get "http://127.0.0.1:5001/api/v0/add?arg=/Users/richard/test" to work on Postman, so I honestly am not sure if this is the right response of not. It's what I get in the CLI, though.

Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Path to a file will not work from http api, you have to send the file content via multipart if you want to add something via http

Copy link

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

If you need to test adds in Postman, you can use the form-data body Content-Type, set a non-empty value for the key, and select 'File' instead of 'Text'.

In curl, you can do:

curl -F "file=@/some/file/path" http://localhost:5001/api/v0/add

Copy link

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

BTW, could be cool to show curl commands for all these methods, does apiary have any good places where we could put that?

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

There's no option to select File instead of Text if I am using a GET command. If I use a PUT or a POST, there is, but I just get a 403 - Forbidden back. Ideas?

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

We could include the curl command directly in the description, like this. I like it! What do you think? cc @dignifiedquire

# 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 <path> 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.

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

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Looks like this:
screenshot 2015-12-25 20 50 09

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

from @RichardLitt: There's no option to select File instead of Text if I am using a GET command. If I use a PUT or a POST, there is, but I just get a 403 - Forbidden back. Ideas?

That would be because no one (i.e Apiary) is expecting for a file to be sent in a GET request and all the other methods are blocked by CORS, if the headers are not set.


+ 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
Expand Down