Add semver to the HTTP-API

[daviddias]

We've been bitten many times by http-api changes, nuances that are only caught after release and it is hard to migrate every single API client(i.e, every single time.

There are some things we should do, as we talked about it, to mitigate some of these problems, like: run every api client tests against a new version of go-ipfs in pre-release, however that is not enough, as there is currently no way for an API client to tell if a go-ipfs version has changed and to notify the user that they should also upgrade their api-client. One more thing is that the http-api is consumable by itself, so any breaking change, even if the api clients are updated, is still a breaking change in user-space.

My proposal to solve this issue comes in the form of:

• We have to start using semver for the API - currently we have v0 on the api, but that is completely ignored
• We have to have http-api tests and make them run over the several versions of the http-api
• Have a way to support describe an API endpoint as 'stable', 'not stable' and deprecated.
• Have a way to phase out old versions of the http-api.

Let's chat about this Monday.

[jbenet]

I agree with much of what you say above.

The one thing I disagree with is the approach to semver -- I am strongly opposed to getting semver-major-upgrade-happy with the api. The reason the api is at v0 is that it is still getting figured out, it is NOT our v1.0.0 api, which should ship with ipfs v1.0 and should be dependable by our users, for years without any breaking change. If the intention here is to start bumping major, no, i am strongly opposed to that. That's a recipe for a mess of versions.

When people start bumping semver majors, they get super break-happy. We don't want to end up with api v41.1.2 soon and force people to deal with 40 different major versions, the ridiculous madness that would be in clients, bindings, scripts, and so on. Debugging will be a nightmare for users. Contrast this with Github itself, the inventors of semver, who are at their API's v3, have changed it only twice, and both of those times were serious upgrade moments with tons of effort and care to make sure no one was caught by surprise.

As Tom Preston-Warner says in the semver spec: be responsible about versions:

This is a question of responsible development and foresight. Incompatible changes should not be introduced lightly to software that has a lot of dependent code. The cost that must be incurred to upgrade can be significant. Having to bump major versions to release incompatible changes means you’ll think through the impact of your changes, and evaluate the cost/benefit ratio involved.

I predict right now that if we just add semver into APIs without a significant and strong rejection of userland breaking changes, then we will end up with huge major version numbers in no time.

My basic statement in all of this is, again: don't break user space. Just don't do it. Sometimes it is absolutely necessary, but those cases are very, very rare, and i want to hear about each of them personally and be involved in that decision. (Most of the time i will say no).

[jbenet]

That the API is in a very messy state now is orthogonal to the approach here. You can introduce new routes and deprecate older ways of doing things without breaking user space (bumping major).

[daviddias]

I'm also from the school of thought that 1.0.0 is when something is defined as 'stable', which is not the case right now (first we would have to get to go-ipfs 1.0.0).

Right now, since we only have one version number (v0), we are unable to denote a sign of API change and also, let client libraries understand which path they can request that will be compatible with their implementation. I proposed semver so that we have the nice things of minor versions for breaking changes pre 1.0.0, but also be able to add new features or make small fixes that a previous api client can still work (patch versions)

[jbenet]

• Okay, let's do semver like that then. i just dont want to have an api with 40 versions. 😄