Configure Azure API Management APIs

The azure-native:apimanagement:Api resource, part of the Pulumi Azure Native provider, defines an API within Azure API Management: its path, protocols, backend service, and authentication requirements. This guide focuses on five capabilities: API definition with authentication, OpenAPI import, API cloning and versioning, revision management, and GraphQL API configuration.

APIs belong to an API Management service instance and may reference authorization servers, version sets, or source APIs for cloning. The examples are intentionally small. Combine them with your own policies, products, and backend configurations.

Define an API with OAuth2 authentication

Most API Management deployments start by defining an API with its path, protocols, and backend service URL, often securing access with OAuth2 authentication.

import * as pulumi from "@pulumi/pulumi";
import * as azure_native from "@pulumi/azure-native";

const api = new azure_native.apimanagement.Api("api", {
    apiId: "tempgroup",
    authenticationSettings: {
        oAuth2: {
            authorizationServerId: "authorizationServerId2283",
            scope: "oauth2scope2580",
        },
    },
    description: "apidescription5200",
    displayName: "apiname1463",
    path: "newapiPath",
    protocols: [
        azure_native.apimanagement.Protocol.Https,
        azure_native.apimanagement.Protocol.Http,
    ],
    resourceGroupName: "rg1",
    serviceName: "apimService1",
    serviceUrl: "http://newechoapi.cloudapp.net/api",
    subscriptionKeyParameterNames: {
        header: "header4520",
        query: "query3037",
    },
});

import pulumi
import pulumi_azure_native as azure_native

api = azure_native.apimanagement.Api("api",
    api_id="tempgroup",
    authentication_settings={
        "o_auth2": {
            "authorization_server_id": "authorizationServerId2283",
            "scope": "oauth2scope2580",
        },
    },
    description="apidescription5200",
    display_name="apiname1463",
    path="newapiPath",
    protocols=[
        azure_native.apimanagement.Protocol.HTTPS,
        azure_native.apimanagement.Protocol.HTTP,
    ],
    resource_group_name="rg1",
    service_name="apimService1",
    service_url="http://newechoapi.cloudapp.net/api",
    subscription_key_parameter_names={
        "header": "header4520",
        "query": "query3037",
    })

package main

import (
	apimanagement "github.com/pulumi/pulumi-azure-native-sdk/apimanagement/v3"
	"github.com/pulumi/pulumi/sdk/v3/go/pulumi"
)

func main() {
	pulumi.Run(func(ctx *pulumi.Context) error {
		_, err := apimanagement.NewApi(ctx, "api", &apimanagement.ApiArgs{
			ApiId: pulumi.String("tempgroup"),
			AuthenticationSettings: &apimanagement.AuthenticationSettingsContractArgs{
				OAuth2: &apimanagement.OAuth2AuthenticationSettingsContractArgs{
					AuthorizationServerId: pulumi.String("authorizationServerId2283"),
					Scope:                 pulumi.String("oauth2scope2580"),
				},
			},
			Description: pulumi.String("apidescription5200"),
			DisplayName: pulumi.String("apiname1463"),
			Path:        pulumi.String("newapiPath"),
			Protocols: pulumi.StringArray{
				pulumi.String(apimanagement.ProtocolHttps),
				pulumi.String(apimanagement.ProtocolHttp),
			},
			ResourceGroupName: pulumi.String("rg1"),
			ServiceName:       pulumi.String("apimService1"),
			ServiceUrl:        pulumi.String("http://newechoapi.cloudapp.net/api"),
			SubscriptionKeyParameterNames: &apimanagement.SubscriptionKeyParameterNamesContractArgs{
				Header: pulumi.String("header4520"),
				Query:  pulumi.String("query3037"),
			},
		})
		if err != nil {
			return err
		}
		return nil
	})
}

using System.Collections.Generic;
using System.Linq;
using Pulumi;
using AzureNative = Pulumi.AzureNative;

return await Deployment.RunAsync(() => 
{
    var api = new AzureNative.ApiManagement.Api("api", new()
    {
        ApiId = "tempgroup",
        AuthenticationSettings = new AzureNative.ApiManagement.Inputs.AuthenticationSettingsContractArgs
        {
            OAuth2 = new AzureNative.ApiManagement.Inputs.OAuth2AuthenticationSettingsContractArgs
            {
                AuthorizationServerId = "authorizationServerId2283",
                Scope = "oauth2scope2580",
            },
        },
        Description = "apidescription5200",
        DisplayName = "apiname1463",
        Path = "newapiPath",
        Protocols = new[]
        {
            AzureNative.ApiManagement.Protocol.Https,
            AzureNative.ApiManagement.Protocol.Http,
        },
        ResourceGroupName = "rg1",
        ServiceName = "apimService1",
        ServiceUrl = "http://newechoapi.cloudapp.net/api",
        SubscriptionKeyParameterNames = new AzureNative.ApiManagement.Inputs.SubscriptionKeyParameterNamesContractArgs
        {
            Header = "header4520",
            Query = "query3037",
        },
    });

});

