We should discuss the versioning of the RESTful backends to ensure a consistent and backwards compatible API for our endusers, as well as a general contract for our development iterations.
So, the plan is following:
We use (semi-)semantic versioning and use the major version to embed the API version in the URL.
It will look like this: back.end/v1/some/endpoint
v1 means we are calling API 1.0.0 - 1.x.x - these versions are forced to be backwards compatible.
v2 would be the API version 2.0.0 - 2.x.x - it doesn't has to be compatible with v1, but with all v2 versions instead.
The endpoints we create for each API versions will be discussed before we start a new development iteration. As soon as we created a full set of implementable features, we freeze the declaration for the API version and start actually implementing the discussed endpoints.
While the major version declares the API version itself, the minor and patch version just provides security updates, performance improvements and bugfixes - no new features or other non-backwards-compatible things.
Well, how to find out which API version is in use?
This will be done by using some "global" endpoints, which are the only endpoints that doesn't follow the pattern above.
These global endpoints will be discussed together with the first iteration (v1).
There will probably be only 2 to 5 of these global endpoints.
Global Endpoints don't require encryption on any side.
Their most probable use will be things like providing the public RSA key of the backend,
some informations about the software & system and, of course, the available API versions.
jens1o
commented
6 years ago
We should discuss the versioning of the RESTful backends to ensure a consistent and backwards compatible API for our endusers, as well as a general contract for our development iterations.
So, the plan is following:
We use (semi-)semantic versioning and use the major version to embed the API version in the URL. It will look like this: back.end/v1/some/endpoint
v1 means we are calling API 1.0.0 - 1.x.x - these versions are forced to be backwards compatible. v2 would be the API version 2.0.0 - 2.x.x - it doesn't has to be compatible with v1, but with all v2 versions instead.
The endpoints we create for each API versions will be discussed before we start a new development iteration. As soon as we created a full set of implementable features, we freeze the declaration for the API version and start actually implementing the discussed endpoints.
While the major version declares the API version itself, the minor and patch version just provides security updates, performance improvements and bugfixes - no new features or other non-backwards-compatible things.
Well, how to find out which API version is in use? This will be done by using some "global" endpoints, which are the only endpoints that doesn't follow the pattern above.
These global endpoints will be discussed together with the first iteration (v1). There will probably be only 2 to 5 of these global endpoints. Global Endpoints don't require encryption on any side.
Their most probable use will be things like providing the public RSA key of the backend, some informations about the software & system and, of course, the available API versions.
@jens1o Any additions?