JT - Migrate RoutingApi

[JackTelford]

# PureCloud.Client API Migration Guide

**Goal:**  
Modernize legacy async client methods into `/src/PureCloud.Client/Apis/`, preserving functionality and aligning with current conventions.
---
## 1. Methods

- **ExpectedCount**: `151`  
  ← set this to the total `AsyncWithHttpInfo` methods you expect in the source file  
---
## 2. Core Guidelines

1. **Async-Only**  
   - Migrate only methods marked `async` (e.g. `AsyncWithHttpInfo`).  
   - Retain `async` and add a `CancellationToken cancellationToken = default` parameter.

2. **Single Representative Method**  
   - Migrate one method per API; omit overloads and variations.

3. **Method Naming**  
   - Prefix with: `Get…`, `Create…`, `Update…`, `Delete…`

4. **Reference Pattern**  
   - **Structure & DI** match `/src/PureCloud.Client/Apis/FlowsApi.cs`  
   - **Source:** `/src/PureCloud.Client/OldApis/RoutingApi.cs`  
   - **Target:** `/src/PureCloud.Client/Apis/RoutingApi.cs`
---
## 3. Code Example: FlowsApi
```csharp
/// <inheritdoc />
public sealed class FlowsApi : IFlowsApi
{
    private readonly IHttpClientFactory _httpClientFactory;
    private readonly PureCloudJsonSerializerOptions _options;

    public FlowsApi(
        IHttpClientFactory httpClientFactory,
        IOptions<PureCloudJsonSerializerOptions> options)
    {
        _httpClientFactory = httpClientFactory;
        _options = options.Value;
    }

    /// <inheritdoc />
    public async Task<FlowActivityResponse> CreateAnalyticsFlowsActivityQueryAsync(FlowActivityQuery body, int? pageSize = null, int? pageNumber = null, CancellationToken cancellationToken = default)
    {
        ArgumentNullException.ThrowIfNull(body);

        var parameters = new NameValueCollection();

        if (pageSize.HasValue)
        {
            parameters.Add("pageSize", UriHelper.ParameterToString(pageSize.Value));
        }

        if (pageNumber.HasValue)
        {
            parameters.Add("pageNumber", UriHelper.ParameterToString(pageNumber.Value));
        }

        var client = _httpClientFactory.CreateClient(PureCloudConstants.PureCloudClientName);

        var uri    = UriHelper.GetUri("api/v2/analytics/flows/activity/query", parameters);

        var response = await client.PostAsJsonAsync(uri, body, _options, cancellationToken);
        
        response.EnsureSuccessStatusCode();

        return await response.Content.ReadFromJsonAsync<FlowActivityResponse>(_options, cancellationToken);
    }

     public async Task<bool> DeleteAlertingAlertAsync(string alertId, CancellationToken cancellationToken = default)
    {
        var client = _httpClientFactory.CreateClient(PureCloudConstants.PureCloudClientName);

        var response = await client.DeleteAsync($"api/v2/alerting/alerts/{alertId}", cancellationToken);

        response.EnsureSuccessStatusCode();

        return response.IsSuccessStatusCode;
    }

}
Add new Line after file

---

4. Infrastructure & URI Handling

• HttpClient:

  var client = _httpClientFactory.CreateClient(PureCloudConstants.PureCloudClientName);

• URI builder:

  var uri = UriHelper.GetUri("api/v2/webchat/settings", parameters);

• Query params: use NameValueCollection; only call UriHelper if any parameters exist.
• All Delete methods return bool.
• Escape path parameters: Uri.EscapeDataString(value)

---

5. HTTP & JSON Helpers

Method	Call
GET	await client.GetAsync(uri, cancellationToken)
DELETE	await client.DeleteAsync(uri, cancellationToken)
POST	await client.PostAsJsonAsync(uri, body, _options, cancellationToken)
PUT	await client.PutAsJsonAsync(uri, body, _options, cancellationToken)
PATCH	await client.PatchAsJsonAsync(uri, body, _options, cancellationToken)
Deserialize	return await response.Content.ReadFromJsonAsync<T>(_options, cancellationToken);

---

6. Code Style & Formatting

1. Seal all classes.
2. End each file with a single newline.
3. Document methods with /// <inheritdoc /> and a blank line.
4. Use IEnumerable<> instead of List<>.
5. Return arrays, never List<>.
6. Single-line method signatures (no stacked parameters).
7. Blank line before each return.
8. Validate inputs with ArgumentException.ThrowIfNullOrEmpty(...) (blank line after).
9. Remove all unnecessary comments.
10. IMPORTANT: always add a new line before file end in *.Api.cs and *.Interface.cs.

---

7. Model Migration

1. Convert all partial classes to sealed.
2. Remove all IEquatable<> implementations.
3. Extract enums into <Base>.<Descriptor>.cs (drop “Enum”).
4. Remove [JsonPropertyName], constructors, overrides (ToString(), Equals(), GetHashCode()).
5. Replace List<> properties with IEnumerable<>.

Include Models

• Generate/migrate request & response models under src/PureCloud.Client/Models/.
• Never rename models.
• Apply Model Cleanup rules.
• Add each model to the .csproj.

Model Cleanup Checklist

After generating all files, include:

1. Converted all partial classes to sealed
2. Removed all IEquatable<> implementations
3. Extracted enums into <Base>.<Descriptor>.cs
4. Removed [JsonPropertyName], constructors, overrides
5. Replaced all List<> properties with IEnumerable<>

Then rename the title to completed + Name, and:

• ✅ Include model registration in PureCloud.Client/Extensions/ServiceCollectionExtensions.cs
• ✅ Include models in src/PureCloud.Client/PureCloud.Client.csproj

---

8. URL Coverage Validation

Include a “✅ when completed”:

1. Extract literal URLs from old code.
2. Confirm each appears via UriHelper.GetUri.
3. If missing, add // TODO: Missing URL comment.
4. ✅ Expected AsyncWithHttpInfo methods converted.
5. ✅ Verify count matches ExpectedCount.

---

9. Completion Summary

After migration, provide:

1. List of API & model files created/modified.
2. Confirmation of guideline adherence.
3. URL coverage verification.
4. Notes on special cases or manual fixes.
5. ✅ Model registration in ServiceCollectionExtensions.cs
6. ✅ Models included in .csproj

Do not include extra explanations—output only final C# files ready for
/src/PureCloud.Client/Apis/ and src/PureCloud.Client/Models/.

---

IMPORTANT VALIDATION
Just before completion, run an audit comparing migrated methods to the old code. Ensure every endpoint and parameter validation matches.

---

Naming Conventions

• Collection parameters use plural; loop variables singular.
• Don’t concatenate values—add each to NameValueCollection.
• Always use UriHelper.ParameterToString(...) for values.
• Use simple null checks; avoid .Any().

---

Once finished, change the title to completed + Name and end each file with a newline.