package generated_program;

import com.pulumi.Context;
import com.pulumi.Pulumi;
import com.pulumi.core.Output;
import com.pulumi.azurenative.apimanagement.Api;
import com.pulumi.azurenative.apimanagement.ApiArgs;
import com.pulumi.azurenative.apimanagement.inputs.AuthenticationSettingsContractArgs;
import com.pulumi.azurenative.apimanagement.inputs.OAuth2AuthenticationSettingsContractArgs;
import com.pulumi.azurenative.apimanagement.inputs.SubscriptionKeyParameterNamesContractArgs;
import java.util.List;
import java.util.ArrayList;
import java.util.Map;
import java.io.File;
import java.nio.file.Files;
import java.nio.file.Paths;

public class App {
    public static void main(String[] args) {
        Pulumi.run(App::stack);
    }

    public static void stack(Context ctx) {
        var api = new Api("api", ApiArgs.builder()
            .apiId("tempgroup")
            .authenticationSettings(AuthenticationSettingsContractArgs.builder()
                .oAuth2(OAuth2AuthenticationSettingsContractArgs.builder()
                    .authorizationServerId("authorizationServerId2283")
                    .scope("oauth2scope2580")
                    .build())
                .build())
            .description("apidescription5200")
            .displayName("apiname1463")
            .path("newapiPath")
            .protocols(            
                "https",
                "http")
            .resourceGroupName("rg1")
            .serviceName("apimService1")
            .serviceUrl("http://newechoapi.cloudapp.net/api")
            .subscriptionKeyParameterNames(SubscriptionKeyParameterNamesContractArgs.builder()
                .header("header4520")
                .query("query3037")
                .build())
            .build());

    }
}

resources:
  api:
    type: azure-native:apimanagement:Api
    properties:
      apiId: tempgroup
      authenticationSettings:
        oAuth2:
          authorizationServerId: authorizationServerId2283
          scope: oauth2scope2580
      description: apidescription5200
      displayName: apiname1463
      path: newapiPath
      protocols:
        - https
        - http
      resourceGroupName: rg1
      serviceName: apimService1
      serviceUrl: http://newechoapi.cloudapp.net/api
      subscriptionKeyParameterNames:
        header: header4520
        query: query3037

The path property sets the API’s URL segment within the gateway. The protocols array specifies whether the API accepts HTTP, HTTPS, or both. The serviceUrl points to your backend service. The authenticationSettings block configures OAuth2, referencing an authorization server that must exist separately. The subscriptionKeyParameterNames customize how clients pass subscription keys.

Import an API from OpenAPI specification

Rather than defining operations manually, teams import APIs from existing OpenAPI specifications to preserve the contract defined in the specification.

import * as pulumi from "@pulumi/pulumi";
import * as azure_native from "@pulumi/azure-native";

const api = new azure_native.apimanagement.Api("api", {
    apiId: "petstore",
    format: azure_native.apimanagement.ContentFormat.Openapi_link,
    path: "petstore",
    resourceGroupName: "rg1",
    serviceName: "apimService1",
    value: "https://raw.githubusercontent.com/OAI/OpenAPI-Specification/master/examples/v3.0/petstore.yaml",
});

import pulumi
import pulumi_azure_native as azure_native

api = azure_native.apimanagement.Api("api",
    api_id="petstore",
    format=azure_native.apimanagement.ContentFormat.OPENAPI_LINK,
    path="petstore",
    resource_group_name="rg1",
    service_name="apimService1",
    value="https://raw.githubusercontent.com/OAI/OpenAPI-Specification/master/examples/v3.0/petstore.yaml")

package main

import (
	apimanagement "github.com/pulumi/pulumi-azure-native-sdk/apimanagement/v3"
	"github.com/pulumi/pulumi/sdk/v3/go/pulumi"
)

func main() {
	pulumi.Run(func(ctx *pulumi.Context) error {
		_, err := apimanagement.NewApi(ctx, "api", &apimanagement.ApiArgs{
			ApiId:             pulumi.String("petstore"),
			Format:            pulumi.String(apimanagement.ContentFormat_Openapi_Link),
			Path:              pulumi.String("petstore"),
			ResourceGroupName: pulumi.String("rg1"),
			ServiceName:       pulumi.String("apimService1"),
			Value:             pulumi.String("https://raw.githubusercontent.com/OAI/OpenAPI-Specification/master/examples/v3.0/petstore.yaml"),
		})
		if err != nil {
			return err
		}
		return nil
	})
}

using System.Collections.Generic;
using System.Linq;
using Pulumi;
using AzureNative = Pulumi.AzureNative;

