Events
Mar 17, 11 PM - Mar 21, 11 PM
Join the meetup series to build scalable AI solutions based on real-world use cases with fellow developers and experts.
Register nowThis browser is no longer supported.
Upgrade to Microsoft Edge to take advantage of the latest features, security updates, and technical support.
APPLIES TO: All API Management tiers
With API Management soft-delete, you can recover and restore a recently deleted API Management instance. This feature protects against accidental deletion of your API Management instance.
Currently, depending on how you delete an API Management instance, the instance is either soft-deleted and recoverable during a retention period, or it's permanently deleted:
2020-06-01-preview
or later to delete an API Management instance, it's soft-deleted.2020-06-01-preview
is permanently deleted.Recovery and other operations on a soft-deleted instance are enabled through REST API version 2020-06-01-preview
or later, or the Azure SDK for .NET, Go, or Python.
Tip
Refer to Azure REST API Reference for tips and tools for calling Azure REST APIs and API Management REST for additional information specific to API Management.
Operation | Description | API Management namespace | Minimum API version |
---|---|---|---|
Create or Update | Creates or updates an API Management service. | API Management Service | Any |
Create or Update with restore property set to true |
Recovers (undeletes) an API Management Service if it was previously soft-deleted. If restore is specified and set to true all other properties will be ignored. |
API Management Service | 2020-06-01-preview |
Delete | Deletes an existing API Management service. | API Management Service | 2020-06-01-preview |
Get By Name | Get soft-deleted Api Management Service by name. | Deleted Services | 2020-06-01-preview |
List By Subscription | Lists all soft-deleted services available for undelete for the given subscription. | Deleted Services | 2020-06-01-preview |
Purge | Purges API Management Service (permanently deletes it with no option to undelete). | Deleted Services | 2020-06-01-preview |
You can use any API version to create your API Management instance. When you use the Azure portal, Azure REST API, or another Azure tool using API version 2020-06-01-preview
or later to delete an API Management instance, it's automatically soft-deleted.
Upon soft-deleting an API Management instance, the service will exist in a deleted state, making it inaccessible to normal API Management operations.
In the soft-deleted state:
If your API Management instance isn't recovered or purged by you within 48 hours, it's automatically deleted permanently.
You can verify that a soft-deleted API Management instance is available to restore (undelete) using either the Deleted Services Get By Name or List By Subscription operations.
Use the API Management Get By Name operation, substituting {subscriptionId}
, {location}
, and {serviceName}
with your Azure subscription, resource location name, and API Management instance name:
GET https://management.azure.com/subscriptions/{subscriptionId}/providers/Microsoft.ApiManagement/locations/{location}/deletedservices/{serviceName}?api-version=2021-08-01
If available for undelete, Azure will return a record of the API Management instance showing its deletionDate
and scheduledPurgeDate
, for example:
{
"id": "subscriptions/########-####-####-####-############/providers/Microsoft.ApiManagement/locations/southcentralus/deletedservices/apimtest",
"name": "apimtest",
"type": "Microsoft.ApiManagement/deletedservices",
"location": "South Central US",
"properties": {
"serviceId": "/subscriptions/########-####-####-####-############/resourceGroups/apimtestgroup/providers/Microsoft.ApiManagement/service/apimtest",
"scheduledPurgeDate": "2021-11-26T19:40:26.3596893Z",
"deletionDate": "2021-11-24T19:40:50.1013572Z"
}
}
Use the API Management List By Subscription operation, substituting {subscriptionId}
with your subscription ID:
GET https://management.azure.com/subscriptions/{subscriptionId}/providers/Microsoft.ApiManagement/deletedservices?api-version=2021-08-01
This will return a list all soft-deleted services available for undelete under the given subscription, showing the deletionDate
and scheduledPurgeDate
for each.
Use the API Management Create Or Update operation, substituting {subscriptionId}
, {resourceGroup}
, and {apimServiceName}
with your Azure subscription, resource group name, and API Management name:
PUT
https://management.azure.com/subscriptions/{subscriptionId}/resourceGroups/{resourceGroup}/providers/Microsoft.ApiManagement/service/{apimServiceName}?api-version=2021-08-01
. . . and set the restore
property to true
in the request body. (When this flag is specified and set to true, all other properties will be ignored.) For example:
{
"properties": {
"publisherEmail": "help@contoso.com",
"publisherName": "Contoso",
"restore": true
},
"sku": {
"name": "Developer",
"capacity": 1
},
"location": "South Central US"
}
Use the API Management Purge operation, substituting {subscriptionId}
, {location}
, and {serviceName}
with your Azure subscription, resource location, and API Management name.
Note
To purge a soft-deleted instance, you must have the following RBAC permissions at the subscription scope in addition to Contributor access to the API Management instance: Microsoft.ApiManagement/locations/deletedservices/delete, Microsoft.ApiManagement/deletedservices/read.
DELETE https://management.azure.com/subscriptions/{subscriptionId}/providers/Microsoft.ApiManagement/locations/{location}/deletedservices/{serviceName}?api-version=2021-08-01
This will permanently delete your API Management instance from Azure.
You can reuse the name of an API Management instance in a new deployment:
After the instance has been permanently deleted (purged) from Azure.
In the same subscription as the original instance.
You can't reuse the name of an API Management instance in a new deployment:
While the instance is soft-deleted.
In a subscription other than the one used to deploy the original instance, even after the original instance has been permanently deleted (purged) from Azure. This restriction applies whether the new subscription used is in the same or a different Microsoft Entra tenant. The restriction is in effect for several days or longer after deletion, depending on the subscription type.
This restriction is because Azure reserves the service host name to a customer's tenant for a reservation period to prevent the threat of subdomain takeover with dangling DNS entries. For more information, see Prevent dangling DNS entries and avoid subdomain takeover. To see all dangling DNS entries for subscriptions in a Microsoft Entra tenant, see Identify dangling DNS entries.
Learn about long-term API Management backup and recovery options:
Events
Mar 17, 11 PM - Mar 21, 11 PM
Join the meetup series to build scalable AI solutions based on real-world use cases with fellow developers and experts.
Register nowTraining
Module
Publish and manage your APIs with Azure API Management - Training
Learn about using an Azure API gateway to share APIs with partners, and how to use subscription keys to control access to your APIs.
Certification
Microsoft Certified: Azure Cosmos DB Developer Specialty - Certifications
Write efficient queries, create indexing policies, manage, and provision resources in the SQL API and SDK with Microsoft Azure Cosmos DB.