# APIs and Operations

Patterns for managing APIs, operations, and schemas.

## Create API from OpenAPI

```csharp
var apiData = new ApiCreateOrUpdateContent
{
    DisplayName = "Pet Store API",
    Path = "petstore",
    Protocols = { ApiOperationInvokableProtocol.Https },
    // Import from OpenAPI spec
    Format = ContentFormat.OpenApiJson,
    Value = File.ReadAllText("petstore-openapi.json"),
    // Or from URL
    // Format = ContentFormat.OpenApiJsonLink,
    // Value = "https://petstore.swagger.io/v2/swagger.json"
};

var api = await service.GetApis()
    .CreateOrUpdateAsync(WaitUntil.Completed, "petstore-api", apiData);
```

## Create API Manually

```csharp
var apiData = new ApiCreateOrUpdateContent
{
    DisplayName = "Custom API",
    Path = "custom",
    Protocols = { ApiOperationInvokableProtocol.Https },
    ServiceUri = new Uri("https://backend.contoso.com"),
    SubscriptionKeyParameterNames = new SubscriptionKeyParameterNamesContract
    {
        Header = "X-API-Key",
        Query = "api-key"
    }
};

var api = await service.GetApis()
    .CreateOrUpdateAsync(WaitUntil.Completed, "custom-api", apiData);
```

## List APIs

```csharp
await foreach (var api in service.GetApis())
{
    Console.WriteLine($"{api.Data.DisplayName}: {api.Data.Path}");
}
```

## Create Operation

```csharp
var operationData = new ApiOperationData
{
    DisplayName = "Get Users",
    Method = "GET",
    UrlTemplate = "/users",
    Description = "Retrieves all users",
    Responses =
    {
        new ResponseContract(200)
        {
            Description = "Success",
            Representations =
            {
                new RepresentationContract("application/json")
            }
        }
    }
};

var operation = await api.Value.GetApiOperations()
    .CreateOrUpdateAsync(WaitUntil.Completed, "get-users", operationData);
```

## Operation with Parameters

```csharp
var operationData = new ApiOperationData
{
    DisplayName = "Get User by ID",
    Method = "GET",
    UrlTemplate = "/users/{userId}",
    TemplateParameters =
    {
        new ParameterContract("userId")
        {
            Description = "User identifier",
            ParameterContractType = "string",
            IsRequired = true
        }
    },
    Request = new RequestContract
    {
        QueryParameters =
        {
            new ParameterContract("include")
            {
                Description = "Related data to include",
                ParameterContractType = "string",
                IsRequired = false
            }
        }
    }
};
```

## API Versioning

```csharp
// Create version set
var versionSetData = new ApiVersionSetData
{
    DisplayName = "My API Versions",
    VersioningScheme = VersioningScheme.Segment // or Header, Query
};

var versionSet = await service.GetApiVersionSets()
    .CreateOrUpdateAsync(WaitUntil.Completed, "my-api-versions", versionSetData);

// Create versioned API
var apiV1Data = new ApiCreateOrUpdateContent
{
    DisplayName = "My API v1",
    Path = "myapi",
    ApiVersion = "v1",
    ApiVersionSetId = versionSet.Value.Id,
    Protocols = { ApiOperationInvokableProtocol.Https }
};

var apiV2Data = new ApiCreateOrUpdateContent
{
    DisplayName = "My API v2",
    Path = "myapi",
    ApiVersion = "v2",
    ApiVersionSetId = versionSet.Value.Id,
    Protocols = { ApiOperationInvokableProtocol.Https }
};
```

## API Revisions

```csharp
// Create revision
var revisionData = new ApiCreateOrUpdateContent
{
    SourceApiId = api.Value.Id,
    Path = api.Value.Data.Path,
    ApiRevisionDescription = "Added new endpoint"
};

var revision = await service.GetApis()
    .CreateOrUpdateAsync(WaitUntil.Completed, "my-api;rev=2", revisionData);

// Make revision current
await revision.Value.UpdateAsync(WaitUntil.Completed, 
    new ApiCreateOrUpdateContent { IsCurrent = true });
```

## Delete API

```csharp
await api.Value.DeleteAsync(WaitUntil.Completed);
```

# Products and Subscriptions

Patterns for managing products, subscriptions, and access control.

## Create Product

