Merge pull request #282901 from dlepow/tutrev

[APIM] Update revisions tutorial

Author: Jill Grant

articles/api-management/api-management-get-started-revise-api.md

@@ -1,36 +1,37 @@
 ---
-title: Tutorial - Use revisions in API Management to make non-breaking API changes safely 
+title: Tutorial - Use revisions in API Management for safe nonbreaking API changes 
 titleSuffix: Azure API Management
-description: Follow the steps of this tutorial to learn how to make non-breaking changes using revisions in API Management.
+description: Follow the steps of this tutorial to learn how to make nonbreaking API changes using revisions in Azure API Management.
 services: api-management
 author: dlepow
-ms.service: api-management
+ms.service: azure-api-management
 ms.custom: mvc, devx-track-azurecli, devdivchpfy22
 ms.topic: tutorial
-ms.date: 03/30/2022
+ms.date: 07/31/2024
 ms.author: danlep
 
 ---
 
-# Tutorial: Use revisions to make non-breaking API changes safely
+# Tutorial: Use revisions to make nonbreaking API changes safely
 
 [!INCLUDE [api-management-availability-all-tiers](../../includes/api-management-availability-all-tiers.md)]
 
 When your API is ready to go and is used by developers, you eventually need to make changes to that API and at the same time not disrupt callers of your API. It's also useful to let developers know about the changes you made.
 
-In Azure API Management, use *revisions* to make non-breaking API changes so you can model and test changes safely. When ready, you can make a revision current and replace your current API.
+In Azure API Management, use *revisions* to make nonbreaking API changes so you can model and test changes safely. When ready, you can make a revision current and replace your current API.
 
-For background, see [Versions & revisions](https://azure.microsoft.com/blog/versions-revisions/) and [API Versioning with Azure API Management](https://azure.microsoft.com/blog/api-versioning-with-azure-api-management/).
+For background, see [Versions](api-management-versions.md) and [Revisions](api-management-revisions.md).
 
 In this tutorial, you learn how to:
 
 > [!div class="checklist"]
 > * Add a new revision
-> * Make non-breaking changes to your revision
+> * Make nonbreaking changes to your revision
 > * Make your revision current and add a change log entry
 > * Browse the developer portal to see changes and change log
+> * Access an API revision
 
-:::image type="content" source="media/api-management-getstarted-revise-api/azure-portal.png" alt-text="API revisions in the Azure portal":::
+:::image type="content" source="media/api-management-getstarted-revise-api/azure-portal.png" alt-text="Screenshot of API revisions in the Azure portal." lightbox="media/api-management-getstarted-revise-api/azure-portal.png":::
 
 ## Prerequisites
 
@@ -41,24 +42,24 @@ In this tutorial, you learn how to:
 ## Add a new revision
 
 1. Sign in to the [Azure portal](https://portal.azure.com), and go to your API Management instance.
-1. Select **APIs**.
+1. In the left menu, under **APIs**, select **APIs**.
 2. Select **Demo Conference API** from the API list (or another API to which you want to add revisions).
 3. Select the **Revisions** tab.
 4. Select **+ Add revision**.
 
-   :::image type="content" source="media/api-management-getstarted-revise-api/07-add-revisions-01-add-new-revision.png" alt-text="Add API revision":::
+   :::image type="content" source="media/api-management-getstarted-revise-api/07-add-revisions-01-add-new-revision.png" alt-text="Screenshot of adding an API revision in the portal.":::
 
     > [!TIP]
     > You can also select **Add revision** in the context menu (**...**) of the API.
 
-5. Provide a description for your new revision, to help remember what it'll be used for.
+5. Provide a description for your new revision, to help remember what it is used for.
 6. Select **Create**.
 7. Your new revision is now created.
 
     > [!NOTE]
     > Your original API remains in **Revision 1**. This is the revision your users continue to call, until you choose to make a different revision current.
 
-## Make non-breaking changes to your revision
+## Make nonbreaking changes to your revision
 
 1. Select **Demo Conference API** from the API list.
 1. Select the **Design** tab near the top of the screen.
@@ -67,10 +68,10 @@ In this tutorial, you learn how to:
     > [!TIP]
     > Use the revision selector to switch between revisions that you wish to work on.
 1. Select **+ Add Operation**.
-1. Set your new operation to **POST**, and the Name, Display Name and URL of the operation as **test**.
+1. Set your new operation to **POST**, and the  **Display name**, **Name**, and **URL** of the operation as **test**.
 1. **Save** your new operation.
 
-   :::image type="content" source="media/api-management-getstarted-revise-api/07-add-revisions-02-make-changes.png" alt-text="Modify revision":::
+   :::image type="content" source="media/api-management-getstarted-revise-api/07-add-revisions-02-make-changes.png" alt-text="Screenshot showing how to add an operation in a revision in the portal.":::
 1. You've now made a change to **Revision 2**. Use the **revision selector** near the top of the page to switch back to **Revision 1**.
 1. Notice that your new operation doesn't appear in **Revision 1**. 
 
@@ -84,7 +85,7 @@ In this tutorial, you learn how to:
 1. Select the **Post to Public Change log for this API** checkbox, if you want to post notes about this change. Provide a description for your change that the developers can see, for example: **Testing revisions. Added new "test" operation.**
 1. **Revision 2** is now current.
 
-    :::image type="content" source="media/api-management-getstarted-revise-api/revisions-menu.png" alt-text="Revision menu in Revisions window":::
+    :::image type="content" source="media/api-management-getstarted-revise-api/revisions-menu.png" alt-text="Screenshot of revision menu in Revisions window in the portal." lightbox="media/api-management-getstarted-revise-api/revisions-menu.png":::
 
 ### [Azure CLI](#tab/azure-cli)
 
@@ -146,22 +147,41 @@ az apim api release delete --resource-group apim-hello-word-resource-group \
 
 If you've tried the [developer portal](api-management-howto-developer-portal-customize.md), you can review the API changes and change log there.
 
-1. In the Azure portal, select **APIs**.
+1. In the Azure portal, navigate to your API Management instance.
+1. In the left menu, under **APIs**, select **APIs**.
 1. Select **Developer portal** from the top menu.
 1. In the developer portal, select **APIs**, and then select **Demo Conference API**.
 1. Notice your new **test** operation is now available.
 1. Select **Changelog** near the API name.
 1. Notice that your change log entry appears in the list.
 
-## Next steps
+
+## Access an API revision
+
+Each revision to your API can be accessed using a specially formed URL. Add `;rev={revisionNumber}` at the end of your API URL path, but before the query string, to access a specific revision of that API. For example, you might use this URL to access revision 2 of the Demo Conference API:
+
+`https://apim-hello-world.azure-api.net/conf;rev=2/speakers`
+
+You can find the URL paths for your API's revisions on the **Revisions** tab in the Azure portal.
+
+:::image type="content" source="media/transform-api/revision-url-path.png" alt-text="Screenshot of revision URLs in the portal.":::
+
+> [!TIP]
+> You can access the *current* revision of your API using the API path without the `;rev` string, in addition to the full URL that appends `;rev={revisionNumber}` to your API path.
+
+
+## Summary
 
 In this tutorial, you learned how to:
 
 > [!div class="checklist"]
 > * Add a new revision
-> * Make non-breaking changes to your revision
+> * Make nonbreaking changes to your revision
 > * Make your revision current and add a change log entry
 > * Browse the developer portal to see changes and change log
+> * Access an API revision
+
+## Next steps
 
 Advance to the next tutorial: