Bitswap wantlist API #5077
Comments
|
This is probably a bug in docs generator as the output type is defined as and in go |
|
Thanks @magik6k for the code pointers. My question is why does it override 'standard' json serialization? IPLD is a much higher 'protocol' than bitswap. Bitswap deals with blocks and CIDs. |
|
If that’s the right output (so we don’t want to change it), it seems like we need to add a special case in the docs generator. Anybody know if there are other types that need special casing like this? |
|
@Mr0grog I really think that the documentation is correct and the API should just return the CIDs. Why make Bitwswap API consumers know about IPLD (which seems to be WIP)? |
Sure, it’s certainly “higher” than a set of routines concerned with trading bits, but the API isn’t bitswap. It’s data about bitswap, and IPLD is concerned with how you represent and parse data. On the other hand, I totally agree that it doesn’t seem especially useful that every instance of a CID in the API is formatted as a link (besides, a CID doesn’t even have to be formatted like (It also looks to me like this was really an unintended (?) consequence of trying to make it easier for CBOR to represent a link with just a CID, rather than differentiating the two concepts. I was surprised to realize that’s how it works last week.) From a more practical perspective, though, this has been the way the API has worked for over a year and it affects 9 API endpoints:
Seems like a very non-trivial change. I also think it’s worth considering that, as I learned during the docs research and heard repeatedly since then, the HTTP API docs are not widely considered a reliable or especially useful reference. |
|
I didn’t mean to derail this discussion entirely! If this is still worth discussing, @richardschneider, we certainly should. I just wanted to make sure we understand the scope when making decisions on this. |
Cid objects always serialize to JSON as `{"/": "<cid string>"}` (https://github.com/ipfs/go-cid/blob/078355866b1dda1658b5fdc5496ed7e25fdcf883/cid.go#L407-L415). There's no obvious way to detect what any type's serialization behavior might be, so we need a special case explicitly for CIDs here.
Also specially calls out Multiaddrs. It doesn't appear that we have any other interfaces or pointer types besides these two that wind up in response schemas. I don't know that string checking on the type is really the best way to do this, but it seemed expendient and avoids needing to depend on CID and Multiaddr packages and make sure they stay in sync with the version of IPFS we are working against.
There is also some discussion here (ipfs/kubo#5077) on whether this is the right formatting for CIDs. For now, I'm including it here because I heard plenty of complaints about the usefulness and accuracy of these docs from users. The output of this tool is preceived as documentation and not a spec, so I think it's right that it shows what IPFS actually *does,* not just what we think it *ought* to. (If we wanted this to be more like a spec, we need a way to annotate it for users to explain the difference between implementation and spec.)
License: MIT
Signed-off-by: Rob Brackett <[email protected]>
According to the docs
/api/v0/bitswap/wantlistreturnsKeyswhich is an array of string. I assume that the string is either a CID or a block's multihash.However,
Keysis actually an array of objects, with I think is an IPLD linkIt should return something like
The text was updated successfully, but these errors were encountered: