we should establish API versioning policy

[sameh-farouk]

Description

Some API changes/PRs, like this one, were delayed because they introduced breaking changes and needed some update plans for the clients as well. we shouldn't rely on updating the clients at the same time every time we introduce breaking changes as proper handling for such cases. also, we are not handling cases where there will be other clients that are not maintained by us.

The solution to this problem is to implement a versioning system in our API as Versioning is a crucial part of API design. It will give us the ability/flexibility to improve the API without the fear of breaking the client’s applications when new updates are rolled out. When the time of an upgrade is due, both old and new versions can coexist for a period of time. This period should allow client maintainers to smoothly change their code to use our latest version.

Implementation

There are many approaches to implementing API versioning. for our grid proxy API, versioning in the URI path is the most straightforward solution, IMO. a new version should be added only when the changes to the API would break existing clients' code, so we bundle those breaking changes into a new API version.

Also, it is important to define in advance how we will version our API (set a policy). something like:

• What goes into the Current version implementation? this is generally any changes that represent independent features that do not alter pre-existing logic.
• when to release a minor API version? generally when the changes being introduced are considered backward compatible, i.e. additive changes.
• when to release a major API version? generally when any of the changes being introduced are backward incompatible. In this case, we would Add a new major version.
• support timelines and deprecation TBD

[sameh-farouk]

it is necessary to keep a record of all changes to the API and the versions that are related to each new addition in API changelog documents.

[Omarabdul3ziz]

these should be part of this story:

• https://github.com/threefoldtech/tfgrid-sdk-go/issues/52
• https://github.com/threefoldtech/tfgrid-sdk-go/issues/55