This page describes how to do versioning for your API and how to deploy to multiple versions.
Recommendations for managing API versions
In managing your API versions, consider these recommendations:
- When you want to introduce an incremental, but non-breaking change, keep the API version constant and deploy over the existing API.
- When you introduce a breaking change to your API, increment the API version.
- For additional protection, increment the App Engine app version as well and then deploy the new API version to that new App Engine app version. This lets you use the built-in flexibility of App Engine to quickly switch between App Engine versions and serve from the old working versions if you run into unexpected problems.
The following table is an illustration of cascading backend API versions to different App Engine app versions:
|App Version||backend API version|
As shown in the table, incremental, non-breaking updates to v1 of the API are rolled out, each overwriting the previous version. When breaking changes are introduced, the API version is incremented to v2 and it is deployed to a new App Engine app version. That allows you to switch back to the previous app version if needed.
In the table, notice that app version 2 supports both the latest v1 version
and the new v2 version of your API. If you don't delete the existing v1 code
from your project, deploying the project will result in both
of your API being deployed to App version 2.
Deploying to multiple app versions
When you deploy your backend API, you deploy it to the project ID of the
Google Cloud Platform project you created for your API, and you must also
specify the App Engine version you deploy to.
You specify the App Engine/Cloud Project ID in the
application field in the
app.yamlfile; you specify the application version in the
Notice that the App Engine app version is not the same thing
as the backend API version number, which you specify in the
As shown in the figure above, you can deploy multiple API versions to the same App Engine version. And, you can have many App Engine versions for an app.
Accessing API versions deployed to a serving version
The first App Engine version
that you deploy your API to is the serving
version. This version runs at the URL
All of the API versions deployed to that App Engine app version can be
accessed using that URL.
The serving version remains the same until you explicitly change it, in the Google Cloud Platform Console.
Accessing API versions deployed to a non-serving application version
If you need to access API versions that are not deployed to the currently serving App Engine version, you use a version-specific URL, like this:
[VERSION] with your App Engine version, and
with your project ID. For example, suppose your App Engine serving version
is 1, but you want to access an API version deployed to version 2: you would
use this URL:
Accessing API versions deployed to non-serving modules
If you need to access API versions that are not deployed to the serving App Engine module, you would use a version-specific URL using the dot syntax as follows: