Skip to content

Latest commit

 

History

History
189 lines (128 loc) · 8.88 KB

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

File metadata and controls

189 lines (128 loc) · 8.88 KB
Raw
title titleSuffix description services author ms.service ms.custom ms.topic ms.date ms.author
Tutorial - Use revisions in API Management for safe nonbreaking API changes
Azure API Management
Follow the steps of this tutorial to learn how to make nonbreaking API changes using revisions in Azure API Management.
api-management
dlepow
azure-api-management
mvc, devx-track-azurecli, devdivchpfy22
tutorial
07/31/2024
danlep

Tutorial: Use revisions to make nonbreaking API changes safely

[!INCLUDE api-management-availability-all-tiers]

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 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 and Revisions.

In this tutorial, you learn how to:

[!div class="checklist"]

  • Add a new 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="Screenshot of API revisions in the Azure portal." lightbox="media/api-management-getstarted-revise-api/azure-portal.png":::

Prerequisites

Add a new revision

  1. Sign in to the Azure portal, and go to your API Management instance.

  2. In the left menu, under APIs, select APIs.

  3. Select Demo Conference API from the API list (or another API to which you want to add revisions).

  4. Select the Revisions tab.

  5. Select + Add 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.

  6. Provide a description for your new revision, to help remember what it is used for.

  7. Select Create.

  8. 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 nonbreaking changes to your revision

  1. Select Demo Conference API from the API list.

  2. Select the Design tab near the top of the screen.

  3. Notice that the revision selector (directly above the design tab) shows Revision 2 as currently selected.

    [!TIP] Use the revision selector to switch between revisions that you wish to work on.

  4. Select + Add Operation.

  5. Set your new operation to POST, and the Display name, Name, and URL of the operation as test.

  6. Save your new operation.

    :::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.":::

  7. 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.

  8. Notice that your new operation doesn't appear in Revision 1.

Make your revision current and add a change log entry

Portal

  1. Select the Revisions tab from the menu near the top of the page.

  2. Open the context menu (...) for Revision 2.

  3. Select Make current.

  4. 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.

  5. Revision 2 is now current.

    :::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

To begin using Azure CLI:

[!INCLUDE azure-cli-prepare-your-environment-no-header.md]

Use this procedure to create and update a release.

  1. Run the az apim api list command to see your API IDs:

    az apim api list --resource-group apim-hello-word-resource-group \
    --service-name apim-hello-world --output table

    The API ID to use in the next command is the Name value. The API revision is in the ApiRevision column.

  2. To create the release, with a release note, run the az apim api release create command:

    az apim api release create --resource-group apim-hello-word-resource-group \
    --api-id demo-conference-api --api-revision 2 --service-name apim-hello-world \
    --notes 'Testing revisions. Added new "test" operation.'

    The revision that you release becomes the current revision.

  3. To see your releases, use the az apim api release list command:

    az apim api release list --resource-group apim-hello-word-resource-group \
    --api-id echo-api --service-name apim-hello-world --output table

    The notes you specify appear in the change log. You can see them in the output of the previous command.

  4. When you create a release, the --notes parameter is optional. You can add or change the notes later using the az apim api release update command:

    az apim api release update --resource-group apim-hello-word-resource-group \
    --api-id demo-conference-api --release-id 00000000000000000000000000000000 \
    --service-name apim-hello-world --notes "Revised notes."

    Use the value in the Name column for the release ID.

You can remove any release by running the az apim api release delete command:

az apim api release delete --resource-group apim-hello-word-resource-group \
    --api-id demo-conference-api --release-id 00000000000000000000000000000000 
    --service-name apim-hello-world

Browse the developer portal to see changes and change log

If you've tried the developer portal, you can review the API changes and change log there.

  1. In the Azure portal, navigate to your API Management instance.
  2. In the left menu, under APIs, select APIs.
  3. Select Developer portal from the top menu.
  4. In the developer portal, select APIs, and then select Demo Conference API.
  5. Notice your new test operation is now available.
  6. Select Changelog near the API name.
  7. Notice that your change log entry appears in the list.

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 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:

[!div class="nextstepaction"] Publish multiple versions of your API