Azure Mgmt Apicenter Dotnet

1---
2name: azure-mgmt-apicenter-dotnet
3description: |
4  Azure API Center SDK for .NET. Centralized API inventory management with governance, versioning, and discovery. Use for creating API services, workspaces, APIs, versions, definitions, environments, deployments, and metadata schemas. Triggers: "API Center", "ApiCenterService", "ApiCenterWorkspace", "ApiCenterApi", "API inventory", "API governance", "API versioning", "API catalog", "API discovery".
5package: Azure.ResourceManager.ApiCenter
6---
7 
8# Azure.ResourceManager.ApiCenter (.NET)
9 
10Centralized API inventory and governance SDK for managing APIs across your organization.
11 
12## Installation
13 
14```bash
15dotnet add package Azure.ResourceManager.ApiCenter
16dotnet add package Azure.Identity
17```
18 
19**Current Version**: v1.0.0 (GA)  
20**API Version**: 2024-03-01
21 
22## Environment Variables
23 
24```bash
25AZURE_SUBSCRIPTION_ID=<your-subscription-id>
26AZURE_RESOURCE_GROUP=<your-resource-group>
27AZURE_APICENTER_SERVICE_NAME=<your-apicenter-service>
28```
29 
30## Authentication
31 
32```csharp
33using Azure.Identity;
34using Azure.ResourceManager;
35using Azure.ResourceManager.ApiCenter;
36 
37ArmClient client = new ArmClient(new DefaultAzureCredential());
38```
39 
40## Resource Hierarchy
41 
42```
43Subscription
44└── ResourceGroup
45    └── ApiCenterService                    # API inventory service
46        ├── Workspace                       # Logical grouping of APIs
47        │   ├── Api                         # API definition
48        │   │   └── ApiVersion              # Version of the API
49        │   │       └── ApiDefinition       # OpenAPI/GraphQL/etc specification
50        │   ├── Environment                 # Deployment target (dev/staging/prod)
51        │   └── Deployment                  # API deployed to environment
52        └── MetadataSchema                  # Custom metadata definitions
53```
54 
55## Core Workflows
56 
57### 1. Create API Center Service
58 
59```csharp
60using Azure.ResourceManager.ApiCenter;
61using Azure.ResourceManager.ApiCenter.Models;
62 
63ResourceGroupResource resourceGroup = await client
64    .GetDefaultSubscriptionAsync()
65    .Result
66    .GetResourceGroupAsync("my-resource-group");
67 
68ApiCenterServiceCollection services = resourceGroup.GetApiCenterServices();
69 
70ApiCenterServiceData data = new ApiCenterServiceData(AzureLocation.EastUS)
71{
72    Identity = new ManagedServiceIdentity(ManagedServiceIdentityType.SystemAssigned)
73};
74 
75ArmOperation<ApiCenterServiceResource> operation = await services
76    .CreateOrUpdateAsync(WaitUntil.Completed, "my-api-center", data);
77 
78ApiCenterServiceResource service = operation.Value;
79```
80 
81### 2. Create Workspace
82 
83```csharp
84ApiCenterWorkspaceCollection workspaces = service.GetApiCenterWorkspaces();
85 
86ApiCenterWorkspaceData workspaceData = new ApiCenterWorkspaceData
87{
88    Title = "Engineering APIs",
89    Description = "APIs owned by the engineering team"
90};
91 
92ArmOperation<ApiCenterWorkspaceResource> operation = await workspaces
93    .CreateOrUpdateAsync(WaitUntil.Completed, "engineering", workspaceData);
94 
95ApiCenterWorkspaceResource workspace = operation.Value;
96```
97 
98### 3. Create API
99 
100```csharp
101ApiCenterApiCollection apis = workspace.GetApiCenterApis();
102 
103ApiCenterApiData apiData = new ApiCenterApiData
104{
105    Title = "Orders API",
106    Description = "API for managing customer orders",
107    Kind = ApiKind.Rest,
108    LifecycleStage = ApiLifecycleStage.Production,
109    TermsOfService = new ApiTermsOfService
110    {
111        Uri = new Uri("https://example.com/terms")
112    },
113    ExternalDocumentation = 
114    {
115        new ApiExternalDocumentation
116        {
117            Title = "Documentation",
118            Uri = new Uri("https://docs.example.com/orders")
119        }
120    },
121    Contacts =
122    {
123        new ApiContact
124        {
125            Name = "API Support",
126            Email = "api-support@example.com"
127        }
128    }
129};
130 
131// Add custom metadata
132apiData.CustomProperties = BinaryData.FromObjectAsJson(new
133{
134    team = "orders-team",
135    costCenter = "CC-1234"
136});
137 
138ArmOperation<ApiCenterApiResource> operation = await apis
139    .CreateOrUpdateAsync(WaitUntil.Completed, "orders-api", apiData);
140 
141ApiCenterApiResource api = operation.Value;
142```
143 
144### 4. Create API Version
145 
146```csharp
147ApiCenterApiVersionCollection versions = api.GetApiCenterApiVersions();
148 
149ApiCenterApiVersionData versionData = new ApiCenterApiVersionData
150{
151    Title = "v1.0.0",
152    LifecycleStage = ApiLifecycleStage.Production
153};
154 
155ArmOperation<ApiCenterApiVersionResource> operation = await versions
156    .CreateOrUpdateAsync(WaitUntil.Completed, "v1-0-0", versionData);
157 
158ApiCenterApiVersionResource version = operation.Value;
159```
160 
161### 5. Create API Definition (Upload OpenAPI Spec)
162 
163```csharp
164ApiCenterApiDefinitionCollection definitions = version.GetApiCenterApiDefinitions();
165 
166ApiCenterApiDefinitionData definitionData = new ApiCenterApiDefinitionData
167{
168    Title = "OpenAPI Specification",
169    Description = "Orders API OpenAPI 3.0 definition"
170};
171 
172ArmOperation<ApiCenterApiDefinitionResource> operation = await definitions
173    .CreateOrUpdateAsync(WaitUntil.Completed, "openapi", definitionData);
174 
175ApiCenterApiDefinitionResource definition = operation.Value;
176 
177// Import specification
178string openApiSpec = await File.ReadAllTextAsync("orders-api.yaml");
179 
180ApiSpecImportContent importContent = new ApiSpecImportContent
181{
182    Format = ApiSpecImportSourceFormat.Inline,
183    Value = openApiSpec,
184    Specification = new ApiSpecImportSpecification
185    {
186        Name = "openapi",
187        Version = "3.0.1"
188    }
189};
190 
191await definition.ImportSpecificationAsync(WaitUntil.Completed, importContent);
192```
193 
194### 6. Export API Specification
195 
196```csharp
197ApiCenterApiDefinitionResource definition = await client
198    .GetApiCenterApiDefinitionResource(definitionResourceId)
199    .GetAsync();
200 
201ArmOperation<ApiSpecExportResult> operation = await definition
202    .ExportSpecificationAsync(WaitUntil.Completed);
203 
204ApiSpecExportResult result = operation.Value;
205 
206// result.Format - e.g., "inline"
207// result.Value - the specification content
208```
209 
210### 7. Create Environment
211 
212```csharp
213ApiCenterEnvironmentCollection environments = workspace.GetApiCenterEnvironments();
214 
215ApiCenterEnvironmentData envData = new ApiCenterEnvironmentData
216{
217    Title = "Production",
218    Description = "Production environment",
219    Kind = ApiCenterEnvironmentKind.Production,
220    Server = new ApiCenterEnvironmentServer
221    {
222        ManagementPortalUris = { new Uri("https://portal.azure.com") }
223    },
224    Onboarding = new EnvironmentOnboardingModel
225    {
226        Instructions = "Contact platform team for access",
227        DeveloperPortalUris = { new Uri("https://developer.example.com") }
228    }
229};
230 
231ArmOperation<ApiCenterEnvironmentResource> operation = await environments
232    .CreateOrUpdateAsync(WaitUntil.Completed, "production", envData);
233```
234 
235### 8. Create Deployment
236 
237```csharp
238ApiCenterDeploymentCollection deployments = workspace.GetApiCenterDeployments();
239 
240// Get environment resource ID
241ResourceIdentifier envResourceId = ApiCenterEnvironmentResource.CreateResourceIdentifier(
242    subscriptionId, resourceGroupName, serviceName, workspaceName, "production");
243 
244// Get API definition resource ID
245ResourceIdentifier definitionResourceId = ApiCenterApiDefinitionResource.CreateResourceIdentifier(
246    subscriptionId, resourceGroupName, serviceName, workspaceName, 
247    "orders-api", "v1-0-0", "openapi");
248 
249ApiCenterDeploymentData deploymentData = new ApiCenterDeploymentData
250{
251    Title = "Orders API - Production",
252    Description = "Production deployment of Orders API v1.0.0",
253    EnvironmentId = envResourceId,
254    DefinitionId = definitionResourceId,
255    State = ApiCenterDeploymentState.Active,
256    Server = new ApiCenterDeploymentServer
257    {
258        RuntimeUris = { new Uri("https://api.example.com/orders") }
259    }
260};
261 
262ArmOperation<ApiCenterDeploymentResource> operation = await deployments
263    .CreateOrUpdateAsync(WaitUntil.Completed, "orders-api-prod", deploymentData);
264```
265 
266### 9. Create Metadata Schema
267 
268```csharp
269ApiCenterMetadataSchemaCollection schemas = service.GetApiCenterMetadataSchemas();
270 
271string jsonSchema = """
272{
273    "type": "object",
274    "properties": {
275        "team": {
276            "type": "string",
277            "title": "Owning Team"
278        },
279        "costCenter": {
280            "type": "string",
281            "title": "Cost Center"
282        },
283        "dataClassification": {
284            "type": "string",
285            "enum": ["public", "internal", "confidential"],
286            "title": "Data Classification"
287        }
288    },
289    "required": ["team"]
290}
291""";
292 
293ApiCenterMetadataSchemaData schemaData = new ApiCenterMetadataSchemaData
294{
295    Schema = jsonSchema,
296    AssignedTo =
297    {
298        new MetadataAssignment
299        {
300            Entity = MetadataAssignmentEntity.Api,
301            Required = true
302        }
303    }
304};
305 
306ArmOperation<ApiCenterMetadataSchemaResource> operation = await schemas
307    .CreateOrUpdateAsync(WaitUntil.Completed, "api-metadata", schemaData);
308```
309 
310### 10. List and Search APIs
311 
312```csharp
313// List all APIs in a workspace
314ApiCenterWorkspaceResource workspace = await client
315    .GetApiCenterWorkspaceResource(workspaceResourceId)
316    .GetAsync();
317 
318await foreach (ApiCenterApiResource api in workspace.GetApiCenterApis())
319{
320    Console.WriteLine($"API: {api.Data.Title}");
321    Console.WriteLine($"  Kind: {api.Data.Kind}");
322    Console.WriteLine($"  Stage: {api.Data.LifecycleStage}");
323    
324    // List versions
325    await foreach (ApiCenterApiVersionResource version in api.GetApiCenterApiVersions())
326    {
327        Console.WriteLine($"  Version: {version.Data.Title}");
328    }
329}
330 
331// List environments
332await foreach (ApiCenterEnvironmentResource env in workspace.GetApiCenterEnvironments())
333{
334    Console.WriteLine($"Environment: {env.Data.Title} ({env.Data.Kind})");
335}
336 
337// List deployments
338await foreach (ApiCenterDeploymentResource deployment in workspace.GetApiCenterDeployments())
339{
340    Console.WriteLine($"Deployment: {deployment.Data.Title}");
341    Console.WriteLine($"  State: {deployment.Data.State}");
342}
343```
344 
345## Key Types Reference
346 
347| Type | Purpose |
348|------|---------|
349| `ApiCenterServiceResource` | API Center service instance |
350| `ApiCenterWorkspaceResource` | Logical grouping of APIs |
351| `ApiCenterApiResource` | Individual API |
352| `ApiCenterApiVersionResource` | Version of an API |
353| `ApiCenterApiDefinitionResource` | API specification (OpenAPI, etc.) |
354| `ApiCenterEnvironmentResource` | Deployment environment |
355| `ApiCenterDeploymentResource` | API deployment to environment |
356| `ApiCenterMetadataSchemaResource` | Custom metadata schema |
357| `ApiKind` | rest, graphql, grpc, soap, webhook, websocket, mcp |
358| `ApiLifecycleStage` | design, development, testing, preview, production, deprecated, retired |
359| `ApiCenterEnvironmentKind` | development, testing, staging, production |
360| `ApiCenterDeploymentState` | active, inactive |
361 
362## Best Practices
363 
3641. **Organize with workspaces** — Group APIs by team, domain, or product
3652. **Use metadata schemas** — Define custom properties for governance
3663. **Track lifecycle stages** — Keep API status current (design → production → deprecated)
3674. **Document environments** — Include onboarding instructions and portal URIs
3685. **Version consistently** — Use semantic versioning for API versions
3696. **Import specifications** — Upload OpenAPI/GraphQL specs for discovery
3707. **Link deployments** — Connect APIs to their runtime environments
3718. **Use managed identity** — Enable SystemAssigned identity for secure integrations
372 
373## Error Handling
374 
375```csharp
376using Azure;
377 
378try
379{
380    ArmOperation<ApiCenterApiResource> operation = await apis
381        .CreateOrUpdateAsync(WaitUntil.Completed, "my-api", apiData);
382}
383catch (RequestFailedException ex) when (ex.Status == 409)
384{
385    Console.WriteLine("API already exists with conflicting configuration");
386}
387catch (RequestFailedException ex) when (ex.Status == 400)
388{
389    Console.WriteLine($"Invalid request: {ex.Message}");
390}
391catch (RequestFailedException ex)
392{
393    Console.WriteLine($"Azure error: {ex.Status} - {ex.Message}");
394}
395```
396 
397## Related SDKs
398 
399| SDK | Purpose | Install |
400|-----|---------|---------|
401| `Azure.ResourceManager.ApiCenter` | API Center management (this SDK) | `dotnet add package Azure.ResourceManager.ApiCenter` |
402| `Azure.ResourceManager.ApiManagement` | API gateway and policies | `dotnet add package Azure.ResourceManager.ApiManagement` |
403 
404## Reference Links
405 
406| Resource | URL |
407|----------|-----|
408| NuGet Package | https://www.nuget.org/packages/Azure.ResourceManager.ApiCenter |
409| API Reference | https://learn.microsoft.com/dotnet/api/azure.resourcemanager.apicenter |
410| Product Documentation | https://learn.microsoft.com/azure/api-center/ |
411| GitHub Source | https://github.com/Azure/azure-sdk-for-net/tree/main/sdk/apicenter/Azure.ResourceManager.ApiCenter |
412