codehava-agent-kit 1.0.1 → 3.0.0

package/templates/.agent/skills/azure-mgmt-apicenter-dotnet/SKILL.md

@@ -0,0 +1,415 @@
+---
+name: azure-mgmt-apicenter-dotnet
+description: Azure API Center SDK for .NET. Centralized API inventory management with governance, versioning, and discovery.
+risk: unknown
+source: community
+date_added: '2026-02-27'
+---
+
+# Azure.ResourceManager.ApiCenter (.NET)
+
+Centralized API inventory and governance SDK for managing APIs across your organization.
+
+## Installation
+
+```bash
+dotnet add package Azure.ResourceManager.ApiCenter
+dotnet add package Azure.Identity
+```
+
+**Current Version**: v1.0.0 (GA)  
+**API Version**: 2024-03-01
+
+## Environment Variables
+
+```bash
+AZURE_SUBSCRIPTION_ID=<your-subscription-id>
+AZURE_RESOURCE_GROUP=<your-resource-group>
+AZURE_APICENTER_SERVICE_NAME=<your-apicenter-service>
+```
+
+## Authentication
+
+```csharp
+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
+
+```csharp
+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
+
+```csharp
+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
+
+```csharp
+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
+
+```csharp
+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)
+
+```csharp
+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
+
+```csharp
+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
+
+```csharp
+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
+
+```csharp
+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
+
+```csharp
+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
+
+```csharp
+// 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
+
+1. **Organize with workspaces** — Group APIs by team, domain, or product
+2. **Use metadata schemas** — Define custom properties for governance
+3. **Track lifecycle stages** — Keep API status current (design → production → deprecated)
+4. **Document environments** — Include onboarding instructions and portal URIs
+5. **Version consistently** — Use semantic versioning for API versions
+6. **Import specifications** — Upload OpenAPI/GraphQL specs for discovery
+7. **Link deployments** — Connect APIs to their runtime environments
+8. **Use managed identity** — Enable SystemAssigned identity for secure integrations
+
+## Error Handling
+
+```csharp
+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 |
+
+## When to Use
+This skill is applicable to execute the workflow or actions described in the overview.

package/templates/.agent/skills/azure-mgmt-apicenter-py/SKILL.md