return await Deployment.RunAsync(() => 
{
    var api = new AzureNative.ApiManagement.Api("api", new()
    {
        ApiId = "petstore",
        Format = AzureNative.ApiManagement.ContentFormat.Openapi_link,
        Path = "petstore",
        ResourceGroupName = "rg1",
        ServiceName = "apimService1",
        Value = "https://raw.githubusercontent.com/OAI/OpenAPI-Specification/master/examples/v3.0/petstore.yaml",
    });

});

package generated_program;

import com.pulumi.Context;
import com.pulumi.Pulumi;
import com.pulumi.core.Output;
import com.pulumi.azurenative.apimanagement.Api;
import com.pulumi.azurenative.apimanagement.ApiArgs;
import java.util.List;
import java.util.ArrayList;
import java.util.Map;
import java.io.File;
import java.nio.file.Files;
import java.nio.file.Paths;

public class App {
    public static void main(String[] args) {
        Pulumi.run(App::stack);
    }

    public static void stack(Context ctx) {
        var api = new Api("api", ApiArgs.builder()
            .apiId("petstore")
            .format("openapi-link")
            .path("petstore")
            .resourceGroupName("rg1")
            .serviceName("apimService1")
            .value("https://raw.githubusercontent.com/OAI/OpenAPI-Specification/master/examples/v3.0/petstore.yaml")
            .build());

    }
}

resources:
  api:
    type: azure-native:apimanagement:Api
    properties:
      apiId: petstore
      format: openapi-link
      path: petstore
      resourceGroupName: rg1
      serviceName: apimService1
      value: https://raw.githubusercontent.com/OAI/OpenAPI-Specification/master/examples/v3.0/petstore.yaml

The format property tells API Management to import from an OpenAPI link. The value property points to the specification URL, which must be publicly accessible. API Management parses the specification and creates operations automatically. The path property sets where the API appears in the gateway.

Clone an existing API with operations

When creating API variants or testing changes, cloning preserves operations and configuration while creating an independent API.

import * as pulumi from "@pulumi/pulumi";
import * as azure_native from "@pulumi/azure-native";

const api = new azure_native.apimanagement.Api("api", {
    apiId: "echo-api2",
    description: "Copy of Existing Echo Api including Operations.",
    displayName: "Echo API2",
    isCurrent: true,
    path: "echo2",
    protocols: [
        azure_native.apimanagement.Protocol.Http,
        azure_native.apimanagement.Protocol.Https,
    ],
    resourceGroupName: "rg1",
    serviceName: "apimService1",
    serviceUrl: "http://echoapi.cloudapp.net/api",
    sourceApiId: "/subscriptions/subid/resourceGroups/rg1/providers/Microsoft.ApiManagement/service/apimService1/apis/58a4aeac497000007d040001",
    subscriptionRequired: true,
});

import pulumi
import pulumi_azure_native as azure_native

api = azure_native.apimanagement.Api("api",
    api_id="echo-api2",
    description="Copy of Existing Echo Api including Operations.",
    display_name="Echo API2",
    is_current=True,
    path="echo2",
    protocols=[
        azure_native.apimanagement.Protocol.HTTP,
        azure_native.apimanagement.Protocol.HTTPS,
    ],
    resource_group_name="rg1",
    service_name="apimService1",
    service_url="http://echoapi.cloudapp.net/api",
    source_api_id="/subscriptions/subid/resourceGroups/rg1/providers/Microsoft.ApiManagement/service/apimService1/apis/58a4aeac497000007d040001",
    subscription_required=True)

package main

import (
	apimanagement "github.com/pulumi/pulumi-azure-native-sdk/apimanagement/v3"
	"github.com/pulumi/pulumi/sdk/v3/go/pulumi"
)

func main() {
	pulumi.Run(func(ctx *pulumi.Context) error {
		_, err := apimanagement.NewApi(ctx, "api", &apimanagement.ApiArgs{
			ApiId:       pulumi.String("echo-api2"),
			Description: pulumi.String("Copy of Existing Echo Api including Operations."),
			DisplayName: pulumi.String("Echo API2"),
			IsCurrent:   pulumi.Bool(true),
			Path:        pulumi.String("echo2"),
			Protocols: pulumi.StringArray{
				pulumi.String(apimanagement.ProtocolHttp),
				pulumi.String(apimanagement.ProtocolHttps),
			},
			ResourceGroupName:    pulumi.String("rg1"),
			ServiceName:          pulumi.String("apimService1"),
			ServiceUrl:           pulumi.String("http://echoapi.cloudapp.net/api"),
			SourceApiId:          pulumi.String("/subscriptions/subid/resourceGroups/rg1/providers/Microsoft.ApiManagement/service/apimService1/apis/58a4aeac497000007d040001"),
			SubscriptionRequired: pulumi.Bool(true),
		})
		if err != nil {
			return err
		}
		return nil
	})
}

