Tutorial: Use revisions to make non-breaking API changes safely

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.

For background, see Versions & revisions and API Versioning with Azure API Management.

In this tutorial, you learn how to:

  • Add a new revision
  • Make non-breaking changes to your revision
  • Make your revision current and add a change log entry
  • Browse the developer portal to see changes and change log

API revisions in the Azure portal

Prerequisites

Add a new revision

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

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

    Add API revision

    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'll be 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 non-breaking 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 Name, Display Name and URL of the operation as test.

  6. Save your new operation.

    Modify revision

  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

  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.

    Revision menu in Revisions window

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, select APIs.
  2. Select Developer portal from the top menu.
  3. In the developer portal, select APIs, and then select Demo Conference API.
  4. Notice your new test operation is now available.
  5. Select Changelog near the API name.
  6. Notice that your change log entry appears in the list.

Next steps

In this tutorial, you learned how to:

  • Add a new revision
  • Make non-breaking changes to your revision
  • Make your revision current and add a change log entry
  • Browse the developer portal to see changes and change log

Advance to the next tutorial: