Azure.ResourceManager.ApiCenter (.NET)

Centralized API inventory and governance SDK for managing APIs across your organization.

Installation

dotnet add package Azure.ResourceManager.ApiCenter dotnet add package Azure.Identity

Current Version: v1.0.0 (GA)

API Version: 2024-03-01

Environment Variables

AZURE_SUBSCRIPTION_ID=<your-subscription-id> AZURE_RESOURCE_GROUP=<your-resource-group> AZURE_APICENTER_SERVICE_NAME=<your-apicenter-service>

Authentication

using Azure.Identity; using Azure.ResourceManager; using Azure.ResourceManager.ApiCenter;

ArmClient client = new ArmClient(new DefaultAzureCredential());

Resource Hierarchy

Subscription └── ResourceGroup └── ApiCenterService # API inventory service ├── Workspace # Logical grouping of APIs │ ├── Api # API definition │ │ └── ApiVersion # Version of the API │ │ └── ApiDefinition # OpenAPI/GraphQL/etc specification │ ├── Environment # Deployment target (dev/staging/prod) │ └── Deployment # API deployed to environment └── MetadataSchema # Custom metadata definitions

Core Workflows

1. Create API Center Service

using Azure.ResourceManager.ApiCenter; using Azure.ResourceManager.ApiCenter.Models;

ResourceGroupResource resourceGroup = await client .GetDefaultSubscriptionAsync() .Result .GetResourceGroupAsync("my-resource-group");

ApiCenterServiceCollection services = resourceGroup.GetApiCenterServices();

ApiCenterServiceData data = new ApiCenterServiceData(AzureLocation.EastUS) { Identity = new ManagedServiceIdentity(ManagedServiceIdentityType.SystemAssigned) };

ArmOperation<ApiCenterServiceResource> operation = await services .CreateOrUpdateAsync(WaitUntil.Completed, "my-api-center", data);

ApiCenterServiceResource service = operation.Value;

2. Create Workspace

ApiCenterWorkspaceCollection workspaces = service.GetApiCenterWorkspaces();

ApiCenterWorkspaceData workspaceData = new ApiCenterWorkspaceData { Title = "Engineering APIs", Description = "APIs owned by the engineering team" };

ArmOperation<ApiCenterWorkspaceResource> operation = await workspaces .CreateOrUpdateAsync(WaitUntil.Completed, "engineering", workspaceData);

ApiCenterWorkspaceResource workspace = operation.Value;

3. Create API

ApiCenterApiCollection apis = workspace.GetApiCenterApis();

ApiCenterApiData apiData = new ApiCenterApiData { Title = "Orders API", Description = "API for managing customer orders", Kind = ApiKind.Rest, LifecycleStage = ApiLifecycleStage.Production, TermsOfService = new ApiTermsOfService { Uri = new Uri("https://example.com/terms") }, ExternalDocumentation = { new ApiExternalDocumentation { Title = "Documentation", Uri = new Uri("https://docs.example.com/orders") } }, Contacts = { new ApiContact { Name = "API Support", Email = "api-support@example.com" } } };

// Add custom metadata apiData.CustomProperties = BinaryData.FromObjectAsJson(new { team = "orders-team", costCenter = "CC-1234" });

ArmOperation<ApiCenterApiResource> operation = await apis .CreateOrUpdateAsync(WaitUntil.Completed, "orders-api", apiData);

ApiCenterApiResource api = operation.Value;

4. Create API Version

ApiCenterApiVersionCollection versions = api.GetApiCenterApiVersions();

ApiCenterApiVersionData versionData = new ApiCenterApiVersionData { Title = "v1.0.0", LifecycleStage = ApiLifecycleStage.Production };

ArmOperation<ApiCenterApiVersionResource> operation = await versions .CreateOrUpdateAsync(WaitUntil.Completed, "v1-0-0", versionData);

ApiCenterApiVersionResource version = operation.Value;

