Add versioned HTTP API

[dborovcanin]

Is your feature request related to a problem? Please describe.

As we approach 1.0, we should start thinking of versioning our API.

Describe the feature you are requesting, as well as the possible use case(s) for it.

While we will make the best effort to keep post-v1.0 API compatible, there is no guarantee that will be possible. For those reasons, we should add versioning to enable using old API and seamlessly switch to newer versions of Magistrala.

Indicate the importance of this feature to you.

Must-have

Anything else?

No response

[felixgateru]

I have encountered the following methods of versioning the api.

1. Header versioning - The version will be passed as a header in each request. We can implement chi middleware to extract the middleware version for further processing.
2. Query parameter versioning - The version number will be a query parameter. This can be extracted by handler logic.
3. URL versioning - the version number is in the url of the endpoint. This is naturally handled by chi routing.

In all the above we will require to maintain code for each version. The advantage and disadvantage being that we can maintain all the versions in parallel.

My recommendation would be for URL versioning, it seems more intuitive and user friendly. It would be easy to update documentation. Would be easier for proxying and caching.

[dborovcanin]

OK, let's go with URL path versioning. It is simple, explicit, and easy for developers to understand and implement, and also the most popular for those reasons. For the time being, let's just address the URL prefix. We will not move implementation under api/v1 package just yet, because we still have only v1 so grouping does not make sense now. However, the URL prefix is a must since it is a breaking change.

[dborovcanin]

Another point here is how the API version correlates to the code version? Do we keep separate modules/create wrapper packages, or determine API version from the version endpoint of the service? Should this be done on the deployment level (i.e. on ingress)? @felixgateru Please research this and write comments here.

[dborovcanin]

@felixgateru Please take this one.

[felixgateru]

Code organization

With implementing the URL versioning, the code can be organized in the following ways:

1. Seperate packages for the api and expanded service interface. The api packages will follow the following folder structure:

/api
	/v1
		/endpoints.go
		/transport.go
	/v2
		/endpoints.go
		/transport.go

Depending on how different the versions are, this would necessitate expansion of the service interface as well to include versioned methods. This would enable mainting older versions of methods and introduce new methods. There is the possibility of code duplication between versioned methods.
Shared logic can be stored in a common package.
This method may have the following advantages:

• The codebase would remain straightforward and easy to maintain with parallel development.
• Makes deprecating older versions simpler.

The biggest drawback would be code duplication even in the service.

2. Creating wrapper packages and middleware for shared logic.
   There would be middleware to handle version specific operations and reduce code duplication. Similar to the current authorization middleware we have. This would reduce code duplication. This would however be logical for small changes where the underlying service logic does not have large differences. Depending on the scale of the difference there may no reason for an expanded service interface with versioned methods.

The biggest drawback would be major changes would require refactoring code used by all the versions.

3. Versioning via Nginx or Proxy
   This would require maintaining seperate packages and possible a separate service.
   My biggest question with this if it is necessary given that all versions will run from the same service. I think this would be best utilized with different backend services.
   It can be used to direct unversioned traffic to a default version.

Links:

• https://www.xmatters.com/blog/blog-four-rest-api-versioning-strategies
• https://www.postman.com/api-platform/api-versioning/
• https://www.designgurus.io/answers/detail/what-are-the-best-practices-for-api-versioning-in-microservices
• https://github.com/kubernetes/kubernetes