AI API Versioning and Revision Control in Azure

Question

Pulumi · Accepted Answer

API versioning and revision control are essential practices when managing APIs, ensuring that changes made to the APIs are done in a controlled manner, and clients are not affected by updates until they're ready to upgrade to the new versions. In Azure, the API Management service provides capabilities to manage API versioning and revisions.

Azure API Management supports multiple API versions and revisions. A version is a distinct set of your API that has its own lifecycle. On the other hand, a revision is a modification within the same version of the API that allows you to make changes, test them, and then decide when to make them available to the consumers.

The following Pulumi program will demonstrate how to set up API versioning and revision control in Azure API Management using the `azure-native` package.

1. **API Version Set**: An API Version Set is a grouping of API versions. This resource allows us to specify a name and versioning scheme, which determines how the versions are represented in the API URLs.
2. **API**: The actual API resource that will be assigned to a version set, representing a particular version of our API.
3. **API Revision**: Each API can have multiple revisions, which are used to make changes, test, and then optionally make the revision current.
4. **API Release**: A release is a snapshot of an API's configuration at a point in time. Releasing an API is the act of publishing an API or a specific revision of an API.

We will use these resources to set up a versioned API with proper revision control. First, let's write the program that sets up an API version set and then adds an API to it with a couple of revisions.

Ensure you have the following before running the code:
- The Azure CLI is installed and configured with an Azure subscription where you have permissions to create resources.
- The Pulumi CLI is installed.
- You have selected a Python environment where Pulumi is installed.

```python
import pulumi
from pulumi_azure_native import apimanagement as api_management

# Set up the resource group and API Management service
resource_group = api_management.ResourceGroup("resourceGroup")

# The API Management service used to host the versioned API
api_management_service = api_management.ApiManagementService("apiManagementService",
    resource_group_name=resource_group.name,
    publisher_email="admin@example.com",
    publisher_name="admin",
    sku=api_management.ApiManagementServiceSkuPropertiesArgs(
        name="Consumption",
        capacity=0,
    )
)

# API Version Set
version_set = api_management.ApiVersionSet("apiVersionSet",
    resource_group_name=resource_group.name,
    service_name=api_management_service.name,
    display_name="MyAPI Versions",
    versioning_scheme="Segment",
)

# API tied to the Version Set, representing one version of our API
api = api_management.Api("api",
    resource_group_name=resource_group.name,
    service_name=api_management_service.name,
    display_name="MyAPI",
    path="myapi",
    api_version_set_id=version_set.id,
    api_version="v1",
    service_url="https://backend.example.com",
)

# First Revision of the API
api_revision1 = api_management.Api("apiRevision1",
    resource_group_name=resource_group.name,
    service_name=api_management_service.name,
    display_name="MyAPI Revision 1",
    path="myapi",
    api_id=api.id,  # Link this API revision to the original API
    api_revision="1",  # This is the first revision of this API
    service_url="https://backend-revision1.example.com",
    api_revision_description="Introduction of new endpoints",
    content_format="swagger-link-json",
    subscription_required=True,
    is_current=True,
    source_api_id=api.id,
)

# Second Revision of the API (will not be current)
api_revision2 = api_management.Api("apiRevision2",
    resource_group_name=resource_group.name,
    service_name=api_management_service.name,
    display_name="MyAPI Revision 2",
    path="myapi",
    api_id=api.id,  # Link this API revision to the original API
    api_revision="2",  # This is the second revision of this API
    service_url="https://backend-revision2.example.com",
    api_revision_description="Deprecation of old endpoints",
    content_format="swagger-link-json",
    subscription_required=True,
    is_current=False,  # Not the current revision, used for testing
    source_api_id=api.id,
)

# Release of the API, which is a snapshot of the API configuration at a specific point in time
api_release = api_management.ApiRelease("apiRelease",
    resource_group_name=resource_group.name,
    service_name=api_management_service.name,
    api_id=api.id,
    release_id=api_revision1.api_revision,
    notes="Initial release of the MyAPI"
)

# Export the API management service URL and the URL of the current API revision
pulumi.export("apiManagementServiceUrl", api_management_service.gateway_url)
pulumi.export("currentApiRevisionUrl", api_revision1.gateway_url)
```

This program creates:
- An API version set that specifies how API versions should be treated and identified.
- An API within that version set, with two revisions: the first being current and the second for testing purposes.
- A release representing the "current" version of the API, which makes this version available to API consumers.

To use this code:
- Replace the placeholder values with the actual values for your backend service URL and other configurations.
- After deployment, test the API revisions by accessing them via the URLs provided by the released API and the service URL.

Each revision and release can be managed within the Azure portal. You can set a revision as current, create new revisions, and manage releases, thus fully controlling the versioning and the lifecycle of your APIs.