using System.Collections.Generic;
using System.Linq;
using Pulumi;
using AzureNative = Pulumi.AzureNative;

return await Deployment.RunAsync(() => 
{
    var api = new AzureNative.ApiManagement.Api("api", new()
    {
        ApiId = "echo-api2",
        Description = "Copy of Existing Echo Api including Operations.",
        DisplayName = "Echo API2",
        IsCurrent = true,
        Path = "echo2",
        Protocols = new[]
        {
            AzureNative.ApiManagement.Protocol.Http,
            AzureNative.ApiManagement.Protocol.Https,
        },
        ResourceGroupName = "rg1",
        ServiceName = "apimService1",
        ServiceUrl = "http://echoapi.cloudapp.net/api",
        SourceApiId = "/subscriptions/subid/resourceGroups/rg1/providers/Microsoft.ApiManagement/service/apimService1/apis/58a4aeac497000007d040001",
        SubscriptionRequired = true,
    });

});

package generated_program;

import com.pulumi.Context;
import com.pulumi.Pulumi;
import com.pulumi.core.Output;
import com.pulumi.azurenative.apimanagement.Api;
import com.pulumi.azurenative.apimanagement.ApiArgs;
import java.util.List;
import java.util.ArrayList;
import java.util.Map;
import java.io.File;
import java.nio.file.Files;
import java.nio.file.Paths;

public class App {
    public static void main(String[] args) {
        Pulumi.run(App::stack);
    }

    public static void stack(Context ctx) {
        var api = new Api("api", ApiArgs.builder()
            .apiId("echo-api2")
            .description("Copy of Existing Echo Api including Operations.")
            .displayName("Echo API2")
            .isCurrent(true)
            .path("echo2")
            .protocols(            
                "http",
                "https")
            .resourceGroupName("rg1")
            .serviceName("apimService1")
            .serviceUrl("http://echoapi.cloudapp.net/api")
            .sourceApiId("/subscriptions/subid/resourceGroups/rg1/providers/Microsoft.ApiManagement/service/apimService1/apis/58a4aeac497000007d040001")
            .subscriptionRequired(true)
            .build());

    }
}

resources:
  api:
    type: azure-native:apimanagement:Api
    properties:
      apiId: echo-api2
      description: Copy of Existing Echo Api including Operations.
      displayName: Echo API2
      isCurrent: true
      path: echo2
      protocols:
        - http
        - https
      resourceGroupName: rg1
      serviceName: apimService1
      serviceUrl: http://echoapi.cloudapp.net/api
      sourceApiId: /subscriptions/subid/resourceGroups/rg1/providers/Microsoft.ApiManagement/service/apimService1/apis/58a4aeac497000007d040001
      subscriptionRequired: true

The sourceApiId references the API to clone by its full resource ID. The clone copies all operations but gets its own path and can have different settings. The isCurrent property marks whether this API is the active version.

Create a new API version from existing API

API versioning maintains multiple versions simultaneously, allowing clients to migrate gradually while new versions reference a version set.

import * as pulumi from "@pulumi/pulumi";
import * as azure_native from "@pulumi/azure-native";

const api = new azure_native.apimanagement.Api("api", {
    apiId: "echoapiv3",
    apiVersion: "v4",
    apiVersionSetId: "/subscriptions/subid/resourceGroups/rg1/providers/Microsoft.ApiManagement/service/apimService1/apiVersionSets/aa9c59e6-c0cd-4258-9356-9ca7d2f0b458",
    description: "Create Echo API into a new Version using Existing Version Set and Copy all Operations.",
    displayName: "Echo API2",
    isCurrent: true,
    path: "echo2",
    protocols: [
        azure_native.apimanagement.Protocol.Http,
        azure_native.apimanagement.Protocol.Https,
    ],
    resourceGroupName: "rg1",
    serviceName: "apimService1",
    serviceUrl: "http://echoapi.cloudapp.net/api",
    sourceApiId: "/subscriptions/subid/resourceGroups/rg1/providers/Microsoft.ApiManagement/service/apimService1/apis/echoPath",
    subscriptionRequired: true,
});

import pulumi
import pulumi_azure_native as azure_native

api = azure_native.apimanagement.Api("api",
    api_id="echoapiv3",
    api_version="v4",
    api_version_set_id="/subscriptions/subid/resourceGroups/rg1/providers/Microsoft.ApiManagement/service/apimService1/apiVersionSets/aa9c59e6-c0cd-4258-9356-9ca7d2f0b458",
    description="Create Echo API into a new Version using Existing Version Set and Copy all Operations.",
    display_name="Echo API2",
    is_current=True,
    path="echo2",
    protocols=[
        azure_native.apimanagement.Protocol.HTTP,
        azure_native.apimanagement.Protocol.HTTPS,
    ],
    resource_group_name="rg1",
    service_name="apimService1",
    service_url="http://echoapi.cloudapp.net/api",
    source_api_id="/subscriptions/subid/resourceGroups/rg1/providers/Microsoft.ApiManagement/service/apimService1/apis/echoPath",
    subscription_required=True)