5. Create API Definition (Upload OpenAPI Spec)

ApiCenterApiDefinitionCollection definitions = version.GetApiCenterApiDefinitions();

ApiCenterApiDefinitionData definitionData = new ApiCenterApiDefinitionData { Title = "OpenAPI Specification", Description = "Orders API OpenAPI 3.0 definition" };

ArmOperation<ApiCenterApiDefinitionResource> operation = await definitions .CreateOrUpdateAsync(WaitUntil.Completed, "openapi", definitionData);

ApiCenterApiDefinitionResource definition = operation.Value;

// Import specification string openApiSpec = await File.ReadAllTextAsync("orders-api.yaml");

ApiSpecImportContent importContent = new ApiSpecImportContent { Format = ApiSpecImportSourceFormat.Inline, Value = openApiSpec, Specification = new ApiSpecImportSpecification { Name = "openapi", Version = "3.0.1" } };

await definition.ImportSpecificationAsync(WaitUntil.Completed, importContent);

6. Export API Specification

ApiCenterApiDefinitionResource definition = await client .GetApiCenterApiDefinitionResource(definitionResourceId) .GetAsync();

ArmOperation<ApiSpecExportResult> operation = await definition .ExportSpecificationAsync(WaitUntil.Completed);

ApiSpecExportResult result = operation.Value;

// result.Format - e.g., "inline" // result.Value - the specification content

7. Create Environment

ApiCenterEnvironmentCollection environments = workspace.GetApiCenterEnvironments();

ApiCenterEnvironmentData envData = new ApiCenterEnvironmentData { Title = "Production", Description = "Production environment", Kind = ApiCenterEnvironmentKind.Production, Server = new ApiCenterEnvironmentServer { ManagementPortalUris = { new Uri("https://portal.azure.com") } }, Onboarding = new EnvironmentOnboardingModel { Instructions = "Contact platform team for access", DeveloperPortalUris = { new Uri("https://developer.example.com") } } };

ArmOperation<ApiCenterEnvironmentResource> operation = await environments .CreateOrUpdateAsync(WaitUntil.Completed, "production", envData);

8. Create Deployment

ApiCenterDeploymentCollection deployments = workspace.GetApiCenterDeployments();

// Get environment resource ID ResourceIdentifier envResourceId = ApiCenterEnvironmentResource.CreateResourceIdentifier( subscriptionId, resourceGroupName, serviceName, workspaceName, "production");

// Get API definition resource ID ResourceIdentifier definitionResourceId = ApiCenterApiDefinitionResource.CreateResourceIdentifier( subscriptionId, resourceGroupName, serviceName, workspaceName, "orders-api", "v1-0-0", "openapi");

ApiCenterDeploymentData deploymentData = new ApiCenterDeploymentData { Title = "Orders API - Production", Description = "Production deployment of Orders API v1.0.0", EnvironmentId = envResourceId, DefinitionId = definitionResourceId, State = ApiCenterDeploymentState.Active, Server = new ApiCenterDeploymentServer { RuntimeUris = { new Uri("https://api.example.com/orders") } } };

ArmOperation<ApiCenterDeploymentResource> operation = await deployments .CreateOrUpdateAsync(WaitUntil.Completed, "orders-api-prod", deploymentData);

9. Create Metadata Schema

ApiCenterMetadataSchemaCollection schemas = service.GetApiCenterMetadataSchemas();

string jsonSchema = """ { "type": "object", "properties": { "team": { "type": "string", "title": "Owning Team" }, "costCenter": { "type": "string", "title": "Cost Center" }, "dataClassification": { "type": "string", "enum": ["public", "internal", "confidential"], "title": "Data Classification" } }, "required": ["team"] } """;

ApiCenterMetadataSchemaData schemaData = new ApiCenterMetadataSchemaData { Schema = jsonSchema, AssignedTo = { new MetadataAssignment { Entity = MetadataAssignmentEntity.Api, Required = true } } };