```csharp
var productData = new ApiManagementProductData
{
    DisplayName = "Premium",
    Description = "Premium tier with full access",
    IsSubscriptionRequired = true,
    IsApprovalRequired = true,  // Requires admin approval
    SubscriptionsLimit = 5,
    State = ApiManagementProductState.Published,
    Terms = "Terms and conditions for premium tier..."
};

var product = await service.GetApiManagementProducts()
    .CreateOrUpdateAsync(WaitUntil.Completed, "premium", productData);
```

## List Products

```csharp
await foreach (var product in service.GetApiManagementProducts())
{
    Console.WriteLine($"{product.Data.DisplayName}: {product.Data.State}");
}
```

## Add API to Product

```csharp
// Get product
var product = await service.GetApiManagementProductAsync("premium");

// Add API
await product.Value.GetProductApis()
    .CreateOrUpdateAsync(WaitUntil.Completed, "my-api");
```

## Remove API from Product

```csharp
var productApi = await product.Value.GetProductApiAsync("my-api");
await productApi.Value.DeleteAsync(WaitUntil.Completed);
```

## List APIs in Product

```csharp
await foreach (var api in product.Value.GetProductApis())
{
    Console.WriteLine($"  - {api.Data.DisplayName}");
}
```

## Create Subscription

```csharp
// Subscription to product
var subscriptionData = new ApiManagementSubscriptionCreateOrUpdateContent
{
    DisplayName = "Customer A Subscription",
    Scope = $"/products/premium",
    State = ApiManagementSubscriptionState.Active,
    AllowTracing = true
};

var subscription = await service.GetApiManagementSubscriptions()
    .CreateOrUpdateAsync(WaitUntil.Completed, "customer-a-sub", subscriptionData);

// Subscription to specific API
var apiSubscriptionData = new ApiManagementSubscriptionCreateOrUpdateContent
{
    DisplayName = "API-specific Subscription",
    Scope = $"/apis/my-api",
    State = ApiManagementSubscriptionState.Active
};
```

## Get Subscription Keys

```csharp
var secrets = await subscription.Value.GetSecretsAsync();
Console.WriteLine($"Primary Key: {secrets.Value.PrimaryKey}");
Console.WriteLine($"Secondary Key: {secrets.Value.SecondaryKey}");
```

## Regenerate Subscription Keys

```csharp
// Regenerate primary key
await subscription.Value.RegeneratePrimaryKeyAsync();

// Regenerate secondary key
await subscription.Value.RegenerateSecondaryKeyAsync();
```

## List Subscriptions

```csharp
await foreach (var sub in service.GetApiManagementSubscriptions())
{
    Console.WriteLine($"{sub.Data.DisplayName}: {sub.Data.State}");
}
```

## Suspend/Activate Subscription

```csharp
// Suspend
var patch = new ApiManagementSubscriptionPatch
{
    State = ApiManagementSubscriptionState.Suspended
};
await subscription.Value.UpdateAsync(patch);

// Reactivate
patch.State = ApiManagementSubscriptionState.Active;
await subscription.Value.UpdateAsync(patch);
```

## Create User

```csharp
var userData = new ApiManagementUserCreateOrUpdateContent
{
    Email = "user@contoso.com",
    FirstName = "John",
    LastName = "Doe",
    State = ApiManagementUserState.Active,
    Password = "SecurePassword123!"  // Optional, can send invite instead
};

var user = await service.GetApiManagementUsers()
    .CreateOrUpdateAsync(WaitUntil.Completed, "john-doe", userData);
```

## Create Group

```csharp
var groupData = new ApiManagementGroupCreateOrUpdateContent
{
    DisplayName = "Premium Users",
    Description = "Users with premium access",
    GroupContractType = ApiManagementGroupType.Custom
};

var group = await service.GetApiManagementGroups()
    .CreateOrUpdateAsync(WaitUntil.Completed, "premium-users", groupData);
```

## Add User to Group

```csharp
await group.Value.GetGroupUsers()
    .CreateOrUpdateAsync(WaitUntil.Completed, "john-doe");
```

## Add Group to Product

```csharp
await product.Value.GetProductGroups()
    .CreateOrUpdateAsync(WaitUntil.Completed, "premium-users");
```

## Delete Subscription

```csharp
await subscription.Value.DeleteAsync(WaitUntil.Completed);
```