package main

import (
	apimanagement "github.com/pulumi/pulumi-azure-native-sdk/apimanagement/v3"
	"github.com/pulumi/pulumi/sdk/v3/go/pulumi"
)

func main() {
	pulumi.Run(func(ctx *pulumi.Context) error {
		_, err := apimanagement.NewApi(ctx, "api", &apimanagement.ApiArgs{
			ApiId:           pulumi.String("echoapiv3"),
			ApiVersion:      pulumi.String("v4"),
			ApiVersionSetId: pulumi.String("/subscriptions/subid/resourceGroups/rg1/providers/Microsoft.ApiManagement/service/apimService1/apiVersionSets/aa9c59e6-c0cd-4258-9356-9ca7d2f0b458"),
			Description:     pulumi.String("Create Echo API into a new Version using Existing Version Set and Copy all Operations."),
			DisplayName:     pulumi.String("Echo API2"),
			IsCurrent:       pulumi.Bool(true),
			Path:            pulumi.String("echo2"),
			Protocols: pulumi.StringArray{
				pulumi.String(apimanagement.ProtocolHttp),
				pulumi.String(apimanagement.ProtocolHttps),
			},
			ResourceGroupName:    pulumi.String("rg1"),
			ServiceName:          pulumi.String("apimService1"),
			ServiceUrl:           pulumi.String("http://echoapi.cloudapp.net/api"),
			SourceApiId:          pulumi.String("/subscriptions/subid/resourceGroups/rg1/providers/Microsoft.ApiManagement/service/apimService1/apis/echoPath"),
			SubscriptionRequired: pulumi.Bool(true),
		})
		if err != nil {
			return err
		}
		return nil
	})
}

using System.Collections.Generic;
using System.Linq;
using Pulumi;
using AzureNative = Pulumi.AzureNative;

return await Deployment.RunAsync(() => 
{
    var api = new AzureNative.ApiManagement.Api("api", new()
    {
        ApiId = "echoapiv3",
        ApiVersion = "v4",
        ApiVersionSetId = "/subscriptions/subid/resourceGroups/rg1/providers/Microsoft.ApiManagement/service/apimService1/apiVersionSets/aa9c59e6-c0cd-4258-9356-9ca7d2f0b458",
        Description = "Create Echo API into a new Version using Existing Version Set and Copy all Operations.",
        DisplayName = "Echo API2",
        IsCurrent = true,
        Path = "echo2",
        Protocols = new[]
        {
            AzureNative.ApiManagement.Protocol.Http,
            AzureNative.ApiManagement.Protocol.Https,
        },
        ResourceGroupName = "rg1",
        ServiceName = "apimService1",
        ServiceUrl = "http://echoapi.cloudapp.net/api",
        SourceApiId = "/subscriptions/subid/resourceGroups/rg1/providers/Microsoft.ApiManagement/service/apimService1/apis/echoPath",
        SubscriptionRequired = true,
    });

});

package generated_program;

import com.pulumi.Context;
import com.pulumi.Pulumi;
import com.pulumi.core.Output;
import com.pulumi.azurenative.apimanagement.Api;
import com.pulumi.azurenative.apimanagement.ApiArgs;
import java.util.List;
import java.util.ArrayList;
import java.util.Map;
import java.io.File;
import java.nio.file.Files;
import java.nio.file.Paths;

public class App {
    public static void main(String[] args) {
        Pulumi.run(App::stack);
    }

    public static void stack(Context ctx) {
        var api = new Api("api", ApiArgs.builder()
            .apiId("echoapiv3")
            .apiVersion("v4")
            .apiVersionSetId("/subscriptions/subid/resourceGroups/rg1/providers/Microsoft.ApiManagement/service/apimService1/apiVersionSets/aa9c59e6-c0cd-4258-9356-9ca7d2f0b458")
            .description("Create Echo API into a new Version using Existing Version Set and Copy all Operations.")
            .displayName("Echo API2")
            .isCurrent(true)
            .path("echo2")
            .protocols(            
                "http",
                "https")
            .resourceGroupName("rg1")
            .serviceName("apimService1")
            .serviceUrl("http://echoapi.cloudapp.net/api")
            .sourceApiId("/subscriptions/subid/resourceGroups/rg1/providers/Microsoft.ApiManagement/service/apimService1/apis/echoPath")
            .subscriptionRequired(true)
            .build());

    }
}

