Support multiple versions of the same API #202
Merged
Conversation
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This gives us the capability of making backwards-compatible updates to a system in production, which in turn reduces the pressure to get all of our APIs perfect before a launch. If we want to remove a problematic endpoint or make backwards-incompatible changes after release, we can release a new major version of the API with those changes, and continue to serve the old version under a version prefix. We can tell existing clients to point at the old version of the API, so they can continue to run for some period of time before updating their software. This also allows us to do hotfixes in production. For example, suppose there is some bug which we cannot fix without a breaking change to the API. We can add a new route with a `/hotfix` prefix or suffix. Only the affected clients need to change their code to use the hotfix endpoint. In the next major version, the hotfix endpoint can replace the original. Note that we can add new methods and make other backwards-compatible changes with only a minor version bump, which can replace the existing API instead of deploying a new version. Closes #185
Surf does not handle redirects correctly: it ends up sending the same request multiple times _after_ the redirect, which is problematic for methods with side-effects.
The rationale is that now a base URL like `https://hostname/v1` can be passed into a client service, which can then access multiple API modules from that URL, as long as all the modules support v1. Different modules are still allowed to support different versions, but this is not the common case. This makes request parsing and routing a bit more complicated, but things are greatly simplified by using a middleware to handle version redirects. Now all the redirect code is isolated and separate from the actual logic of handling routes.
nyospe
approved these changes
Mar 27, 2024
| @@ -683,7 +684,12 @@ pub fn app_api_path(org_name: &str, app_name: &str) -> PathBuf { | |||
| pub async fn wait_for_server(url: &Url, retries: u64, sleep_ms: u64) { | |||
| let dur = Duration::from_millis(sleep_ms); | |||
| for _ in 0..retries { | |||
| if surf::connect(url).send().await.is_ok() { | |||
| if reqwest::Client::new() | |||
There was a problem hiding this comment.
👍 for reqwest. If it wasn't for WebSocket support, I'd petition for replacing our other uses of surf as well.
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
This gives us the capability of making backwards-compatible updates
to a system in production, which in turn reduces the pressure to get
all of our APIs perfect before a launch.
If we want to remove a problematic endpoint or make backwards-incompatible
changes after release, we can release a new major version of the API with
those changes, and continue to serve the old version under a version prefix.
We can tell existing clients to point at the old version of the API, so they
can continue to run for some period of time before updating their software.
This also allows us to do hotfixes in production. For example, suppose there
is some bug which we cannot fix without a breaking change to the API. We can
add a new route with a
/hotfixprefix or suffix. Only the affected clientsneed to change their code to use the hotfix endpoint. In the next major version,
the hotfix endpoint can replace the original.
Note that we can add new methods and make other backwards-compatible changes
with only a minor version bump, which can replace the existing API instead
of deploying a new version.
Closes #185