Add API versioning

[portainer]

Add API versioning

[kendrickm]

So based on reading some different blog posts, we will want to move all the current versions into a v1 namespace with the name prepended with a starting version. We could either use date+timestamps or just an incrementing number. Because of the global nature of development and use, spanning many time zones, I propose just incrementing a single int for the version number(1,2,3 etc) vs a timestamp.

If we want to be able to support older versions of the api(for bug fixes etc) we could add a - or _ in the version number(1-1 etc) or (1_1 etc)

The challenge with the first option (the hypen - ) is we can not name the go functions the same thing(ie browsePut1-1 is an invalid method name) so the function name would be slightly different then the api version, could be an underscore or no special character.

If instead we use an underscore(_) in the URL it creates URLs that could be harder to parse(some API libraries have shown issues parsing urls with _) but since we control the consumption of this API we it might be less of a problem.

Once the version scheme is decided, the next question is how much to scope into a version of the API.
Only the browse API is changing with v2, but I think we should support calls for v2 to other api's just for consistency, even if the other apis aren't changing.

So the changes required would be to rename all our existing browse API's to be V1 first.

ex func (handler *Handler) browsePut becomes func (handler *Handler) browsePutV1 etc

Then merge the changes from feat8-refactor-browse branch and name those functions latest, along with all other APIs in other packages besides browse.
ex in package http/handler/docker rename (handler *Handler) dockerOperation to (handler *Handler) dockerOperationLatest etc.

Then update the ServeHTTP method to strip v1 out of the URL and send any requests to the v1 functions. Also strip out v2 and then send any requests with v2(or no version) to the latest functions.

[deviantony]

If we want to be able to support older versions of the api(for bug fixes etc) we could add a - or _ in the version number(1-1 etc) or (1_1 etc)

I don't think we need this. If a bug is detected in a specific version of the API (and thus related to the agent, our instruction will be to simply update the agent to a version that includes the fix).

Version scheme v1, v2, vX ok for me.

Only the browse API is changing with v2, but I think we should support calls for v2 to other api's just for consistency, even if the other apis aren't changing.

Yes.

Then merge the changes from feat8-refactor-browse branch and name those functions latest, along with all other APIs in other packages besides browse.
ex in package http/handler/docker rename (handler *Handler) dockerOperation to (handler *Handler) dockerOperationLatest etc.

No need to append Latest to each handler, each handler without a version suffix should be considered the latest version of the handler.

We should start with a PR affecting the browse and agent API endpoints first, we'll review it and then go further with the whole API.

[deviantony]

In order to solve portainer/portainer#2364 I think that as a part of this work we should also introduce a new Header returned by all the agent responses that would include the current version of the Agent API.

This could be added next to the Agent version header: https://github.com/portainer/agent/blob/develop/http/server.go#L44