Skip to content

Create a New API Version

You need to create a new API version when you want to change a published API's behavior, authentication mechanism, resources, throttling tiers, target audiences, etc. WSO2 does not recommend to modify a published API that has subscribers plugged into it.

After creating a new version, you typically deploy it as a prototype for early promotion. A prototype can be used for testing, without a subscription, along with the published versions of the API. After a period of time of using the new version of the API in parallel with the older versions, you can publish the prototyped API and deprecate the older versions.


The example here uses the PizzaShack API, which you created in the Create a REST API section and Published in the Publish an API section.

Follow the instructions below to create a new version of an existing API:

  1. Sign in to the WSO2 API Publisher.


    Create and publish an API. For more information, see Create a REST API and Publish an API.

  2. Navigate to the API listing page, and click on the API for which you want to create a new version (e.g., PizzaShackAPI 2.0.0).

  3. Click Create New Version.

    Create New Version button

  4. Enter a version number and click Create.

    Create New API Version

    You are redirected to the API Overview page.


For API Product versioning create an API Product following Create an API Product. Then follow the above steps as similar to API versioning.


For more details on the default version, see Backward Compatibility section.


By default, only the latest version of an API is shown in the Developer Portal. If you want to display multiple versions, add/change the following configuration in the <API-M_HOME>/repository/conf/deployment.toml file, and restart the server.

   display_multiple_versions = true

You have created a new version of an API. In the next tutorial, let's learn how to publish the new version and deprecate old API versions.