Published on

How to Purge an API Management Instance

Authors
  • avatar
    Name
    Alexander Arana Escobedo
    Twitter
purge-apim

If you’ve noticed errors when trying to recreate your API Management (APIM) instance with the same name during your testing phase, you might see a message similar to this:

code: ServiceAlreadyExistsInSoftDeletedState, message:Api service apim-test-we-01 was soft-deleted. In order to create the new service with the same name, you have to either undelete the service or purge it. See https://aka.ms/apimsoftdelete.

This happens for two reasons:

  • When you use the Azure portal or REST API version 2020-06-01-preview or later to delete an API Management instance, it's soft-deleted.
  • An API Management instance deleted using API Management commands in Azure PowerShell or Azure CLI is soft-deleted.

To permanently delete (purge) the APIM service, you can use the Azure REST API. Here's how:

Step 1: Retrieve a Microsoft Entra ID Access Token

First, you need to obtain an access token. You can use any API development tool you prefer, but for this demo, I'll use Postman.

Run the commands below and copy the accessToken you get from the output.

az login
az account set --subscription <SUBSCRIPTION_ID>
az account get-access-token

Navigate to the Authorization tab and select Bearer Token as the Type.

purge-apim

Paste the access token in the Token field.

purge-apim

Step 2: List Soft-Deleted Instances

Start by getting a list of all soft-deleted instances for a given subscription. You need to send a GET request using the REST API. Replace the placeholder with your subscription ID, and copy it to Postman.

Here’s the REST API:

https://management.azure.com/subscriptions/{subscriptionId}/providers/Microsoft.ApiManagement/deletedservices?api-version=2021-08-01

If you find an instance, as the picture below, it means you have something you can purge. Let’s do it! 🤠

purge-apim

Step 3: Purge the APIM Instance

To purge the APIM instance, you need to send a DELETE request using the REST API. Replace the placeholders with your subscription ID, location, and APIM name.

Here’s the REST API:

https://management.azure.com/subscriptions/{subscriptionId}/providers/Microsoft.ApiManagement/locations/{location}/deletedservices/{serviceName}?api-version=2021-08-01

Step 4: Confirm the Deletion

After successfully deleting the APIM service, run the list soft-deleted instances request again. The list (array) should now be empty, indicating that the service has been purged.

purge-apim

I hope this guide helps you out! If you have any questions, don’t hesitate to reach out.

Alexander Arana.E

References

https://learn.microsoft.com/en-us/azure/deployment-environments/how-to-authenticate

https://learn.microsoft.com/en-us/azure/api-management/soft-delete

Discuss on X