# Service Management

Detailed patterns for managing API Management service instances.

## Get Existing Service

```csharp
// By resource group
var service = await resourceGroup.Value
    .GetApiManagementServiceAsync("my-apim-service");

// By resource ID
var serviceId = ApiManagementServiceResource.CreateResourceIdentifier(
    subscriptionId, "my-resource-group", "my-apim-service");
var service = armClient.GetApiManagementServiceResource(serviceId);
service = await service.GetAsync();
```

## List Services

```csharp
// In resource group
await foreach (var service in resourceGroup.Value.GetApiManagementServices())
{
    Console.WriteLine($"{service.Data.Name}: {service.Data.Location}");
}

// In subscription
await foreach (var service in subscription.GetApiManagementServicesAsync())
{
    Console.WriteLine($"{service.Data.Name}: {service.Data.ResourceGroupName}");
}
```

## Update Service

```csharp
var patch = new ApiManagementServicePatch
{
    PublisherName = "Updated Publisher",
    Tags = { ["environment"] = "production" }
};

var operation = await service.UpdateAsync(WaitUntil.Completed, patch);
```

## Delete Service

```csharp
await service.DeleteAsync(WaitUntil.Completed);
```

## SKU Configuration

```csharp
// Developer (for testing)
var devSku = new ApiManagementServiceSkuProperties(
    ApiManagementServiceSkuType.Developer, capacity: 1);

// Standard with multiple units
var standardSku = new ApiManagementServiceSkuProperties(
    ApiManagementServiceSkuType.Standard, capacity: 2);

// Premium with availability zones
var premiumData = new ApiManagementServiceData(
    location: AzureLocation.EastUS,
    sku: new ApiManagementServiceSkuProperties(
        ApiManagementServiceSkuType.Premium, capacity: 3),
    publisherEmail: "admin@contoso.com",
    publisherName: "Contoso")
{
    Zones = { "1", "2", "3" }
};
```

## Virtual Network Integration

```csharp
var serviceData = new ApiManagementServiceData(
    location: AzureLocation.EastUS,
    sku: new ApiManagementServiceSkuProperties(
        ApiManagementServiceSkuType.Premium, capacity: 1),
    publisherEmail: "admin@contoso.com",
    publisherName: "Contoso")
{
    VirtualNetworkType = VirtualNetworkType.External,
    VirtualNetworkConfiguration = new VirtualNetworkConfiguration
    {
        SubnetResourceId = new ResourceIdentifier(
            "/subscriptions/.../subnets/apim-subnet")
    }
};
```

## Custom Domains

```csharp
var serviceData = new ApiManagementServiceData(...)
{
    HostnameConfigurations =
    {
        new HostnameConfiguration(HostnameType.Proxy)
        {
            HostName = "api.contoso.com",
            CertificateSource = CertificateSource.KeyVault,
            KeyVaultSecretUri = new Uri("https://myvault.vault.azure.net/secrets/api-cert")
        },
        new HostnameConfiguration(HostnameType.DeveloperPortal)
        {
            HostName = "developer.contoso.com",
            CertificateSource = CertificateSource.KeyVault,
            KeyVaultSecretUri = new Uri("https://myvault.vault.azure.net/secrets/portal-cert")
        }
    }
};
```

## Managed Identity

```csharp
var serviceData = new ApiManagementServiceData(...)
{
    Identity = new ManagedServiceIdentity(ManagedServiceIdentityType.SystemAssigned)
};

// Or user-assigned
var serviceData = new ApiManagementServiceData(...)
{
    Identity = new ManagedServiceIdentity(ManagedServiceIdentityType.UserAssigned)
    {
        UserAssignedIdentities =
        {
            [new ResourceIdentifier("/subscriptions/.../userAssignedIdentities/my-identity")] = 
                new UserAssignedIdentity()
        }
    }
};
```

## Get Service Information

```csharp
// Get gateway URL
Console.WriteLine($"Gateway: {service.Data.GatewayUri}");

// Get portal URL
Console.WriteLine($"Portal: {service.Data.DeveloperPortalUri}");

// Get management API URL
Console.WriteLine($"Management: {service.Data.ManagementApiUri}");

// Get provisioning state
Console.WriteLine($"State: {service.Data.ProvisioningState}");
```