resources:
  api:
    type: azure-native:apimanagement:Api
    properties:
      apiId: echoapiv3
      apiVersion: v4
      apiVersionSetId: /subscriptions/subid/resourceGroups/rg1/providers/Microsoft.ApiManagement/service/apimService1/apiVersionSets/aa9c59e6-c0cd-4258-9356-9ca7d2f0b458
      description: Create Echo API into a new Version using Existing Version Set and Copy all Operations.
      displayName: Echo API2
      isCurrent: true
      path: echo2
      protocols:
        - http
        - https
      resourceGroupName: rg1
      serviceName: apimService1
      serviceUrl: http://echoapi.cloudapp.net/api
      sourceApiId: /subscriptions/subid/resourceGroups/rg1/providers/Microsoft.ApiManagement/service/apimService1/apis/echoPath
      subscriptionRequired: true

The apiVersion property sets the version identifier. The apiVersionSetId references the version set that groups related versions. The sourceApiId copies operations from an existing API. The isCurrent property determines which version is active.

Create an API revision for testing changes

Revisions let teams test API changes without affecting the current version, copying operations from an existing API and potentially pointing to a different backend.

import * as pulumi from "@pulumi/pulumi";
import * as azure_native from "@pulumi/azure-native";

const api = new azure_native.apimanagement.Api("api", {
    apiId: "echo-api;rev=3",
    apiRevisionDescription: "Creating a Revision of an existing API",
    path: "echo",
    resourceGroupName: "rg1",
    serviceName: "apimService1",
    serviceUrl: "http://echoapi.cloudapp.net/apiv3",
    sourceApiId: "/subscriptions/subid/resourceGroups/rg1/providers/Microsoft.ApiManagement/service/apimService1/apis/echo-api",
});

import pulumi
import pulumi_azure_native as azure_native

api = azure_native.apimanagement.Api("api",
    api_id="echo-api;rev=3",
    api_revision_description="Creating a Revision of an existing API",
    path="echo",
    resource_group_name="rg1",
    service_name="apimService1",
    service_url="http://echoapi.cloudapp.net/apiv3",
    source_api_id="/subscriptions/subid/resourceGroups/rg1/providers/Microsoft.ApiManagement/service/apimService1/apis/echo-api")

package main

import (
	apimanagement "github.com/pulumi/pulumi-azure-native-sdk/apimanagement/v3"
	"github.com/pulumi/pulumi/sdk/v3/go/pulumi"
)

func main() {
	pulumi.Run(func(ctx *pulumi.Context) error {
		_, err := apimanagement.NewApi(ctx, "api", &apimanagement.ApiArgs{
			ApiId:                  pulumi.String("echo-api;rev=3"),
			ApiRevisionDescription: pulumi.String("Creating a Revision of an existing API"),
			Path:                   pulumi.String("echo"),
			ResourceGroupName:      pulumi.String("rg1"),
			ServiceName:            pulumi.String("apimService1"),
			ServiceUrl:             pulumi.String("http://echoapi.cloudapp.net/apiv3"),
			SourceApiId:            pulumi.String("/subscriptions/subid/resourceGroups/rg1/providers/Microsoft.ApiManagement/service/apimService1/apis/echo-api"),
		})
		if err != nil {
			return err
		}
		return nil
	})
}

using System.Collections.Generic;
using System.Linq;
using Pulumi;
using AzureNative = Pulumi.AzureNative;

return await Deployment.RunAsync(() => 
{
    var api = new AzureNative.ApiManagement.Api("api", new()
    {
        ApiId = "echo-api;rev=3",
        ApiRevisionDescription = "Creating a Revision of an existing API",
        Path = "echo",
        ResourceGroupName = "rg1",
        ServiceName = "apimService1",
        ServiceUrl = "http://echoapi.cloudapp.net/apiv3",
        SourceApiId = "/subscriptions/subid/resourceGroups/rg1/providers/Microsoft.ApiManagement/service/apimService1/apis/echo-api",
    });

});

package generated_program;

import com.pulumi.Context;
import com.pulumi.Pulumi;
import com.pulumi.core.Output;
import com.pulumi.azurenative.apimanagement.Api;
import com.pulumi.azurenative.apimanagement.ApiArgs;
import java.util.List;
import java.util.ArrayList;
import java.util.Map;
import java.io.File;
import java.nio.file.Files;
import java.nio.file.Paths;

public class App {
    public static void main(String[] args) {
        Pulumi.run(App::stack);
    }

    public static void stack(Context ctx) {
        var api = new Api("api", ApiArgs.builder()
            .apiId("echo-api;rev=3")
            .apiRevisionDescription("Creating a Revision of an existing API")
            .path("echo")
            .resourceGroupName("rg1")
            .serviceName("apimService1")
            .serviceUrl("http://echoapi.cloudapp.net/apiv3")
            .sourceApiId("/subscriptions/subid/resourceGroups/rg1/providers/Microsoft.ApiManagement/service/apimService1/apis/echo-api")
            .build());

    }
}

