Skip to content

📝 Document backwards compatibility #4457

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 5 commits into from
Jul 6, 2023
Merged

📝 Document backwards compatibility #4457

Changes from 2 commits
Commits
Show all changes
5 commits
Select commit Hold shift + click to select a range
a0feb4c
first attempt at documenting backwards compatibility
bisgaard-itis Jul 4, 2023
1206960
add section on backwards compatibility
bisgaard-itis Jul 4, 2023
bf7b4ac
add icons for lengend
bisgaard-itis Jul 5, 2023
2c57d96
small fix
bisgaard-itis Jul 5, 2023
779fcbe
merge master into document-backwards-compatibility
bisgaard-itis Jul 6, 2023
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
31 changes: 31 additions & 0 deletions services/api-server/README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -36,6 +36,37 @@ will start the api-server in development-mode together with a postgres db initia
- http://127.0.0.1:8000/docs: redoc documentation
- http://127.0.0.1:8000/dev/docs: swagger type of documentation

## Backwards compatibility of the server API
The public API is required to be backwards compatible in the sense that a [client](https://github.com/ITISFoundation/osparc-simcore-clients) which is compatible with API version `N` should also be compatible with version `N+1`. Because of this, upgrading the server should never force a user to upgrade their client: The client which they have is already compatible with the new server. Note that

```mermaid

flowchart LR
subgraph Client
direction LR
A2(dev branch) .-> B2(master) .-> C2(staging) .-> D2(production)
A2(dev branch) ==> B2(master) ==> C2(staging) ==> D2(production)
end
subgraph Server
direction LR
A1(dev branch) ~~~ B1(master) ~~~ C1(staging) ~~~ D1(production)
A1(dev branch) ==> B1(master) ==> C1(staging) ==> D1(production)
end

A1 .-> A2
B1 .-> B2
C1 .-> C2
D1 .-> D2

A2 ~~~ A1
B2 ~~~ B1
C2 ~~~ C1
D2 ~~~ D1

```
In this diagram the development workflow/progress is indicated with full arrows both for the server client (`dev branch`->`master`->`staging`->`production`). To see which client version a given server version is compatible with one can follow the dotted arrows from that server version. E.g. one sees that the server in `staging` is compatible with the client in `staging` and in `production`. Needless to say, to see which versions of the server a given client is compatible with one can follow the dotted lines backwards from the client version. E.g. the client in `master` is seen to be compatible with ther server versions in `master` and in `dev branch`.


## References

- [Design patterns for modern web APIs](https://blog.feathersjs.com/design-patterns-for-modern-web-apis-1f046635215) by D. Luecke
Expand Down