dohertj2/jdescopingtool
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
b31fd35575b55ae2bf2e0280fe2f2cfaa0e5e1e7
jdescopingtool/PLANS/2026-01-06-api-client-contracts-implementation.md
T
Joseph Doherty d4135e8ad3 fix(data-access): correct self-referential SQL in WorkCenter filter 
The WHERE clause was comparing Code to itself instead of the aliased
table reference, which would always be true.
2026-01-06 14:12:07 -05:00

1291 lines
40 KiB
Markdown
Raw Blame History

# API Client Contracts Implementation Plan
> **For Claude:** REQUIRED SUB-SKILL: Use superpowers:executing-plans to implement this plan task-by-task.
**Goal:** Implement shared API contracts in Core that ensure compile-time safety for URLs, parameters, and return types between API and Client projects.
**Architecture:** Shared `ApiRoutes` constants define URLs usable in controller attributes and client code. Client interfaces (`ISearchApiClient`, etc.) return `ApiResult<T>` using OneOf for type-safe error handling. Controllers continue returning `ActionResult<T>` with proper HTTP semantics.
**Tech Stack:** .NET 10, OneOf library, Blazor WebAssembly, ASP.NET Core Web API
---
## Task 1: Add OneOf Package to Core
**Files:**
- Modify: `NEW/src/JdeScoping.Core/JdeScoping.Core.csproj`
**Step 1: Add OneOf package reference**
Add to the `<ItemGroup>` containing PackageReferences in `JdeScoping.Core.csproj`:
```xml
<PackageReference Include="OneOf" Version="3.0.271" />
```
**Step 2: Verify package restores**
Run: `dotnet restore NEW/src/JdeScoping.Core/JdeScoping.Core.csproj`
Expected: Restore completed successfully
**Step 3: Commit**
```bash
git add NEW/src/JdeScoping.Core/JdeScoping.Core.csproj
git commit -m "chore: add OneOf package to Core for API result types"
```
---
## Task 2: Create Result Types - Error Markers
**Files:**
- Create: `NEW/src/JdeScoping.Core/ApiContracts/Results/NotFound.cs`
- Create: `NEW/src/JdeScoping.Core/ApiContracts/Results/Unauthorized.cs`
- Create: `NEW/src/JdeScoping.Core/ApiContracts/Results/Forbidden.cs`
- Create: `NEW/src/JdeScoping.Core/ApiContracts/Results/Unit.cs`
**Step 1: Create NotFound.cs**
```csharp
namespace JdeScoping.Core.ApiContracts.Results;
/// <summary>
/// Resource not found (HTTP 404).
/// </summary>
public readonly record struct NotFound;
```
**Step 2: Create Unauthorized.cs**
```csharp
namespace JdeScoping.Core.ApiContracts.Results;
/// <summary>
/// Authentication required (HTTP 401).
/// </summary>
public readonly record struct Unauthorized;
```
**Step 3: Create Forbidden.cs**
```csharp
namespace JdeScoping.Core.ApiContracts.Results;
/// <summary>
/// Access denied (HTTP 403).
/// </summary>
public readonly record struct Forbidden;
```
**Step 4: Create Unit.cs**
```csharp
namespace JdeScoping.Core.ApiContracts.Results;
/// <summary>
/// Empty success type for void operations.
/// </summary>
public readonly record struct Unit;
```
**Step 5: Verify build**
Run: `dotnet build NEW/src/JdeScoping.Core/JdeScoping.Core.csproj`
Expected: Build succeeded
**Step 6: Commit**
```bash
git add NEW/src/JdeScoping.Core/ApiContracts/Results/
git commit -m "feat: add empty marker result types (NotFound, Unauthorized, Forbidden, Unit)"
```
---
## Task 3: Create Result Types - Error Types with Data
**Files:**
- Create: `NEW/src/JdeScoping.Core/ApiContracts/Results/ValidationError.cs`
- Create: `NEW/src/JdeScoping.Core/ApiContracts/Results/ApiError.cs`
**Step 1: Create ValidationError.cs**
```csharp
namespace JdeScoping.Core.ApiContracts.Results;
/// <summary>
/// Validation failed (HTTP 400) with field-level errors.
/// Maps to ASP.NET Core ValidationProblemDetails format.
/// </summary>
/// <param name="FieldErrors">Dictionary mapping field names to error messages.</param>
public readonly record struct ValidationError(IReadOnlyDictionary<string, string[]> FieldErrors)
{
/// <summary>
/// Creates a ValidationError from a dictionary of field errors.
/// </summary>
public static ValidationError FromDictionary(Dictionary<string, string[]> errors)
=> new(errors);
}
```
**Step 2: Create ApiError.cs**
```csharp
namespace JdeScoping.Core.ApiContracts.Results;
/// <summary>
/// General API error with message and optional status code.
/// </summary>
/// <param name="Message">Error message describing what went wrong.</param>
/// <param name="StatusCode">Optional HTTP status code.</param>
public readonly record struct ApiError(string Message, int? StatusCode = null);
```
**Step 3: Verify build**
Run: `dotnet build NEW/src/JdeScoping.Core/JdeScoping.Core.csproj`
Expected: Build succeeded
**Step 4: Commit**
```bash
git add NEW/src/JdeScoping.Core/ApiContracts/Results/
git commit -m "feat: add ValidationError and ApiError result types"
```
---
## Task 4: Create ApiResult<T> Type
**Files:**
- Create: `NEW/src/JdeScoping.Core/ApiContracts/Results/ApiResult.cs`
**Step 1: Create ApiResult.cs**
```csharp
using OneOf;
namespace JdeScoping.Core.ApiContracts.Results;
/// <summary>
/// Standard API result type for client-side operations.
/// Represents either success with value T, or one of several error types.
/// </summary>
/// <typeparam name="T">The success value type.</typeparam>
[GenerateOneOf]
public partial class ApiResult<T> : OneOfBase<T, NotFound, ValidationError, Unauthorized, Forbidden, ApiError>
{
/// <summary>Returns true if the result is a success value.</summary>
public bool IsSuccess => IsT0;
/// <summary>Returns true if the result is NotFound.</summary>
public bool IsNotFound => IsT1;
/// <summary>Returns true if the result is a ValidationError.</summary>
public bool IsValidationError => IsT2;
/// <summary>Returns true if the result is Unauthorized.</summary>
public bool IsUnauthorized => IsT3;
/// <summary>Returns true if the result is Forbidden.</summary>
public bool IsForbidden => IsT4;
/// <summary>Returns true if the result is an ApiError.</summary>
public bool IsError => IsT5;
/// <summary>Gets the success value. Throws if not a success.</summary>
public T Value => AsT0;
/// <summary>Gets the validation error. Throws if not a validation error.</summary>
public ValidationError ValidationError => AsT2;
/// <summary>Gets the API error. Throws if not an API error.</summary>
public ApiError Error => AsT5;
}
```
**Step 2: Verify build**
Run: `dotnet build NEW/src/JdeScoping.Core/JdeScoping.Core.csproj`
Expected: Build succeeded
**Step 3: Commit**
```bash
git add NEW/src/JdeScoping.Core/ApiContracts/Results/ApiResult.cs
git commit -m "feat: add ApiResult<T> discriminated union type using OneOf"
```
---
## Task 5: Create ApiRoutes - Search Routes
**Files:**
- Create: `NEW/src/JdeScoping.Core/ApiContracts/ApiRoutes.cs`
**Step 1: Create ApiRoutes.cs with Search routes**
```csharp
namespace JdeScoping.Core.ApiContracts;
/// <summary>
/// Shared API route constants. Use in controller attributes and client implementations.
/// </summary>
public static class ApiRoutes
{
/// <summary>
/// Routes for search API endpoints.
/// </summary>
public static class Search
{
/// <summary>Base route for search endpoints.</summary>
public const string Base = "api/search";
/// <summary>Route for queued searches.</summary>
public const string Queue = "api/search/queue";
/// <summary>Route template for getting a search by ID (use in controller attributes).</summary>
public const string ById = "{id:int}";
/// <summary>Route template for copying a search (use in controller attributes).</summary>
public const string Copy = "{id:int}/copy";
/// <summary>Route template for getting search results (use in controller attributes).</summary>
public const string Results = "{id:int}/results";
/// <summary>Builds the route to get a specific search.</summary>
public static string GetById(int id) => $"api/search/{id}";
/// <summary>Builds the route to copy a search.</summary>
public static string GetCopy(int id) => $"api/search/{id}/copy";
/// <summary>Builds the route to get search results.</summary>
public static string GetResults(int id) => $"api/search/{id}/results";
}
}
```
**Step 2: Verify build**
Run: `dotnet build NEW/src/JdeScoping.Core/JdeScoping.Core.csproj`
Expected: Build succeeded
**Step 3: Commit**
```bash
git add NEW/src/JdeScoping.Core/ApiContracts/ApiRoutes.cs
git commit -m "feat: add ApiRoutes.Search constants and builder methods"
```
---
## Task 6: Add ApiRoutes - Lookup Routes
**Files:**
- Modify: `NEW/src/JdeScoping.Core/ApiContracts/ApiRoutes.cs`
**Step 1: Add Lookup routes to ApiRoutes.cs**
Add the following class inside the `ApiRoutes` class, after the `Search` class:
```csharp
/// <summary>
/// Routes for lookup/autocomplete API endpoints.
/// </summary>
public static class Lookup
{
/// <summary>Base route for lookup endpoints.</summary>
public const string Base = "api/lookup";
/// <summary>Route for item lookup.</summary>
public const string Items = "api/lookup/items";
/// <summary>Route for profit center lookup.</summary>
public const string ProfitCenters = "api/lookup/profit-centers";
/// <summary>Route for work center lookup.</summary>
public const string WorkCenters = "api/lookup/work-centers";
/// <summary>Route for operator lookup.</summary>
public const string Operators = "api/lookup/operators";
/// <summary>Builds the route to find items with URL-encoded query.</summary>
public static string FindItems(string query) => $"{Items}?q={Uri.EscapeDataString(query)}";
/// <summary>Builds the route to find profit centers with URL-encoded query.</summary>
public static string FindProfitCenters(string query) => $"{ProfitCenters}?q={Uri.EscapeDataString(query)}";
/// <summary>Builds the route to find work centers with URL-encoded query.</summary>
public static string FindWorkCenters(string query) => $"{WorkCenters}?q={Uri.EscapeDataString(query)}";
/// <summary>Builds the route to find operators with URL-encoded query.</summary>
public static string FindOperators(string query) => $"{Operators}?q={Uri.EscapeDataString(query)}";
}
```
**Step 2: Verify build**
Run: `dotnet build NEW/src/JdeScoping.Core/JdeScoping.Core.csproj`
Expected: Build succeeded
**Step 3: Commit**
```bash
git add NEW/src/JdeScoping.Core/ApiContracts/ApiRoutes.cs
git commit -m "feat: add ApiRoutes.Lookup constants with URL encoding"
```
---
## Task 7: Add ApiRoutes - Auth Routes
**Files:**
- Modify: `NEW/src/JdeScoping.Core/ApiContracts/ApiRoutes.cs`
**Step 1: Add Auth routes to ApiRoutes.cs**
Add the following class inside the `ApiRoutes` class:
```csharp
/// <summary>
/// Routes for authentication API endpoints.
/// </summary>
public static class Auth
{
/// <summary>Base route for auth endpoints.</summary>
public const string Base = "api/auth";
/// <summary>Route to get the public key for credential encryption.</summary>
public const string PublicKey = "api/auth/public-key";
/// <summary>Route for login.</summary>
public const string Login = "api/auth/login";
/// <summary>Route for logout.</summary>
public const string Logout = "api/auth/logout";
/// <summary>Route to get current user info.</summary>
public const string Me = "api/auth/me";
}
```
**Step 2: Verify build**
Run: `dotnet build NEW/src/JdeScoping.Core/JdeScoping.Core.csproj`
Expected: Build succeeded
**Step 3: Commit**
```bash
git add NEW/src/JdeScoping.Core/ApiContracts/ApiRoutes.cs
git commit -m "feat: add ApiRoutes.Auth constants"
```
---
## Task 8: Add ApiRoutes - FileIO Routes
**Files:**
- Modify: `NEW/src/JdeScoping.Core/ApiContracts/ApiRoutes.cs`
**Step 1: Add FileIO routes to ApiRoutes.cs**
Add the following class inside the `ApiRoutes` class:
```csharp
/// <summary>
/// Routes for file upload/download API endpoints.
/// </summary>
public static class FileIO
{
/// <summary>Base route for file IO endpoints.</summary>
public const string Base = "api/fileio";
/// <summary>Route to download work orders template.</summary>
public const string DownloadWorkOrders = "api/fileio/workorders/download";
/// <summary>Route to download items template.</summary>
public const string DownloadItems = "api/fileio/items/download";
/// <summary>Route to download component lots template.</summary>
public const string DownloadComponentLots = "api/fileio/componentlots/download";
/// <summary>Route to download part operations template.</summary>
public const string DownloadPartOperations = "api/fileio/partoperations/download";
/// <summary>Route to upload work orders.</summary>
public const string UploadWorkOrders = "api/fileio/workorders/upload";
/// <summary>Route to upload items.</summary>
public const string UploadItems = "api/fileio/items/upload";
/// <summary>Route to upload component lots.</summary>
public const string UploadComponentLots = "api/fileio/componentlots/upload";
/// <summary>Route to upload part operations.</summary>
public const string UploadPartOperations = "api/fileio/partoperations/upload";
}
```
**Step 2: Verify build**
Run: `dotnet build NEW/src/JdeScoping.Core/JdeScoping.Core.csproj`
Expected: Build succeeded
**Step 3: Commit**
```bash
git add NEW/src/JdeScoping.Core/ApiContracts/ApiRoutes.cs
git commit -m "feat: add ApiRoutes.FileIO constants"
```
---
## Task 9: Create ISearchApiClient Interface
**Files:**
- Create: `NEW/src/JdeScoping.Core/ApiContracts/ISearchApiClient.cs`
**Step 1: Create ISearchApiClient.cs**
```csharp
using JdeScoping.Core.ApiContracts.Results;
using JdeScoping.Core.ViewModels;
namespace JdeScoping.Core.ApiContracts;
/// <summary>
/// Client contract for search API operations.
/// </summary>
public interface ISearchApiClient
{
/// <summary>Gets all searches for the current user.</summary>
Task<ApiResult<IReadOnlyList<SearchViewModel>>> GetUserSearchesAsync(CancellationToken ct = default);
/// <summary>Gets all queued searches.</summary>
Task<ApiResult<IReadOnlyList<SearchViewModel>>> GetQueuedSearchesAsync(CancellationToken ct = default);
/// <summary>Gets a specific search by ID.</summary>
Task<ApiResult<SearchViewModel>> GetSearchAsync(int id, CancellationToken ct = default);
/// <summary>Copies an existing search to create a new one (returns copy without persisting).</summary>
Task<ApiResult<SearchViewModel>> CopySearchAsync(int id, CancellationToken ct = default);
/// <summary>Creates and submits a new search.</summary>
Task<ApiResult<int>> CreateSearchAsync(SearchViewModel search, CancellationToken ct = default);
/// <summary>Downloads the results for a completed search as Excel bytes.</summary>
Task<ApiResult<byte[]>> GetResultsAsync(int id, CancellationToken ct = default);
}
```
**Step 2: Verify build**
Run: `dotnet build NEW/src/JdeScoping.Core/JdeScoping.Core.csproj`
Expected: Build succeeded
**Step 3: Commit**
```bash
git add NEW/src/JdeScoping.Core/ApiContracts/ISearchApiClient.cs
git commit -m "feat: add ISearchApiClient interface"
```
---
## Task 10: Create ILookupApiClient Interface
**Files:**
- Create: `NEW/src/JdeScoping.Core/ApiContracts/ILookupApiClient.cs`
**Step 1: Create ILookupApiClient.cs**
```csharp
using JdeScoping.Core.ApiContracts.Results;
using JdeScoping.Core.ViewModels;
namespace JdeScoping.Core.ApiContracts;
/// <summary>
/// Client contract for lookup/autocomplete API operations.
/// </summary>
public interface ILookupApiClient
{
/// <summary>Finds items matching the search query.</summary>
Task<ApiResult<IReadOnlyList<ItemViewModel>>> FindItemsAsync(string query, CancellationToken ct = default);
/// <summary>Finds profit centers matching the search query.</summary>
Task<ApiResult<IReadOnlyList<ProfitCenterViewModel>>> FindProfitCentersAsync(string query, CancellationToken ct = default);
/// <summary>Finds work centers matching the search query.</summary>
Task<ApiResult<IReadOnlyList<WorkCenterViewModel>>> FindWorkCentersAsync(string query, CancellationToken ct = default);
/// <summary>Finds operators (JDE users) matching the search query.</summary>
Task<ApiResult<IReadOnlyList<JdeUserViewModel>>> FindOperatorsAsync(string query, CancellationToken ct = default);
}
```
**Step 2: Verify build**
Run: `dotnet build NEW/src/JdeScoping.Core/JdeScoping.Core.csproj`
Expected: Build succeeded
**Step 3: Commit**
```bash
git add NEW/src/JdeScoping.Core/ApiContracts/ILookupApiClient.cs
git commit -m "feat: add ILookupApiClient interface"
```
---
## Task 11: Create IAuthApiClient Interface
**Files:**
- Create: `NEW/src/JdeScoping.Core/ApiContracts/IAuthApiClient.cs`
**Step 1: Create IAuthApiClient.cs**
```csharp
using JdeScoping.Core.ApiContracts.Results;
using JdeScoping.Core.Models;
using JdeScoping.Core.Models.Auth;
namespace JdeScoping.Core.ApiContracts;
/// <summary>
/// Client contract for authentication API operations.
/// </summary>
public interface IAuthApiClient
{
/// <summary>Gets the server's RSA public key for encrypting login credentials.</summary>
Task<ApiResult<PublicKeyResponse>> GetPublicKeyAsync(CancellationToken ct = default);
/// <summary>Authenticates with encrypted credentials.</summary>
Task<ApiResult<LoginResultModel>> LoginAsync(EncryptedLoginRequest request, CancellationToken ct = default);
/// <summary>Logs out the current user.</summary>
Task<ApiResult<Unit>> LogoutAsync(CancellationToken ct = default);
/// <summary>Gets the current authenticated user's information.</summary>
Task<ApiResult<UserInfo>> GetCurrentUserAsync(CancellationToken ct = default);
}
```
**Step 2: Verify build**
Run: `dotnet build NEW/src/JdeScoping.Core/JdeScoping.Core.csproj`
Expected: Build succeeded
**Step 3: Commit**
```bash
git add NEW/src/JdeScoping.Core/ApiContracts/IAuthApiClient.cs
git commit -m "feat: add IAuthApiClient interface"
```
---
## Task 12: Create IFileApiClient Interface
**Files:**
- Create: `NEW/src/JdeScoping.Core/ApiContracts/IFileApiClient.cs`
**Step 1: Create IFileApiClient.cs**
```csharp
using JdeScoping.Core.ApiContracts.Results;
using JdeScoping.Core.ViewModels;
namespace JdeScoping.Core.ApiContracts;
/// <summary>
/// Client contract for file upload/download API operations.
/// Note: Uses Stream for client-side; controllers use IFormFile.
/// </summary>
public interface IFileApiClient
{
// Downloads (POST with existing data, returns Excel bytes)
/// <summary>Downloads work orders template, optionally pre-filled with existing data.</summary>
Task<ApiResult<byte[]>> DownloadWorkOrdersTemplateAsync(IReadOnlyList<WorkOrderViewModel>? existingData = null, CancellationToken ct = default);
/// <summary>Downloads items template, optionally pre-filled with existing data.</summary>
Task<ApiResult<byte[]>> DownloadItemsTemplateAsync(IReadOnlyList<ItemViewModel>? existingData = null, CancellationToken ct = default);
/// <summary>Downloads component lots template, optionally pre-filled with existing data.</summary>
Task<ApiResult<byte[]>> DownloadComponentLotsTemplateAsync(IReadOnlyList<LotViewModel>? existingData = null, CancellationToken ct = default);
/// <summary>Downloads part operations template, optionally pre-filled with existing data.</summary>
Task<ApiResult<byte[]>> DownloadPartOperationsTemplateAsync(IReadOnlyList<PartOperationViewModel>? existingData = null, CancellationToken ct = default);
// Uploads (multipart form, returns parsed data)
/// <summary>Uploads work orders Excel file and returns parsed data.</summary>
Task<ApiResult<IReadOnlyList<WorkOrderViewModel>>> UploadWorkOrdersAsync(Stream fileStream, string fileName, CancellationToken ct = default);
/// <summary>Uploads items Excel file and returns parsed data.</summary>
Task<ApiResult<IReadOnlyList<ItemViewModel>>> UploadItemsAsync(Stream fileStream, string fileName, CancellationToken ct = default);
/// <summary>Uploads component lots Excel file and returns parsed data.</summary>
Task<ApiResult<IReadOnlyList<LotViewModel>>> UploadComponentLotsAsync(Stream fileStream, string fileName, CancellationToken ct = default);
/// <summary>Uploads part operations Excel file and returns parsed data.</summary>
Task<ApiResult<IReadOnlyList<PartOperationViewModel>>> UploadPartOperationsAsync(Stream fileStream, string fileName, CancellationToken ct = default);
}
```
**Step 2: Verify build**
Run: `dotnet build NEW/src/JdeScoping.Core/JdeScoping.Core.csproj`
Expected: Build succeeded
**Step 3: Commit**
```bash
git add NEW/src/JdeScoping.Core/ApiContracts/IFileApiClient.cs
git commit -m "feat: add IFileApiClient interface"
```
---
## Task 13: Create ApiClientBase in Client Project
**Files:**
- Create: `NEW/src/JdeScoping.Client/Services/ApiClientBase.cs`
**Step 1: Create ApiClientBase.cs**
```csharp
using System.Net;
using System.Net.Http.Json;
using System.Text.Json;
using JdeScoping.Core.ApiContracts.Results;
namespace JdeScoping.Client.Services;
/// <summary>
/// Base class for API clients with shared HTTP execution logic.
/// </summary>
public abstract class ApiClientBase
{
protected readonly HttpClient HttpClient;
private static readonly JsonSerializerOptions JsonOptions = new()
{
PropertyNameCaseInsensitive = true
};
protected ApiClientBase(HttpClient httpClient)
{
HttpClient = httpClient;
}
protected async Task<ApiResult<T>> GetAsync<T>(string route, CancellationToken ct = default)
{
return await ExecuteAsync<T>(() => HttpClient.GetAsync(route, ct));
}
protected async Task<ApiResult<T>> PostAsync<T, TBody>(string route, TBody body, CancellationToken ct = default)
{
return await ExecuteAsync<T>(() => HttpClient.PostAsJsonAsync(route, body, ct));
}
protected async Task<ApiResult<T>> PostAsync<T>(string route, CancellationToken ct = default)
{
return await ExecuteAsync<T>(() => HttpClient.PostAsync(route, null, ct));
}
protected async Task<ApiResult<byte[]>> GetBytesAsync(string route, CancellationToken ct = default)
{
try
{
var response = await HttpClient.GetAsync(route, ct);
return await MapResponseToBytesAsync(response);
}
catch (Exception ex)
{
return new ApiError(ex.Message);
}
}
protected async Task<ApiResult<byte[]>> PostForBytesAsync<TBody>(string route, TBody body, CancellationToken ct = default)
{
try
{
var response = await HttpClient.PostAsJsonAsync(route, body, ct);
return await MapResponseToBytesAsync(response);
}
catch (Exception ex)
{
return new ApiError(ex.Message);
}
}
protected async Task<ApiResult<T>> PostMultipartAsync<T>(
string route,
Stream fileStream,
string fileName,
CancellationToken ct = default)
{
try
{
using var content = new MultipartFormDataContent();
using var streamContent = new StreamContent(fileStream);
content.Add(streamContent, "file", fileName);
var response = await HttpClient.PostAsync(route, content, ct);
return await MapResponseAsync<T>(response);
}
catch (Exception ex)
{
return new ApiError(ex.Message);
}
}
private async Task<ApiResult<T>> ExecuteAsync<T>(Func<Task<HttpResponseMessage>> request)
{
try
{
var response = await request();
return await MapResponseAsync<T>(response);
}
catch (Exception ex)
{
return new ApiError(ex.Message);
}
}
private async Task<ApiResult<T>> MapResponseAsync<T>(HttpResponseMessage response)
{
return response.StatusCode switch
{
HttpStatusCode.OK or HttpStatusCode.Created =>
await response.Content.ReadFromJsonAsync<T>(JsonOptions)
is T value ? value : new ApiError("Invalid response format"),
HttpStatusCode.NoContent =>
typeof(T) == typeof(Unit) ? (ApiResult<T>)(object)new Unit() : new ApiError("Unexpected empty response"),
HttpStatusCode.NotFound => new NotFound(),
HttpStatusCode.Unauthorized => new Unauthorized(),
HttpStatusCode.Forbidden => new Forbidden(),
HttpStatusCode.BadRequest => await ParseValidationErrorAsync<T>(response),
_ => new ApiError(
await response.Content.ReadAsStringAsync(),
(int)response.StatusCode)
};
}
private async Task<ApiResult<byte[]>> MapResponseToBytesAsync(HttpResponseMessage response)
{
return response.StatusCode switch
{
HttpStatusCode.OK => await response.Content.ReadAsByteArrayAsync(),
HttpStatusCode.NotFound => new NotFound(),
HttpStatusCode.Unauthorized => new Unauthorized(),
HttpStatusCode.Forbidden => new Forbidden(),
_ => new ApiError(
await response.Content.ReadAsStringAsync(),
(int)response.StatusCode)
};
}
private static async Task<ApiResult<T>> ParseValidationErrorAsync<T>(HttpResponseMessage response)
{
try
{
var content = await response.Content.ReadAsStringAsync();
var problemDetails = JsonSerializer.Deserialize<ValidationProblemDetails>(content, JsonOptions);
if (problemDetails?.Errors is { } errors)
{
return new ValidationError(errors);
}
return new ApiError(content, (int)response.StatusCode);
}
catch
{
return new ApiError("Validation error", (int)response.StatusCode);
}
}
/// <summary>
/// Matches ASP.NET Core ValidationProblemDetails structure.
/// </summary>
private sealed class ValidationProblemDetails
{
public Dictionary<string, string[]>? Errors { get; set; }
}
}
```
**Step 2: Verify build**
Run: `dotnet build NEW/src/JdeScoping.Client/JdeScoping.Client.csproj`
Expected: Build succeeded
**Step 3: Commit**
```bash
git add NEW/src/JdeScoping.Client/Services/ApiClientBase.cs
git commit -m "feat: add ApiClientBase with shared HTTP execution logic"
```
---
## Task 14: Create SearchApiClient Implementation
**Files:**
- Create: `NEW/src/JdeScoping.Client/Services/SearchApiClient.cs`
**Step 1: Create SearchApiClient.cs**
```csharp
using JdeScoping.Core.ApiContracts;
using JdeScoping.Core.ApiContracts.Results;
using JdeScoping.Core.ViewModels;
namespace JdeScoping.Client.Services;
/// <summary>
/// HTTP client implementation of ISearchApiClient.
/// </summary>
public class SearchApiClient : ApiClientBase, ISearchApiClient
{
public SearchApiClient(HttpClient httpClient) : base(httpClient) { }
public Task<ApiResult<IReadOnlyList<SearchViewModel>>> GetUserSearchesAsync(CancellationToken ct = default)
=> GetAsync<IReadOnlyList<SearchViewModel>>(ApiRoutes.Search.Base, ct);
public Task<ApiResult<IReadOnlyList<SearchViewModel>>> GetQueuedSearchesAsync(CancellationToken ct = default)
=> GetAsync<IReadOnlyList<SearchViewModel>>(ApiRoutes.Search.Queue, ct);
public Task<ApiResult<SearchViewModel>> GetSearchAsync(int id, CancellationToken ct = default)
=> GetAsync<SearchViewModel>(ApiRoutes.Search.GetById(id), ct);
public Task<ApiResult<SearchViewModel>> CopySearchAsync(int id, CancellationToken ct = default)
=> GetAsync<SearchViewModel>(ApiRoutes.Search.GetCopy(id), ct);
public Task<ApiResult<int>> CreateSearchAsync(SearchViewModel search, CancellationToken ct = default)
=> PostAsync<int, SearchViewModel>(ApiRoutes.Search.Base, search, ct);
public Task<ApiResult<byte[]>> GetResultsAsync(int id, CancellationToken ct = default)
=> GetBytesAsync(ApiRoutes.Search.GetResults(id), ct);
}
```
**Step 2: Verify build**
Run: `dotnet build NEW/src/JdeScoping.Client/JdeScoping.Client.csproj`
Expected: Build succeeded
**Step 3: Commit**
```bash
git add NEW/src/JdeScoping.Client/Services/SearchApiClient.cs
git commit -m "feat: add SearchApiClient implementation"
```
---
## Task 15: Create LookupApiClient Implementation
**Files:**
- Create: `NEW/src/JdeScoping.Client/Services/LookupApiClient.cs`
**Step 1: Create LookupApiClient.cs**
```csharp
using JdeScoping.Core.ApiContracts;
using JdeScoping.Core.ApiContracts.Results;
using JdeScoping.Core.ViewModels;
namespace JdeScoping.Client.Services;
/// <summary>
/// HTTP client implementation of ILookupApiClient.
/// </summary>
public class LookupApiClient : ApiClientBase, ILookupApiClient
{
public LookupApiClient(HttpClient httpClient) : base(httpClient) { }
public Task<ApiResult<IReadOnlyList<ItemViewModel>>> FindItemsAsync(string query, CancellationToken ct = default)
=> GetAsync<IReadOnlyList<ItemViewModel>>(ApiRoutes.Lookup.FindItems(query), ct);
public Task<ApiResult<IReadOnlyList<ProfitCenterViewModel>>> FindProfitCentersAsync(string query, CancellationToken ct = default)
=> GetAsync<IReadOnlyList<ProfitCenterViewModel>>(ApiRoutes.Lookup.FindProfitCenters(query), ct);
public Task<ApiResult<IReadOnlyList<WorkCenterViewModel>>> FindWorkCentersAsync(string query, CancellationToken ct = default)
=> GetAsync<IReadOnlyList<WorkCenterViewModel>>(ApiRoutes.Lookup.FindWorkCenters(query), ct);
public Task<ApiResult<IReadOnlyList<JdeUserViewModel>>> FindOperatorsAsync(string query, CancellationToken ct = default)
=> GetAsync<IReadOnlyList<JdeUserViewModel>>(ApiRoutes.Lookup.FindOperators(query), ct);
}
```
**Step 2: Verify build**
Run: `dotnet build NEW/src/JdeScoping.Client/JdeScoping.Client.csproj`
Expected: Build succeeded
**Step 3: Commit**
```bash
git add NEW/src/JdeScoping.Client/Services/LookupApiClient.cs
git commit -m "feat: add LookupApiClient implementation"
```
---
## Task 16: Create AuthApiClient Implementation
**Files:**
- Create: `NEW/src/JdeScoping.Client/Services/AuthApiClient.cs`
**Step 1: Create AuthApiClient.cs**
```csharp
using JdeScoping.Core.ApiContracts;
using JdeScoping.Core.ApiContracts.Results;
using JdeScoping.Core.Models;
using JdeScoping.Core.Models.Auth;
namespace JdeScoping.Client.Services;
/// <summary>
/// HTTP client implementation of IAuthApiClient.
/// </summary>
public class AuthApiClient : ApiClientBase, IAuthApiClient
{
public AuthApiClient(HttpClient httpClient) : base(httpClient) { }
public Task<ApiResult<PublicKeyResponse>> GetPublicKeyAsync(CancellationToken ct = default)
=> GetAsync<PublicKeyResponse>(ApiRoutes.Auth.PublicKey, ct);
public Task<ApiResult<LoginResultModel>> LoginAsync(EncryptedLoginRequest request, CancellationToken ct = default)
=> PostAsync<LoginResultModel, EncryptedLoginRequest>(ApiRoutes.Auth.Login, request, ct);
public Task<ApiResult<Unit>> LogoutAsync(CancellationToken ct = default)
=> PostAsync<Unit>(ApiRoutes.Auth.Logout, ct);
public Task<ApiResult<UserInfo>> GetCurrentUserAsync(CancellationToken ct = default)
=> GetAsync<UserInfo>(ApiRoutes.Auth.Me, ct);
}
```
**Step 2: Verify build**
Run: `dotnet build NEW/src/JdeScoping.Client/JdeScoping.Client.csproj`
Expected: Build succeeded
**Step 3: Commit**
```bash
git add NEW/src/JdeScoping.Client/Services/AuthApiClient.cs
git commit -m "feat: add AuthApiClient implementation"
```
---
## Task 17: Create FileApiClient Implementation
**Files:**
- Create: `NEW/src/JdeScoping.Client/Services/FileApiClient.cs`
**Step 1: Create FileApiClient.cs**
```csharp
using JdeScoping.Core.ApiContracts;
using JdeScoping.Core.ApiContracts.Results;
using JdeScoping.Core.ViewModels;
namespace JdeScoping.Client.Services;
/// <summary>
/// HTTP client implementation of IFileApiClient.
/// </summary>
public class FileApiClient : ApiClientBase, IFileApiClient
{
public FileApiClient(HttpClient httpClient) : base(httpClient) { }
// Downloads
public Task<ApiResult<byte[]>> DownloadWorkOrdersTemplateAsync(IReadOnlyList<WorkOrderViewModel>? existingData = null, CancellationToken ct = default)
=> PostForBytesAsync(ApiRoutes.FileIO.DownloadWorkOrders, existingData, ct);
public Task<ApiResult<byte[]>> DownloadItemsTemplateAsync(IReadOnlyList<ItemViewModel>? existingData = null, CancellationToken ct = default)
=> PostForBytesAsync(ApiRoutes.FileIO.DownloadItems, existingData, ct);
public Task<ApiResult<byte[]>> DownloadComponentLotsTemplateAsync(IReadOnlyList<LotViewModel>? existingData = null, CancellationToken ct = default)
=> PostForBytesAsync(ApiRoutes.FileIO.DownloadComponentLots, existingData, ct);
public Task<ApiResult<byte[]>> DownloadPartOperationsTemplateAsync(IReadOnlyList<PartOperationViewModel>? existingData = null, CancellationToken ct = default)
=> PostForBytesAsync(ApiRoutes.FileIO.DownloadPartOperations, existingData, ct);
// Uploads
public Task<ApiResult<IReadOnlyList<WorkOrderViewModel>>> UploadWorkOrdersAsync(Stream fileStream, string fileName, CancellationToken ct = default)
=> PostMultipartAsync<IReadOnlyList<WorkOrderViewModel>>(ApiRoutes.FileIO.UploadWorkOrders, fileStream, fileName, ct);
public Task<ApiResult<IReadOnlyList<ItemViewModel>>> UploadItemsAsync(Stream fileStream, string fileName, CancellationToken ct = default)
=> PostMultipartAsync<IReadOnlyList<ItemViewModel>>(ApiRoutes.FileIO.UploadItems, fileStream, fileName, ct);
public Task<ApiResult<IReadOnlyList<LotViewModel>>> UploadComponentLotsAsync(Stream fileStream, string fileName, CancellationToken ct = default)
=> PostMultipartAsync<IReadOnlyList<LotViewModel>>(ApiRoutes.FileIO.UploadComponentLots, fileStream, fileName, ct);
public Task<ApiResult<IReadOnlyList<PartOperationViewModel>>> UploadPartOperationsAsync(Stream fileStream, string fileName, CancellationToken ct = default)
=> PostMultipartAsync<IReadOnlyList<PartOperationViewModel>>(ApiRoutes.FileIO.UploadPartOperations, fileStream, fileName, ct);
}
```
**Step 2: Verify build**
Run: `dotnet build NEW/src/JdeScoping.Client/JdeScoping.Client.csproj`
Expected: Build succeeded
**Step 3: Commit**
```bash
git add NEW/src/JdeScoping.Client/Services/FileApiClient.cs
git commit -m "feat: add FileApiClient implementation"
```
---
## Task 18: Update SearchController to Use ApiRoutes
**Files:**
- Modify: `NEW/src/JdeScoping.Api/Controllers/SearchController.cs`
**Step 1: Add using statement**
Add at the top of the file:
```csharp
using JdeScoping.Core.ApiContracts;
```
**Step 2: Update Route attribute**
Change the class-level `[Route]` attribute from:
```csharp
[Route("api/search")]
```
To:
```csharp
[Route(ApiRoutes.Search.Base)]
```
**Step 3: Verify build**
Run: `dotnet build NEW/src/JdeScoping.Api/JdeScoping.Api.csproj`
Expected: Build succeeded
**Step 4: Commit**
```bash
git add NEW/src/JdeScoping.Api/Controllers/SearchController.cs
git commit -m "refactor: update SearchController to use ApiRoutes constants"
```
---
## Task 19: Update LookupController to Use ApiRoutes
**Files:**
- Modify: `NEW/src/JdeScoping.Api/Controllers/LookupController.cs`
**Step 1: Add using statement**
Add at the top of the file:
```csharp
using JdeScoping.Core.ApiContracts;
```
**Step 2: Update Route attribute**
Change the class-level `[Route]` attribute from:
```csharp
[Route("api/lookup")]
```
To:
```csharp
[Route(ApiRoutes.Lookup.Base)]
```
**Step 3: Verify build**
Run: `dotnet build NEW/src/JdeScoping.Api/JdeScoping.Api.csproj`
Expected: Build succeeded
**Step 4: Commit**
```bash
git add NEW/src/JdeScoping.Api/Controllers/LookupController.cs
git commit -m "refactor: update LookupController to use ApiRoutes constants"
```
---
## Task 20: Update AuthController to Use ApiRoutes
**Files:**
- Modify: `NEW/src/JdeScoping.Api/Controllers/AuthController.cs`
**Step 1: Add using statement**
Add at the top of the file:
```csharp
using JdeScoping.Core.ApiContracts;
```
**Step 2: Update Route attribute**
Change the class-level `[Route]` attribute from:
```csharp
[Route("api/auth")]
```
To:
```csharp
[Route(ApiRoutes.Auth.Base)]
```
**Step 3: Verify build**
Run: `dotnet build NEW/src/JdeScoping.Api/JdeScoping.Api.csproj`
Expected: Build succeeded
**Step 4: Commit**
```bash
git add NEW/src/JdeScoping.Api/Controllers/AuthController.cs
git commit -m "refactor: update AuthController to use ApiRoutes constants"
```
---
## Task 21: Update FileIOController to Use ApiRoutes
**Files:**
- Modify: `NEW/src/JdeScoping.Api/Controllers/FileController.cs`
**Step 1: Add using statement**
Add at the top of the file:
```csharp
using JdeScoping.Core.ApiContracts;
```
**Step 2: Update Route attribute**
Change the class-level `[Route]` attribute from:
```csharp
[Route("api/fileio")]
```
To:
```csharp
[Route(ApiRoutes.FileIO.Base)]
```
**Step 3: Verify build**
Run: `dotnet build NEW/src/JdeScoping.Api/JdeScoping.Api.csproj`
Expected: Build succeeded
**Step 4: Commit**
```bash
git add NEW/src/JdeScoping.Api/Controllers/FileController.cs
git commit -m "refactor: update FileIOController to use ApiRoutes constants"
```
---
## Task 22: Register New API Clients in Client DI
**Files:**
- Modify: `NEW/src/JdeScoping.Client/Program.cs`
**Step 1: Add using statement**
Add at the top of the file:
```csharp
using JdeScoping.Core.ApiContracts;
```
**Step 2: Add new client registrations**
Find where services are registered and add:
```csharp
builder.Services.AddScoped<ISearchApiClient, SearchApiClient>();
builder.Services.AddScoped<ILookupApiClient, LookupApiClient>();
builder.Services.AddScoped<IAuthApiClient, AuthApiClient>();
builder.Services.AddScoped<IFileApiClient, FileApiClient>();
```
**Step 3: Verify build**
Run: `dotnet build NEW/src/JdeScoping.Client/JdeScoping.Client.csproj`
Expected: Build succeeded
**Step 4: Commit**
```bash
git add NEW/src/JdeScoping.Client/Program.cs
git commit -m "feat: register new API clients in Client DI container"
```
---
## Task 23: Full Solution Build Verification
**Files:**
- None (verification only)
**Step 1: Build entire solution**
Run: `dotnet build NEW/JdeScopingTool.sln`
Expected: Build succeeded with no errors
**Step 2: Run existing tests**
Run: `dotnet test NEW/JdeScopingTool.sln --no-build`
Expected: All tests pass
---
## Summary
This implementation plan adds:
1. **Core/ApiContracts/Results/** - Result types (ApiResult, NotFound, ValidationError, etc.)
2. **Core/ApiContracts/ApiRoutes.cs** - Shared route constants
3. **Core/ApiContracts/I*ApiClient.cs** - Client interface contracts
4. **Client/Services/ApiClientBase.cs** - Shared HTTP execution logic
5. **Client/Services/*ApiClient.cs** - Client implementations
6. **Controller updates** - Use ApiRoutes constants
The old services (`SearchService`, `LookupService`, `AuthService`, `FileService`) remain functional. Migration of Blazor components to use the new clients is a separate follow-up task.
Reference in New Issue View Git Blame Copy Permalink