resources:
  api:
    type: azure-native:apimanagement:Api
    properties:
      apiId: echo-api;rev=3
      apiRevisionDescription: Creating a Revision of an existing API
      path: echo
      resourceGroupName: rg1
      serviceName: apimService1
      serviceUrl: http://echoapi.cloudapp.net/apiv3
      sourceApiId: /subscriptions/subid/resourceGroups/rg1/providers/Microsoft.ApiManagement/service/apimService1/apis/echo-api

The apiId uses semicolon syntax to specify the revision number (e.g., “echo-api;rev=3”). The apiRevisionDescription documents what changed. The sourceApiId copies operations from the base API. The serviceUrl can point to a different backend for testing. Revisions remain non-current until explicitly promoted.

Configure a GraphQL API endpoint

GraphQL APIs require different handling than REST APIs, with a single endpoint serving all queries and mutations that API Management routes to the backend.

import * as pulumi from "@pulumi/pulumi";
import * as azure_native from "@pulumi/azure-native";

const api = new azure_native.apimanagement.Api("api", {
    apiId: "tempgroup",
    apiType: azure_native.apimanagement.ApiType.Graphql,
    description: "apidescription5200",
    displayName: "apiname1463",
    path: "graphql-api",
    protocols: [
        azure_native.apimanagement.Protocol.Http,
        azure_native.apimanagement.Protocol.Https,
    ],
    resourceGroupName: "rg1",
    serviceName: "apimService1",
    serviceUrl: "https://api.spacex.land/graphql",
});

import pulumi
import pulumi_azure_native as azure_native

api = azure_native.apimanagement.Api("api",
    api_id="tempgroup",
    api_type=azure_native.apimanagement.ApiType.GRAPHQL,
    description="apidescription5200",
    display_name="apiname1463",
    path="graphql-api",
    protocols=[
        azure_native.apimanagement.Protocol.HTTP,
        azure_native.apimanagement.Protocol.HTTPS,
    ],
    resource_group_name="rg1",
    service_name="apimService1",
    service_url="https://api.spacex.land/graphql")

package main

import (
	apimanagement "github.com/pulumi/pulumi-azure-native-sdk/apimanagement/v3"
	"github.com/pulumi/pulumi/sdk/v3/go/pulumi"
)

func main() {
	pulumi.Run(func(ctx *pulumi.Context) error {
		_, err := apimanagement.NewApi(ctx, "api", &apimanagement.ApiArgs{
			ApiId:       pulumi.String("tempgroup"),
			ApiType:     pulumi.String(apimanagement.ApiTypeGraphql),
			Description: pulumi.String("apidescription5200"),
			DisplayName: pulumi.String("apiname1463"),
			Path:        pulumi.String("graphql-api"),
			Protocols: pulumi.StringArray{
				pulumi.String(apimanagement.ProtocolHttp),
				pulumi.String(apimanagement.ProtocolHttps),
			},
			ResourceGroupName: pulumi.String("rg1"),
			ServiceName:       pulumi.String("apimService1"),
			ServiceUrl:        pulumi.String("https://api.spacex.land/graphql"),
		})
		if err != nil {
			return err
		}
		return nil
	})
}

using System.Collections.Generic;
using System.Linq;
using Pulumi;
using AzureNative = Pulumi.AzureNative;

return await Deployment.RunAsync(() => 
{
    var api = new AzureNative.ApiManagement.Api("api", new()
    {
        ApiId = "tempgroup",
        ApiType = AzureNative.ApiManagement.ApiType.Graphql,
        Description = "apidescription5200",
        DisplayName = "apiname1463",
        Path = "graphql-api",
        Protocols = new[]
        {
            AzureNative.ApiManagement.Protocol.Http,
            AzureNative.ApiManagement.Protocol.Https,
        },
        ResourceGroupName = "rg1",
        ServiceName = "apimService1",
        ServiceUrl = "https://api.spacex.land/graphql",
    });

});

package generated_program;

import com.pulumi.Context;
import com.pulumi.Pulumi;
import com.pulumi.core.Output;
import com.pulumi.azurenative.apimanagement.Api;
import com.pulumi.azurenative.apimanagement.ApiArgs;
import java.util.List;
import java.util.ArrayList;
import java.util.Map;
import java.io.File;
import java.nio.file.Files;
import java.nio.file.Paths;

public class App {
    public static void main(String[] args) {
        Pulumi.run(App::stack);
    }

    public static void stack(Context ctx) {
        var api = new Api("api", ApiArgs.builder()
            .apiId("tempgroup")
            .apiType("graphql")
            .description("apidescription5200")
            .displayName("apiname1463")
            .path("graphql-api")
            .protocols(            
                "http",
                "https")
            .resourceGroupName("rg1")
            .serviceName("apimService1")
            .serviceUrl("https://api.spacex.land/graphql")
            .build());

    }
}

