http-api-spec.ng - Roadmap, Priorities and Discussions of where to take the HTTP API

[daviddias]

This issue is a follow up on last HTTP-API Sprint call, August 15.

tl;dr; The HTTP-API is one of the most common and used interfaces to interact with IPFS core, however, it has been historically a PITA to deal with and implement client libraries that work both in the browser and natively + that keep up to date with the evolution of API itself

Current issues

• There is no way to actual verify that the HTTP-API documentation still applies to the current state of go-ipfs
• There is no way to notify developers of client libraries, when does the HTTP-API changes and how did it change
• go-ipfs doesn't have a process to verify if the client libraries work before releasing

Discussions & Proposals to improve the HTTP-API and process

• a) Extract the sharness tests from the go-ipfs repo into a seperate repo (this would take out the CLI as well), so that we can throw those tests at other implementations.
• b) Generate tests from the spec itself to verify that go-ipfs and js-ipfs conform with what de spec defines
• c) RPC vs RESTful API - Research and understand if it is possible to have a full RPC API without compromising the browser use cases
• d) Add semver to the API

Priorities

• Get the go-ipfs batch of tests to be executable against other HTTP-API implementations (namely, the js-ipfs one)

Moar issues

• https://github.com/ipfs/specs/issues?q=is%3Aissue+is%3Aopen+label%3Ahttp-api
• https://github.com/ipfs/go-ipfs/issues?q=is%3Aissue+is%3Aopen+label%3Ahttp-api

[magik6k]

IIRC there was some API 2.0 discussion on the dev meeting in Glasgow/London. I don't know where the notes are, but it would be nice to link them here / write them down

[achingbrain]

I did a bunch of work related to improving the http api a while ago, the demo version is here (though needs a bit of love): https://github.com/ipfs-shipyard/ipfs-http

My approach was to use REST and not RPC because having worked with both, my experience of RPC is that it tends to be inflexible, reflects the conventions of the platform it's implemented against in terms of data types and procedure addressing and usually ends up with a very large API surface area, none of which we want.

[mikeal]

One thing you might struggle with in a more RESTful approach is how to efficiently send multiple blocks in a single response.

You may want to check out @rvagg’s work on zipcar, essentially just a zip-based container for IPLD blocks. There are implementations in js and go already.

[ianopolous]

One thing you might struggle with in a more RESTful approach is how to efficiently send multiple blocks in a single response.

Related discussion here for multiple blocks in a put request: ipfs/kubo#3667

[achingbrain]

One thing you might struggle with in a more RESTful approach is how to efficiently send multiple blocks in a single response.

This depends on how you define your resources, though it would be interesting to see if you'd get better performance by just making multiple requests in parallel because sending multiple blocks in a single response is ultimately going to be similar to sending them in series as the server can only send one byte at a time in a given response.

[lidel]

cc:

• docs: add files resource v1 spec: docs: add HTTP API v1 spec #224
• RPC over REST: RPC over REST #225