You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
There are times when it's impractical to have all callers to your API use exactly the same version. When callers want to upgrade to a later version, they want an approach that's easy to understand. As shown in this tutorial, it's possible to provide multiple *versions* in Azure API Management.
19
+
There are times when it's impractical to have all callers to your API use the same version. When callers want to upgrade to a later version, they want an approach that's easy to understand. As shown in this tutorial, it's possible to provide multiple *versions* in Azure API Management.
17
20
18
-
For background, see [Versions](api-management-versions.md)&[Revisions](api-management-revisions.md).
21
+
For background, see [Versions](api-management-versions.md)and[Revisions](api-management-revisions.md).
@@ -25,73 +28,71 @@ In this tutorial, you learn how to:
25
28
> * Add a new version to an existing API
26
29
> * Choose a version scheme
27
30
> * Add the version to a product
28
-
> *Browse the developer portal to see the version
31
+
> *View the version in the developer portal
29
32
30
-
:::image type="content" source="media/api-management-get-started-publish-versions/azure-portal.png" alt-text="Screenshot showing API versions in the Azure portal.":::
33
+
:::image type="content" source="media/api-management-get-started-publish-versions/azure-portal.png" alt-text="Screenshot showing API versions in the Azure portal." lightbox="media/api-management-get-started-publish-versions/azure-portal.png":::
31
34
32
35
## Prerequisites
33
36
34
-
+ Learn the[Azure API Management terminology](api-management-terminology.md).
35
-
+ Complete the following quickstart:[Create an Azure API Management instance](get-started-create-service-instance.md).
36
-
+Also, complete the following tutorial:[Import and publish your first API](import-and-publish.md).
37
+
+ Learn [Azure API Management terminology](api-management-terminology.md).
38
+
+ Complete the quickstart [Create an Azure API Management instance](get-started-create-service-instance.md).
39
+
+Complete the tutorial [Import and publish your first API](import-and-publish.md).
37
40
38
41
## Add a new version
39
42
40
43
1. In the [Azure portal](https://portal.azure.com), navigate to your API Management instance.
41
-
1. Select **APIs**.
42
-
1. Select **Swagger Petstore** from the API list.
43
-
1. Select the context menu (**...**) next to **Swagger Petstore**.
44
-
1. Select **Add version**.
45
-
46
-
:::image type="content" source="media/api-management-get-started-publish-versions/add-version-menu.png" alt-text="Screenshot showing command to add version in the API context menu in the portal.":::
44
+
1. In the left menu, in the **APIs** section, select **APIs**.
45
+
1. Locate **Swagger Petstore - OpenAPI 3.0** in the API list. Select the ellipsis (**...**) next to **Swagger Petstore - OpenAPI 3.0** and then select **Add version**. You'll add values to the resulting window in the next section.
47
46
47
+
:::image type="content" source="media/api-management-get-started-publish-versions/add-version-menu.png" alt-text="Screenshot showing the steps for adding a version." lightbox="media/api-management-get-started-publish-versions/add-version-menu.png":::
48
48
49
49
> [!TIP]
50
-
> Versions can also be enabled when you create a new API. On the **Add API** screen, select **Version this API?**.
50
+
> You can also enable versions when you create a new API. On the **Add API** screen, select **Version this API?**.
51
51
52
52
## Choose a versioning scheme
53
53
54
-
In Azure API Management, you choose how callers specify the API version by selecting a *versioning scheme*: **path, header**, or **query string**. In the following example, *path* is used as the versioning scheme.
55
-
56
-
Enter the values from the following table. Then select **Create** to create your version.
57
-
58
-
:::image type="content" source="media/api-management-get-started-publish-versions/add-version.png" alt-text="Screenshot showing window to create a new version in the portal.":::
59
-
54
+
In API Management, you choose how callers specify the API version by selecting a *versioning scheme*: **Path**, **Header**, or **Query string**. In the following example, *Path* is used as the versioning scheme.
60
55
56
+
In the **Create a new API as a version** window, enter the values from the following table. Then select **Create** to create your version.
61
57
62
58
|Setting |Value |Description |
63
59
|---------|---------|---------|
64
60
|**Version identifier**|*v1*| Scheme-specific indicator of the version. For **Path**, the suffix for the API URL path. |
65
-
|**Versioning scheme**|**Path**| The way callers specify the API version.<br/><br/> If **Header** or **Query string** is selected, enter another value: the name of the header or query string parameter.<br/><br/> A usage example is displayed. |
66
-
|**Full API version name**|*swagger-petstore-v1*| Unique name in your API Management instance.<br/><br/>Because a version is in fact a new API based off an API's [revision](api-management-get-started-revise-api.md), this setting is the new API's name. |
67
-
|**Products**|**Unlimited** (provided in certain service tiers) | Optionally, one or more products that the API version is associated with. To publish the API, you must associate it with a product. You can also [add the version to a product](#add-the-version-to-a-product) later. |
61
+
|**Versioning scheme**|**Path**| The way callers specify the API version.<br/><br/> If you select **Header** or **Query string**, enter another value: the name of the header or query string parameter.<br/><br/> A usage example is displayed. |
62
+
|**Full API version name**|*swagger-petstore-openapi-3-0-v1*| Unique name in your API Management instance.<br/><br/>Because a version is actually a new API that's based on an API's [revision](api-management-get-started-revise-api.md), this value is the new API's name. |
63
+
|**Products**|**Unlimited** (provided in some service tiers) | Optionally, one or more products that the API version is associated with. To publish the API, you must associate it with a product. You can also [add the version to a product](#add-the-version-to-a-product) later. |
64
+
65
+
:::image type="content" source="media/api-management-get-started-publish-versions/add-version.png" alt-text="Screenshot showing window to create a new version in the portal." lightbox="media/api-management-get-started-publish-versions/add-version.png":::
68
66
69
-
After creating the version, it now appears underneath**Swagger Petstore** in the API List. You now see two APIs: **Original**, and **v1**.
67
+
After you create the version, it appears under**Swagger Petstore - OpenAPI 3.0** in the API list. You now see two APIs: **Original** and **v1**:
70
68
71
-
:::image type="content" source="media/api-management-get-started-publish-versions/version-list.png" alt-text="Screenshot of versions listed under API in the portal.":::
69
+
:::image type="content" source="media/api-management-get-started-publish-versions/version-list.png" alt-text="Screenshot that shows the list of versions." lightbox="media/api-management-get-started-publish-versions/version-list.png":::
72
70
73
71
> [!Note]
74
-
> If you add a version to a non-versioned API, an **Original**is also automatically created. This version responds on the default URL. Creating an Original version ensures that any existing callers are not broken by the process of adding a version. If you create a new API with versions enabled at the start, an Original isn't created.
72
+
> If you add a version to a non-versioned API, an original version is also automatically created. This version responds on the default URL. The original version ensures that calls from existing callers still work after the version is added. If you create a new API with versions enabled at the start, an original isn't created.
75
73
76
74
## Edit a version
77
75
78
-
After adding the version, you can now edit and configure it as an API that is separate from an Original. Changes to one version don't affect another. For example, add or remove API operations, or edit the OpenAPI specification. For more information, see [Edit an API](edit-api.md).
76
+
After you add the version, you can edit and configure it as an API that's separate from the original. Changes to one version don't affect another (for example, if you add or remove API operations, or edit the OpenAPI specification). For more information, see [Edit an API](edit-api.md).
79
77
80
78
## Add the version to a product
81
79
82
-
In order for callers to see the new version, it must be added to a *product*. If you didn't already add the version to a product, you can add it to a product at any time.
80
+
For callers to see the new version, it must be added to a *product*. If you didn't already add the version to a product, you can do so at any time.
81
+
82
+
To add the version to a product:
83
83
84
-
For example, to add the version to the **Unlimited** product:
85
84
1. In the Azure portal, navigate to your API Management instance.
1. Under **APIs** in the left pane, select **Products**.
86
+
1. Select the product, and then select **APIs** in the left pane.
87
+
1. Select **+ Add**.
88
+
1. Select the API.
89
+
1. Click **Select**.
89
90
90
-
:::image type="content" source="media/api-management-get-started-publish-versions/08-add-multiple-versions-03-add-version-product.png" alt-text="Screenshot of adding version to product in the portal.":::
91
+
:::image type="content" source="media/api-management-get-started-publish-versions/08-add-multiple-versions-03-add-version-product.png" alt-text="Screenshot that shows the APIs - Product window." lightbox="media/api-management-get-started-publish-versions/08-add-multiple-versions-03-add-version-product.png":::
91
92
92
93
## Use version sets
93
94
94
-
When you create multiple versions, the Azure portal creates a *version set*, which represents a set of versions for a single logical API. Select the name of an API that has multiple versions. The Azure portal displays its **Version set**. You can customize the **Name** and **Description** of a virtual set.
95
+
When you create multiple versions, the Azure portal creates a *version set*, which represents a set of versions for a single logical API. If you select the name of an API that has multiple versions, the portal displays its version set. You can customize the name and description of a version set.
95
96
96
97
You can interact directly with version sets by using the Azure CLI:
97
98
@@ -100,42 +101,34 @@ You can interact directly with version sets by using the Azure CLI:
100
101
To see all your version sets, run the [az apim api versionset list](/cli/azure/apim/api/versionset#az-apim-api-versionset-list) command:
101
102
102
103
```azurecli
103
-
az apim api versionset list --resource-group apim-hello-world-resource-group \
104
-
--service-name apim-hello-world --output table
104
+
az apim api versionset list --resource-group <resource-group-name> \
When the Azure portal creates a version set for you, it assigns an alphanumeric name, which appears in the **Name** column of the list. Use this name in other Azure CLI commands.
108
109
109
110
To see details about a version set, run the [az apim api versionset show](/cli/azure/apim/api/versionset#az-apim-api-versionset-show) command:
110
111
111
112
```azurecli
112
-
az apim api versionset show --resource-group apim-hello-world-resource-group \
0 commit comments