How to check for backwards compatibility?

[Stezido]

Summary 💡

Trubudget should be able to handle older versions of Trubudget.
How can we ensure backwards compatibility when implementing a new feature.
Our api provides an api version property with each endpoint.
When these api version do increase?
Is there a documentation?

[daniel-arnauer]

There are many different ways to have different API versions.
A good practice: If we change an API Call with breaking changes, the entire API (all API routes) should get a new version number.
Another practice: set the version in the name of the API route (for instance user.listv2).

But since we only have the Front-end that depends on the API, versions are not really necessary because any changes that are done to the API will also be applied to the Front-end immediately

[daniel-arnauer]

There are already issues that relates to breaking changes for the API:
#59
#101

[Stezido]

I agree to the mentioned practices. The task here is to find out how Trubudget handles a version upgrade right now. I think the api version property is for new formats of an specific api endpoint request/response. So if Trubudget should change an api endpoint, the way to do that should be similar to following workflow:

1. Is it a breaking change (if no skip following tasks/ if yes continue)
2. Introduce the new request/response format for the endpoint and generate a new request/response version e.g. 2.0.
3. All 2.0 endpoints should be disabled until a new major version is released. With publishing a major version change all new request/response versions are supported and enabled.

There is no documentation how to handle a new version of an endpoint yet.

I disagree to the part that versions are not necessary. backwards compatibility- Trubudget wants to support older components. It's true that the changes will be applied to both frontend and api within one release but what if the api of a live system can be upgraded but the frontend stays on the same version as before?

[daniel-arnauer]

The API version property apiVersion is not yet used. This can be used to route in the domain layer to different service layers, depending on the apiVersion. I would also go with this.
The other, more easy but more dirty version is to put a v2 into the name of the route. The slack API uses this pattern, e.g.
https://api.slack.com/methods/oauth.v2.access

Why should 2.0 endpoints be disabled until next major release?