ArmOperation<ApiCenterMetadataSchemaResource> operation = await schemas .CreateOrUpdateAsync(WaitUntil.Completed, "api-metadata", schemaData);

10. List and Search APIs

// List all APIs in a workspace ApiCenterWorkspaceResource workspace = await client .GetApiCenterWorkspaceResource(workspaceResourceId) .GetAsync();

await foreach (ApiCenterApiResource api in workspace.GetApiCenterApis()) { Console.WriteLine($"API: {api.Data.Title}"); Console.WriteLine($" Kind: {api.Data.Kind}"); Console.WriteLine($" Stage: {api.Data.LifecycleStage}");

// List versions
await foreach (ApiCenterApiVersionResource version in api.GetApiCenterApiVersions())
{
    Console.WriteLine($"  Version: {version.Data.Title}");
}

}

// List environments await foreach (ApiCenterEnvironmentResource env in workspace.GetApiCenterEnvironments()) { Console.WriteLine($"Environment: {env.Data.Title} ({env.Data.Kind})"); }

// List deployments await foreach (ApiCenterDeploymentResource deployment in workspace.GetApiCenterDeployments()) { Console.WriteLine($"Deployment: {deployment.Data.Title}"); Console.WriteLine($" State: {deployment.Data.State}"); }

Key Types Reference

Type Purpose

ApiCenterServiceResource

API Center service instance

ApiCenterWorkspaceResource

Logical grouping of APIs

ApiCenterApiResource

Individual API

ApiCenterApiVersionResource

Version of an API

ApiCenterApiDefinitionResource

API specification (OpenAPI, etc.)

ApiCenterEnvironmentResource

Deployment environment

ApiCenterDeploymentResource

API deployment to environment

ApiCenterMetadataSchemaResource

Custom metadata schema

ApiKind

rest, graphql, grpc, soap, webhook, websocket, mcp

ApiLifecycleStage

design, development, testing, preview, production, deprecated, retired

ApiCenterEnvironmentKind

development, testing, staging, production

ApiCenterDeploymentState

active, inactive

Best Practices

• Organize with workspaces — Group APIs by team, domain, or product

• Use metadata schemas — Define custom properties for governance

• Track lifecycle stages — Keep API status current (design → production → deprecated)

• Document environments — Include onboarding instructions and portal URIs

• Version consistently — Use semantic versioning for API versions

• Import specifications — Upload OpenAPI/GraphQL specs for discovery

• Link deployments — Connect APIs to their runtime environments

• Use managed identity — Enable SystemAssigned identity for secure integrations

Error Handling

using Azure;

try { ArmOperation<ApiCenterApiResource> operation = await apis .CreateOrUpdateAsync(WaitUntil.Completed, "my-api", apiData); } catch (RequestFailedException ex) when (ex.Status == 409) { Console.WriteLine("API already exists with conflicting configuration"); } catch (RequestFailedException ex) when (ex.Status == 400) { Console.WriteLine($"Invalid request: {ex.Message}"); } catch (RequestFailedException ex) { Console.WriteLine($"Azure error: {ex.Status} - {ex.Message}"); }

Related SDKs

SDK Purpose Install

Azure.ResourceManager.ApiCenter

API Center management (this SDK) dotnet add package Azure.ResourceManager.ApiCenter

Azure.ResourceManager.ApiManagement

API gateway and policies dotnet add package Azure.ResourceManager.ApiManagement

Reference Links

Resource URL

NuGet Package https://www.nuget.org/packages/Azure.ResourceManager.ApiCenter

API Reference https://learn.microsoft.com/dotnet/api/azure.resourcemanager.apicenter

Product Documentation https://learn.microsoft.com/azure/api-center/

GitHub Source https://github.com/Azure/azure-sdk-for-net/tree/main/sdk/apicenter/Azure.ResourceManager.ApiCenter