@@ -0,0 +1,245 @@
+---
+name: azure-mgmt-apicenter-py
+description: Azure API Center Management SDK for Python. Use for managing API inventory, metadata, and governance across your organization.
+risk: unknown
+source: community
+date_added: '2026-02-27'
+---
+
+# Azure API Center Management SDK for Python
+
+Manage API inventory, metadata, and governance in Azure API Center.
+
+## Installation
+
+```bash
+pip install azure-mgmt-apicenter
+pip install azure-identity
+```
+
+## Environment Variables
+
+```bash
+AZURE_SUBSCRIPTION_ID=your-subscription-id
+```
+
+## Authentication
+
+```python
+from azure.identity import DefaultAzureCredential
+from azure.mgmt.apicenter import ApiCenterMgmtClient
+import os
+
+client = ApiCenterMgmtClient(
+    credential=DefaultAzureCredential(),
+    subscription_id=os.environ["AZURE_SUBSCRIPTION_ID"]
+)
+```
+
+## Create API Center
+
+```python
+from azure.mgmt.apicenter.models import Service
+
+api_center = client.services.create_or_update(
+    resource_group_name="my-resource-group",
+    service_name="my-api-center",
+    resource=Service(
+        location="eastus",
+        tags={"environment": "production"}
+    )
+)
+
+print(f"Created API Center: {api_center.name}")
+```
+
+## List API Centers
+
+```python
+api_centers = client.services.list_by_subscription()
+
+for api_center in api_centers:
+    print(f"{api_center.name} - {api_center.location}")
+```
+
+## Register an API
+
+```python
+from azure.mgmt.apicenter.models import Api, ApiKind, LifecycleStage
+
+api = client.apis.create_or_update(
+    resource_group_name="my-resource-group",
+    service_name="my-api-center",
+    workspace_name="default",
+    api_name="my-api",
+    resource=Api(
+        title="My API",
+        description="A sample API for demonstration",
+        kind=ApiKind.REST,
+        lifecycle_stage=LifecycleStage.PRODUCTION,
+        terms_of_service={"url": "https://example.com/terms"},
+        contacts=[{"name": "API Team", "email": "api-team@example.com"}]
+    )
+)
+
+print(f"Registered API: {api.title}")
+```
+
+## Create API Version
+
+```python
+from azure.mgmt.apicenter.models import ApiVersion, LifecycleStage
+
+version = client.api_versions.create_or_update(
+    resource_group_name="my-resource-group",
+    service_name="my-api-center",
+    workspace_name="default",
+    api_name="my-api",
+    version_name="v1",
+    resource=ApiVersion(
+        title="Version 1.0",
+        lifecycle_stage=LifecycleStage.PRODUCTION
+    )
+)
+
+print(f"Created version: {version.title}")
+```
+
+## Add API Definition
+
+```python
+from azure.mgmt.apicenter.models import ApiDefinition
+
+definition = client.api_definitions.create_or_update(
+    resource_group_name="my-resource-group",
+    service_name="my-api-center",
+    workspace_name="default",
+    api_name="my-api",
+    version_name="v1",
+    definition_name="openapi",
+    resource=ApiDefinition(
+        title="OpenAPI Definition",
+        description="OpenAPI 3.0 specification"
+    )
+)
+```
+
+## Import API Specification
+
+```python
+from azure.mgmt.apicenter.models import ApiSpecImportRequest, ApiSpecImportSourceFormat
+
+# Import from inline content
+client.api_definitions.import_specification(
+    resource_group_name="my-resource-group",
+    service_name="my-api-center",
+    workspace_name="default",
+    api_name="my-api",
+    version_name="v1",
+    definition_name="openapi",
+    body=ApiSpecImportRequest(
+        format=ApiSpecImportSourceFormat.INLINE,
+        value='{"openapi": "3.0.0", "info": {"title": "My API", "version": "1.0"}, "paths": {}}'
+    )
+)
+```
+
+## List APIs
+
+```python
+apis = client.apis.list(
+    resource_group_name="my-resource-group",
+    service_name="my-api-center",
+    workspace_name="default"
+)
+
+for api in apis:
+    print(f"{api.name}: {api.title} ({api.kind})")
+```
+
+## Create Environment
+
+```python
+from azure.mgmt.apicenter.models import Environment, EnvironmentKind
+
+environment = client.environments.create_or_update(
+    resource_group_name="my-resource-group",
+    service_name="my-api-center",
+    workspace_name="default",
+    environment_name="production",
+    resource=Environment(
+        title="Production",
+        description="Production environment",
+        kind=EnvironmentKind.PRODUCTION,
+        server={"type": "Azure API Management", "management_portal_uri": ["https://portal.azure.com"]}
+    )
+)
+```
+
+## Create Deployment
+
+```python
+from azure.mgmt.apicenter.models import Deployment, DeploymentState
+
+deployment = client.deployments.create_or_update(
+    resource_group_name="my-resource-group",
+    service_name="my-api-center",
+    workspace_name="default",
+    api_name="my-api",
+    deployment_name="prod-deployment",
+    resource=Deployment(
+        title="Production Deployment",
+        description="Deployed to production APIM",
+        environment_id="/workspaces/default/environments/production",
+        definition_id="/workspaces/default/apis/my-api/versions/v1/definitions/openapi",
+        state=DeploymentState.ACTIVE,
+        server={"runtime_uri": ["https://api.example.com"]}
+    )
+)
+```
+
+## Define Custom Metadata
+
+```python
+from azure.mgmt.apicenter.models import MetadataSchema
+
+metadata = client.metadata_schemas.create_or_update(
+    resource_group_name="my-resource-group",
+    service_name="my-api-center",
+    metadata_schema_name="data-classification",
+    resource=MetadataSchema(
+        schema='{"type": "string", "title": "Data Classification", "enum": ["public", "internal", "confidential"]}'
+    )
+)
+```
+
+## Client Types
+
+| Client | Purpose |
+|--------|---------|
+| `ApiCenterMgmtClient` | Main client for all operations |
+
+## Operations
+
+| Operation Group | Purpose |
+|----------------|---------|
+| `services` | API Center service management |
+| `workspaces` | Workspace management |
+| `apis` | API registration and management |
+| `api_versions` | API version management |
+| `api_definitions` | API definition management |
+| `deployments` | Deployment tracking |
+| `environments` | Environment management |
+| `metadata_schemas` | Custom metadata definitions |
+
+## Best Practices
+
+1. **Use workspaces** to organize APIs by team or domain
+2. **Define metadata schemas** for consistent governance
+3. **Track deployments** to understand where APIs are running
+4. **Import specifications** to enable API analysis and linting
+5. **Use lifecycle stages** to track API maturity
+6. **Add contacts** for API ownership and support
+
+## When to Use
+This skill is applicable to execute the workflow or actions described in the overview.