HTTP Documentation is lacking


I’m trying to understand the Response types given by the HTTP API.

While the Response type is defined, what the fields actually contain is not. In some cases its obvious what the values will be, but in others I have no idea.

Can the API documentation be augmented with comments explaining the fields?

I see there’s an older similar thread, Are these seriously the docs?
which ended with the OP creating an issue for this, but it has received zero attention.

As an example, HTTP API | IPFS Docs. There are multiple peer-id fields, a field called “Extra” (?), and a Responses nested inside of Response.

What are these fields supposed to contain? Some fields are also nested in angled brackets – does this indicate they’re arrays?

For the DHT provide objects, you can see:

The response object is of routing.QueryEvent type. Depending on the type of query, the Extra is used for one thing or another (i.e. to contain the Value or an Error message).

Looking at the code in core/commands is the best way to obtain information.


Thanks for the reply. I’m quite sad its “read the code”.

Going through the code in core/commands for dht.provide reveals little about what to expect from a QueryEvent. At least to me – I’m not a Go pro.

The command itself only forms QueryEvent events for any errors that occur. Otherwise the happy-path QueryEvents are simply re-emitted from whatever machinery drives the DHT internally (I think?). And this one cannot follow from the code since its hidden behind interfaces. There are also no comments or hints to follow.

Or maybe I’m misunderstanding and the response only contains any errors that may have occurred? And for the happy path there is no inner responses?

I think the dht code will emit events as thing happen.

You can grep for them here but I think you can see from the printEvent function the kind of events you can get:

  • when sending query to a peer, ID will be the ID of that peer ID
  • when getting a Value after a lookup, Extra will contain the value.
  • When getting a PeerResponse (I can only imagine this is querying a peer for other closest peers), the ID is the peer ID of the queried peer, and the Responses array contains the peer IDs (AddrInfos) of those peers.
  • When a QueryError happens, Extra contains the reason.
  • When dialing a peer, ID contains the peer ID that you are dialing to.
  • FinalPeer events are issued in this file to after GetClosestPeer queries, which IDs being those of the peers.
  • I don’t see AddingPeer events being issued anywhere.

While it is not good excuse for not having better docs, the dht subcommands in go-ipfs are also not the hot-path and mostly there for ipfs developers and advanced users. Hopefully I’m helping you to become one!

Ah thanks that helped a lot.

The js-ipfs gives this example for dht.provide:

js example
  extra: 'dial backoff',
  id: 'QmWtewmnzJiQevJPSmG9s8aC7yRfK2WXTCdRc1pCbDFu6z',
  responses: [
      addrs: [
      id: 'QmRz5Nth4jTFuJJKcjyb6uwvrhxWbruRvamKY2PJxwJKw8'
  type: 1

so would this be a fair interpretation of the fields:

  "Extra": "<string>",  // any extra info
  "ID": "<peer-id>",    // ID of peer queried (i.e. node sending this response)
   // List of peers we also "put" the value on? 
   // Other known peers also providing this value?
   // k-Peers closest to the CID to be provided?
  "Responses": [        
      // multi-addr of peer[i]
      "Addrs": [
      // ID of peer[i]
      "ID": "peer-id"
  // Response type; can be error, peer-response, etc. 
  // Defined inside go-code somewhere :(
  "Type": "<int>"

Now its also possible for dht.provide to have multiple CIDs in the request. So then I’m really not sure what this would look like for a response.

Probably get one of object per peer. Try it out?