resources:
  api:
    type: azure-native:apimanagement:Api
    properties:
      apiId: tempgroup
      apiType: graphql
      description: apidescription5200
      displayName: apiname1463
      path: graphql-api
      protocols:
        - http
        - https
      resourceGroupName: rg1
      serviceName: apimService1
      serviceUrl: https://api.spacex.land/graphql

The apiType property specifies “graphql” to enable GraphQL-specific handling. The serviceUrl points to your GraphQL backend. Unlike REST APIs, GraphQL uses a single path for all operations. The protocols array typically includes both HTTP and HTTPS.

Beyond these examples

These snippets focus on specific API-level features: API definition and import (manual, OpenAPI, WSDL), versioning and revision management, and authentication configuration (OAuth2, OpenID Connect). They’re intentionally minimal rather than full API gateway configurations.

The examples reference pre-existing infrastructure such as API Management service instances, resource groups, authorization servers and OpenID Connect providers, and backend services (REST, GraphQL, SOAP, WebSocket). They focus on configuring the API rather than provisioning the surrounding infrastructure.

To keep things focused, common API patterns are omitted, including:

Operation-level configuration (methods, request/response schemas)
Policy attachments (rate limiting, transformation, caching)
Product associations and subscription management
Backend configuration (load balancing, circuit breakers)
Diagnostic and monitoring settings
API-level tags and metadata beyond basic properties

These omissions are intentional: the goal is to illustrate how each API feature is wired, not provide drop-in gateway modules. See the API Management Api resource reference for all available configuration options.

Let's configure Azure API Management APIs

Get started with Pulumi Cloud, then follow our quick setup guide to deploy this infrastructure.

Try Pulumi Cloud for FREE

Frequently Asked Questions

API Import & Creation

How do I import an API from a Swagger, OpenAPI, or WSDL specification?

Set format to the appropriate value (swagger-link-json, openapi-link, wsdl-link, etc.) and provide the specification URL in value. For example, to import from OpenAPI 3.0, use format: openapi-link and value: "https://raw.githubusercontent.com/OAI/OpenAPI-Specification/master/examples/v3.0/petstore.yaml".

What does the `translateRequiredQueryParametersConduct` property do?

It controls how required query parameters are handled during OpenAPI import. The default value template converts them to path template parameters, while query keeps them as query parameters.

Can I override the backend service URL when importing an API?

Yes, set serviceUrl to override the backend URL from the imported specification. This is useful when the specification contains a different endpoint than your actual backend.

Versioning & Revisions

What's the difference between API versions and revisions?

Versions are for breaking changes and require apiVersion and apiVersionSetId. Revisions are for non-breaking changes and use the syntax apiId;rev=N (e.g., echo-api;rev=3). Versions can coexist, while revisions replace each other when made current.

How do I create a new version of an API?

Set sourceApiId to the source API’s resource identifier, provide apiVersion (e.g., v4), and set apiVersionSetId to an existing version set. Set isCurrent: true to make it the active version.

How do I create a revision of an API?

Set apiId using the revision syntax (e.g., echo-api;rev=3), provide apiRevisionDescription, set sourceApiId to the base API, and optionally update serviceUrl for the new revision.

How do I clone an existing API?

Set sourceApiId to the resource identifier of the API you want to clone, provide a new apiId and path, and set isCurrent: true. All operations from the source API will be copied.

API Types & Protocols

How do I create a GraphQL API?

Set apiType: graphql, provide the GraphQL endpoint in serviceUrl, and include http and/or https in the protocols array.

How do I create a WebSocket API?

Set apiType: websocket, provide the WebSocket endpoint in serviceUrl (e.g., wss://echo.websocket.org), and include ws and/or wss in the protocols array.

What's the difference between SOAP pass-through and SOAP-to-REST?

For SOAP pass-through, set soapApiType: soap to preserve SOAP operations. For SOAP-to-REST conversion, omit soapApiType and use format: wsdl-link to automatically convert SOAP operations to REST endpoints.

Authentication

Can I configure multiple OAuth2 authorization servers for an API?

Yes, use the oAuth2AuthenticationSettings array within authenticationSettings to specify multiple servers, each with its own authorizationServerId and scope.

Can I configure multiple OpenID Connect providers for an API?

Yes, use the openidAuthenticationSettings array within authenticationSettings to specify multiple providers, each with its own openidProviderId and bearerTokenSendingMethods.

Configuration & Immutability

Can I change the `apiId` after creating an API?

No, apiId is immutable and cannot be changed after creation. Plan your API identifier carefully, especially when using revisions (format: apiId;rev=N).

Using a different cloud?

Explore integration guides for other cloud providers:

AWS Guides GCP Guides