Hi all,
I’ve implemented a library in Scheme to interface with the HTTP API and during this time I gathered some doubts and possible improvements (to the docs mainly).
Integers
Firstly, I noticed that there are three different integer types in the docs: int, uint, and int64. From the point of view of an user of the HTTP API, are these really different?
For now I have implemented all three as the same type. I guess I should at least correctly check for non-negative-ness in the case of unsigned integers.
I read somewhere that these docs were automatically generated from somewhere, but I couldn’t find the source. If someone could point it out to me that would be great! 
pin/ls
When given a CID that is not pinned the server returns HTTP 500.
Is that right? Seems overkill to me.
cid/format
The v flag is supposed to be a CID version but is tagged as a string rather than an integer like in the other instances (that I’ve noticed). Is that right?
Strings rather than Arrays?
These are examples of where the docs suggest that some argument/flag can be used to specify several of something (like CIDs or keys), but where the type is string rather than array.
-
filestore/ls&filestore/verify: the CID argument. -
dht/provide: the keys argument. -
key/rm: the key(s?)’ names.
p2p/close
The response is really just a JSON string of an integer, like "123"?
Missing periods
These are instances where a period is missing between the argument/flag’s description proper, and the “Required: yes/no”. Very minor detail, but still…
-
urlstore/add: the path argument. -
dag/export&dag/get: their single argument. -
key/rename: the old and new name arguments. -
key/rm: the key(s?)’ names. -
swarm/peering/add&swarm/peering/rm: their single argument.
Other
And lastly, the argument’s description of objects/new has a redundant “Optional”.