Skip to content

16 01 API Clients Reference

Jump to bottom
Cyberdyne Development edited this page Feb 18, 2026 · 3 revisions

API Clients Reference

Complete reference for the 16 per-domain .Clients packages that provide typed HTTP access to FractalDataWorks REST endpoints. These packages are the HTTP layer in the Headless UI architecture, consumed by Protocol providers in UI.Components.Blazor and available for any .NET consumer that needs programmatic access to FDW APIs.

Architecture Overview

Consumer UI / Application
  |
  +-- Protocol Providers (UI.Components.Blazor)
  |     |
  |     +-- Per-domain .Clients packages (16 total)
  |           |
  |           +-- Web.Clients.Abstractions
  |                 ApiClientBase    -- HTTP plumbing (GET/POST/PUT/PATCH/DELETE)
  |                 ClientLog        -- Structured logging (EventIds 4400-4406)
  |                 Contracts/       -- Cross-domain DTO interfaces
  |
  +-- HTTP (REST) --> Per-domain .Endpoints packages --> ConfigurationDb

Every API client:

  1. Inherits from ApiClientBase -- shared HTTP methods with JSON serialization, structured error handling, and logging.
  2. Returns IGenericResult<T> -- railway-oriented results that carry either a value or a structured error message. Never throws for business-logic failures.
  3. Registers via IHttpClientFactory -- each package provides an Add{Client}ApiClient(baseUrl) extension method that returns IHttpClientBuilder for further configuration (auth handlers, retry policies, etc.).

ApiClientBase

Located in FractalDataWorks.Web.Clients.Abstractions, the base class provides six protected HTTP methods:

Method Signature Returns
Get<T> (string path, CancellationToken ct) IGenericResult<T>
Post<TReq, TResp> (string path, TRequest request, CancellationToken ct) IGenericResult<TResponse>
Post<TReq> (string path, TRequest request, CancellationToken ct) IGenericResult (no body)
Post (string path, CancellationToken ct) IGenericResult (no request, no body)
PostWithResponse<T> (string path, CancellationToken ct) IGenericResult<T> (no request, with body)
Put<TReq, TResp> (string path, TRequest request, CancellationToken ct) IGenericResult<TResponse>
Put<TReq> (string path, TRequest request, CancellationToken ct) IGenericResult (no body)
Patch<TReq, TResp> (string path, TRequest request, CancellationToken ct) IGenericResult<TResponse>
Delete (string path, CancellationToken ct) IGenericResult

Each method wraps HttpClient calls with three catch blocks: HttpRequestException, JsonException, and Exception. Every path through the method logs via ClientLog and returns a structured IGenericResult.

ClientLog (EventIds 4400-4406)

ClientLog is a [MessageLogging] class in Web.Clients.Abstractions that provides structured logging for all HTTP operations:

EventId Level Method Message
4400 Trace SendingRequest Sending {method} request to {path}
4401 Debug ResponseReceived {method} request to {path} received response {statusCode}
4402 Information RequestCompleted {method} request to {path} completed successfully
4403 Warning RequestNonSuccess {method} request to {path} returned non-success status {statusCode}
4404 Error HttpRequestFailed {method} request to {path} failed with HTTP error
4405 Error DeserializationFailed {method} request to {path} failed with serialization error
4406 Error UnexpectedError {method} request to {path} failed with unexpected error

Every request is traced before sending (4400), every response is logged with its status code (4401), and every completion or failure produces a structured message that is both logged AND returned inside the IGenericResult.

Web.Clients.Abstractions -- Cross-Domain Contracts

The Contracts/ directory defines interface abstractions for DTOs shared across domain boundaries. Per-domain .Clients packages implement these interfaces on their concrete DTOs, enabling dependency inversion.

Interface Properties Used By Domains
IColumnSchema Name, DataType, IsNullable, IsPrimaryKey, MaxLength, Precision, Scale, Role Schema, Data
IFieldDiscovery Name, DataType, IsNullable, IsKey Schema, Data
IContainerDiscovery Name, ContainerType, Fields (list of IFieldDiscovery) Schema, Data
IDataPreviewRequest DataSetName, ConnectionName, SchemaName, TableName, MaxRows Schema, Data
IDataPreviewResponse Columns (list of IColumnSchema), Rows, TotalRowCount, HasMoreRows Schema, Data
IDataSetField Id, Name, Description, DataType, IsKey, IsRequired, IsIndexed, MaxLength, DefaultValue, IsCalculated, Role, Ordinal Data, Calculations
IEnvironmentInfo Id, Name, Description Operations, Analytics
ICalculationTypeStats CalculationType, ExecutionCount, AverageDurationMs, MinDurationMs, MaxDurationMs, SuccessRate, CacheHitRate, LastExecuted Calculations, Analytics

Per-Package Reference

Core Infrastructure

1. Services.Connections.Clients

Connection management -- CRUD, type browsing, and connectivity testing.

Client ConnectionApiClient
Registration services.AddConnectionApiClient(baseUrl)
Method HTTP Return Type
GetConnections(ct) GET connections IGenericResult<IReadOnlyList<ConnectionDto>>
GetConnectionTypes(ct) GET connections/types IGenericResult<IReadOnlyList<ConnectionTypeDto>>
GetConnection(name, ct) GET connections/{name} IGenericResult<ConnectionDetailResponse>
CreateConnection(request, ct) POST connections IGenericResult<ConnectionDetailResponse>
UpdateConnection(name, request, ct) PUT connections/{name} IGenericResult<ConnectionDetailResponse>
DeleteConnection(name, ct) DELETE connections/{name} IGenericResult
TestConnection(name, ct) POST connections/{name}/test IGenericResult<TestConnectionResponse>

Key DTOs: ConnectionDto, ConnectionTypeDto, ConnectionDetailResponse, ConnectionResponse, CreateConnectionRequest, UpdateConnectionRequest, ConnectionAuthenticationRequest, TestConnectionResponse

2. Services.Data.Clients

DataStore and DataSet management -- two clients in one package.

Client DataStoreApiClient
Registration services.AddDataStoreApiClient(baseUrl)
Method HTTP Return Type
GetDataStores(ct) GET datastores IGenericResult<IReadOnlyList<DataStoreSummaryDto>>
GetDataStore(name, ct) GET datastores/{name} IGenericResult<DataStoreDetailDto>
CreateDataStore(request, ct) POST datastores IGenericResult<DataStoreDetailDto>
UpdateDataStore(name, request, ct) PUT datastores/{name} IGenericResult<DataStoreDetailDto>
DeleteDataStore(name, ct) DELETE datastores/{name} IGenericResult
DiscoverContainers(connectionName, path, ct) GET datastores/discover?... IGenericResult<IReadOnlyList<ContainerDiscoveryResult>>
Client DataSetApiClient
Registration services.AddDataSetApiClient(baseUrl)
Method HTTP Return Type
GetDataSets(ct) GET datasets IGenericResult<IReadOnlyList<DataSetSummaryDto>>
GetDataSet(name, ct) GET datasets/{name} IGenericResult<DataSetDetailDto>
CreateDataSet(request, ct) POST datasets IGenericResult<DataSetDetailDto>
UpdateDataSet(name, request, ct) PUT datasets/{name} IGenericResult<DataSetDetailDto>
DeleteDataSet(name, ct) DELETE datasets/{name} IGenericResult

Key DTOs: DataStoreSummaryDto, DataStoreDetailDto, DataStorePathDto, DataStoreContainerDto, DataStoreFieldDto, CreateDataStoreWithPathsRequest, UpdateDataStoreWithPathsRequest, DataPathRequest, DataSetSummaryDto, DataSetDetailDto, DataSetSourceDto, DataSetJoinDto, DataSetCachingDto, DataSetFieldMappingDto, DataSetFieldDto, CreateDataSetRequest, CreateDataSetSourceRequest, CreateDataSetFieldRequest, UpdateDataSetRequest, ColumnSchemaDto, FieldDiscoveryResult, ContainerDiscoveryResult, DataPreviewRequest, DataPreviewResponse

3. Schema.Clients

Schema introspection, data preview, and physical table DDL management -- two clients.

Client SchemaApiClient
Registration services.AddSchemaApiClient(baseUrl)
Method HTTP Return Type
Introspect(connectionName, ct) GET schema/introspect?connection=... IGenericResult<SchemaIntrospectionResponse>
GetCapableConnections(ct) GET schema/connections IGenericResult<IReadOnlyList<SchemaCapableConnectionDto>>
PreviewData(request, ct) POST schema/preview IGenericResult<DataPreviewResponse>
Client TableApiClient
Registration services.AddTableApiClient(baseUrl)
Method HTTP Return Type
GenerateDdl(request, ct) POST schema/tables/generate-ddl IGenericResult<DdlResponse>
ExecuteDdl(request, ct) POST schema/tables/execute-ddl IGenericResult<ExecuteDdlResponse>

Key DTOs: SchemaIntrospectionResponse, SchemaCapableConnectionDto, DatabaseSchemaDto, DatabaseTableDto, DatabaseColumnDto, TableSchemaDto, ViewSchemaDto, CreateTableRequest, TableColumnRequest, DdlResponse, ExecuteDdlRequest, ExecuteDdlResponse, ColumnSchemaDto, FieldDiscoveryResult, ContainerDiscoveryResult, DataPreviewRequest, DataPreviewResponse

ETL & Scheduling

4. Services.Pipelines.Clients

Pipeline configuration and job execution -- two clients for two target servers.

Client IPipelineClient (impl: PipelineHttpClient)
Registration services.AddPipelineClient(baseUrl)
Target Server ApiSolution
Method HTTP Return Type
GetPipelines(ct) GET pipelines IGenericResult<IReadOnlyList<PipelineDto>>
GetPipeline(name, ct) GET pipelines/{name} IGenericResult<PipelineDetailResponse>
CreatePipeline(request, ct) POST pipelines IGenericResult<CreatePipelineResponse>
UpdatePipeline(name, request, ct) PUT pipelines/{name} IGenericResult<UpdatePipelineResponse>
DeletePipeline(name, ct) DELETE pipelines/{name} IGenericResult
Client IPipelineJobClient (impl: PipelineJobHttpClient)
Registration services.AddPipelineJobClient(baseUrl)
Target Server EtlServer
Method HTTP Return Type
TriggerJob(name, ct) POST etl/trigger IGenericResult<TriggerJobResponse>
GetJobStatus(id, ct) GET etl/jobs/{id}/status IGenericResult<GetJobStatusResponse>

Key DTOs: PipelineDto, PipelineDetailResponse, PipelineInfo, CreatePipelineRequest, CreatePipelineResponse, UpdatePipelineRequest, UpdatePipelineResponse, TriggerJobRequest, TriggerJobResponse, GetJobStatusResponse, JobStatus

5. Services.Scheduling.Clients

Schedule CRUD and enable/disable toggling.

Client ScheduleApiClient
Registration services.AddScheduleApiClient(baseUrl)
Method HTTP Return Type
GetSchedules(ct) GET schedules IGenericResult<IReadOnlyList<ScheduleDto>>
GetSchedule(name, ct) GET schedules/{name} IGenericResult<ScheduleInfo>
CreateSchedule(request, ct) POST schedules IGenericResult
UpdateSchedule(name, request, ct) PUT schedules/{name} IGenericResult<UpdateScheduleResponse>
DeleteSchedule(name, ct) DELETE schedules/{name} IGenericResult
ToggleSchedule(name, isEnabled, ct) PATCH schedules/{name}/toggle IGenericResult<ScheduleInfo>

Key DTOs: ScheduleDto, ScheduleStatus, ScheduleInfo, CreateScheduleRequest, UpdateScheduleRequest, UpdateScheduleResponse, ToggleScheduleRequest

Operations & Lineage

6. Operations.Clients

Three clients in one package: dataflow visualization, data lineage traversal, and configuration metadata discovery.

Client DataflowApiClient
Registration services.AddDataflowApiClient(baseUrl)
Method HTTP Return Type
GetGraph(ct) GET dataflow/graph IGenericResult<DataflowGraphResponse>
GetLineage(datasetName, ct) GET dataflow/lineage/{name} IGenericResult<DataSetLineageResponse>
AnalyzeImpact(targetType, targetName, ct) GET dataflow/impact/{type}/{name} IGenericResult<ImpactAnalysisResponse>
Client LineageApiClient
Registration services.AddLineageApiClient(baseUrl)
Method HTTP Return Type
GetLineage(entityType, entityName, ct) GET lineage/{type}/{name} IGenericResult<LineageGraphDto>
GetColumnLineage(entityType, entityName, fieldName, ct) GET lineage/{type}/{name}/fields/{field} IGenericResult<LineageGraphDto>
Client ConfigurationApiClient
Registration services.AddConfigurationApiClient(baseUrl)
Method HTTP Return Type
GetTypesByCategory(category, ct) GET configuration/types?category=... IGenericResult<IReadOnlyList<ConfigurationTypeSummary>>
GetTypeDetail(category, serviceType, ct) GET configuration/types/detail?... IGenericResult<ConfigurationTypeDetail>
GetRootTypes(ct) GET configuration/types/roots IGenericResult<IReadOnlyList<ConfigurationTypeSummary>>
GetChildTypes(parentTableName, ct) GET configuration/types/children?parent=... IGenericResult<IReadOnlyList<ConfigurationTypeSummary>>
GetInstances(category?, ct) GET configuration/instances[?category=...] IGenericResult<IReadOnlyList<ConfigurationInstanceSummary>>
GetInstance(category, name, ct) GET configuration/instances/{category}/{name} IGenericResult<ConfigurationInstanceDetail>
CreateInstance(category, request, ct) POST configuration/instances/{category} IGenericResult<ConfigurationInstanceDetail>
UpdateInstance(category, name, request, ct) PUT configuration/instances/{category}/{name} IGenericResult<ConfigurationInstanceDetail>
DeleteInstance(category, name, ct) DELETE configuration/instances/{category}/{name} IGenericResult

Key DTOs: DataflowGraphResponse, DataflowNodeResponse, DataflowEdgeResponse, DataflowStatsResponse, DataflowNodeType, DataSetLineageResponse, ImpactAnalysisResponse, ImpactedDataSetDto, LineageGraphDto, LineageNodeDto, LineageEdgeDto, LineageSourceDto, LineageConsumerDto, FieldLineageDto, FieldSourceMappingDto, ConfigurationTypeSummary, ConfigurationTypeDetail, ConfigurationPropertyInfo, ConfigurationPropertyType, ValidationRuleInfo, ConfigurationInstanceSummary, ConfigurationInstanceDetail, ConfigurationData, CreateConfigurationInstanceRequest, UpdateConfigurationInstanceRequest, ActivityEntryDto, ActivityType, DashboardSummaryDto, ExecutionState, EnvironmentDto

Identity & Access

7. Services.Users.Clients

User CRUD, current user, and role assignment.

Client UserApiClient
Registration services.AddUserApiClient(baseUrl)
Method HTTP Return Type
GetUsers(ct) GET users IGenericResult<IReadOnlyList<UserSummaryDto>>
GetUser(id, ct) GET users/{id} IGenericResult<UserDetailDto>
GetCurrentUser(ct) GET users/me IGenericResult<UserDetailDto>
CreateUser(request, ct) POST users IGenericResult<CreateUserResponse>
UpdateUser(id, request, ct) PUT users/{id} IGenericResult<UserDetailDto>
DeleteUser(id, ct) DELETE users/{id} IGenericResult
GetUserRoles(id, ct) GET users/{id}/roles IGenericResult<UserRolesResponse>
AssignUserRole(id, request, ct) POST users/{id}/roles IGenericResult
RevokeUserRole(id, roleName, ct) DELETE users/{id}/roles/{roleName} IGenericResult

Key DTOs: UserSummaryDto, UserDetailDto, UserRolesResponse, CreateUserRequest, CreateUserResponse, UpdateUserRequest, AssignRoleRequest

8. Services.Authorization.Clients

Role definitions and permission matrix management.

Client RoleApiClient
Registration services.AddRoleApiClient(baseUrl)
Method HTTP Return Type
GetRoles(ct) GET roles IGenericResult<IReadOnlyList<RoleSummaryDto>>
GetRole(name, ct) GET roles/{name} IGenericResult<RoleDetailDto>
CreateRole(request, ct) POST roles IGenericResult<RoleDetailDto>
UpdateRole(name, request, ct) PUT roles/{name} IGenericResult<RoleDetailDto>
DeleteRole(name, ct) DELETE roles/{name} IGenericResult
GetPermissions(ct) GET permissions IGenericResult<IReadOnlyList<PermissionDto>>
GetPermissionsGrouped(ct) GET permissions/grouped IGenericResult<IReadOnlyList<PermissionGroupDto>>
GetRolePermissions(name, ct) GET roles/{name}/permissions IGenericResult<IReadOnlyList<PermissionDto>>
SetRolePermissions(name, request, ct) PUT roles/{name}/permissions IGenericResult

Key DTOs: RoleSummaryDto, RoleDetailDto, PermissionDto, PermissionGroupDto, CreateRoleRequest, UpdateRoleRequest, SetRolePermissionsRequest

9. Services.Authentication.Clients

JWT authentication lifecycle -- login, token refresh, logout, and user info.

Client AuthenticationApiClient
Registration services.AddAuthenticationApiClient(baseUrl)
Method HTTP Return Type
Login(request, ct) POST auth/token IGenericResult<TokenResponse>
RefreshToken(request, ct) POST auth/refresh IGenericResult<RefreshTokenResponse>
Logout(ct) POST auth/logout IGenericResult
GetMe(ct) GET auth/me IGenericResult<GetMeResponse>

Key DTOs: TokenRequest, TokenResponse, RefreshTokenRequest, RefreshTokenResponse, GetMeResponse

10. Services.Multitenancy.Clients (formerly #9)

Tenant management and tenant switching.

Client TenantApiClient
Registration services.AddTenantApiClient(baseUrl)
Method HTTP Return Type
GetTenants(includeInactive, ct) GET tenants?includeInactive=... IGenericResult<IReadOnlyList<TenantSummaryDto>>
GetTenant(tenantId, ct) GET tenants/{tenantId} IGenericResult<TenantDetailDto>
GetCurrentTenant(ct) GET tenants/current IGenericResult<TenantDetailDto>
CreateTenant(request, ct) POST tenants IGenericResult<TenantDetailDto>
UpdateTenant(tenantId, request, ct) PUT tenants/{tenantId} IGenericResult<TenantDetailDto>
SwitchTenant(request, ct) POST tenants/switch IGenericResult<SwitchTenantResponse>

Key DTOs: TenantSummaryDto, TenantDetailDto, CreateTenantRequest, UpdateTenantRequest, SwitchTenantRequest, SwitchTenantResponse

Data Quality & Catalog

11. Services.Quality.Clients

Quality rule management and check execution.

Client QualityApiClient
Registration services.AddQualityApiClient(baseUrl)
Method HTTP Return Type
GetDashboard(ct) GET quality/dashboard IGenericResult<QualityDashboardDto>
GetRules(ct) GET quality/rules IGenericResult<IReadOnlyList<QualityRuleSummaryDto>>
GetRule(id, ct) GET quality/rules/{id} IGenericResult<QualityRuleDetailDto>
CreateRule(request, ct) POST quality/rules IGenericResult<QualityRuleDetailDto>
UpdateRule(id, request, ct) PUT quality/rules/{id} IGenericResult<QualityRuleDetailDto>
DeleteRule(id, ct) DELETE quality/rules/{id} IGenericResult
ExecuteCheck(id, ct) POST quality/rules/{id}/execute IGenericResult<QualityCheckResultDto>

Key DTOs: QualityDashboardDto, QualityRuleSummaryDto, QualityRuleDetailDto, QualityCheckResultDto, CreateQualityRuleRequest, UpdateQualityRuleRequest

12. Services.Catalog.Clients

Data catalog search and glossary.

Client CatalogApiClient
Registration services.AddCatalogApiClient(baseUrl)
Method HTTP Return Type
Search(query, entityType?, ct) GET catalog/search?query=... IGenericResult<IReadOnlyList<CatalogEntityDto>>
GetGlossary(ct) GET catalog/glossary IGenericResult<IReadOnlyList<GlossaryTermDto>>
GetDataSetEntry(name, ct) GET catalog/datasets/{name} IGenericResult<DataSetCatalogDto>

Key DTOs: CatalogEntityDto, GlossaryTermDto, DataSetCatalogDto, CatalogSearchRequest

Analytics & Calculations

13. Web.Analytics.Clients

Analytics, data profiling, and promotion management -- three clients in one package.

Client AnalyticsApiClient
Registration services.AddAnalyticsApiClient(baseUrl)
Method HTTP Return Type
GetAnalytics(request, ct) POST analytics IGenericResult<AnalyticsResponse>
GetTopCalculations(request, ct) POST analytics/top-calculations IGenericResult<TopCalculationsResponse>
Client ProfileApiClient
Registration services.AddProfileApiClient(baseUrl)
Method HTTP Return Type
GetProfile(dataSetName, ct) GET datasets/{name}/profile IGenericResult<DataProfileDto>
RunProfile(dataSetName, ct) POST datasets/{name}/profile IGenericResult<DataProfileDto>
Client PromotionApiClient
Registration services.AddPromotionApiClient(baseUrl)
Method HTTP Return Type
GetEnvironments(ct) GET admin/environments IGenericResult<IReadOnlyList<EnvironmentDto>>
GetPendingPromotions(ct) GET promotions?status=Pending IGenericResult<IReadOnlyList<PromotionDto>>
CreatePromotion(request, ct) POST promotions IGenericResult<PromotionDto>
ApprovePromotion(id, ct) POST promotions/{id}/approve IGenericResult
RejectPromotion(id, ct) POST promotions/{id}/reject IGenericResult

Key DTOs: AnalyticsRequest, AnalyticsResponse, AnalyticsSummary, TimeSeriesDataPoint, TopCalculationsRequest, TopCalculationsResponse, CalculationTypeStats, DataProfileDto, PromotionDto, CreatePromotionRequest, EnvironmentDto

14. Web.Calculations.Clients

Calculation definitions, execution, formula validation, and preview.

Client CalculationApiClient
Registration services.AddCalculationApiClient(baseUrl)
Method HTTP Return Type
GetCalculationTypes(ct) GET calculations/types IGenericResult<CalculationTypesResponse>
GetCalculations(ct) GET calculations IGenericResult<IReadOnlyList<CalculationSummaryDto>>
GetCalculation(id, ct) GET calculations/{id} IGenericResult<CalculationDetailDto>
CreateCalculation(request, ct) POST calculations IGenericResult<CalculationDetailDto>
UpdateCalculation(id, request, ct) PUT calculations/{id} IGenericResult<CalculationDetailDto>
DeleteCalculation(id, ct) DELETE calculations/{id} IGenericResult
ExecuteCalculation(request, ct) POST calculations/execute IGenericResult<ExecuteCalculationResponse>
ValidateFormula(request, ct) POST calculations/validate IGenericResult<PreviewFormulaResponse>
PreviewCalculation(request, ct) POST calculations/preview IGenericResult<PreviewCalculationResponse>
GetDataSetFields(dataSetName, ct) GET datasets/{name}/fields IGenericResult<IReadOnlyList<DataSetFieldDto>>

Key DTOs: CalculationTypesResponse, CalculationTypeDto, CalculationSummaryDto, CalculationDetailDto, PeriodComparisonTypeDto, PeriodComparisonTypesResponse, CreateCalculationDefinitionRequest, UpdateCalculationDefinitionRequest, ExecuteCalculationRequest, ExecuteCalculationResponse, ValidateFormulaRequest, PreviewFormulaRequest, PreviewFormulaResponse, PreviewCalculationRequest, PreviewCalculationResponse, DataSetFieldDto, CalculationTypeStats

UI & Search

15. Web.Search.Clients

Unified search across all entity types.

Client SearchApiClient
Registration services.AddSearchApiClient(baseUrl)
Method HTTP Return Type
Search(request, ct) GET search?query=...&limit=... IGenericResult<SearchResponse>

Key DTOs: SearchRequest, SearchResponse, SearchResultDto, SearchSuggestionDto

16. UI.Themes.Clients

Theme CRUD and default theme management.

Client ThemeApiClient
Registration services.AddThemeApiClient(baseUrl)
Method HTTP Return Type
GetThemes(ct) GET themes IGenericResult<IReadOnlyList<ThemeSummaryDto>>
GetTheme(name, ct) GET themes/{name} IGenericResult<ThemeConfiguration>
GetDefaultTheme(ct) GET themes/default IGenericResult<ThemeConfiguration>
CreateTheme(request, ct) POST themes IGenericResult<ThemeConfiguration>
UpdateTheme(name, request, ct) PUT themes/{name} IGenericResult<ThemeConfiguration>
DeleteTheme(name, ct) DELETE themes/{name} IGenericResult
SetDefaultTheme(name, ct) POST themes/{name}/default IGenericResult

Key DTOs: ThemeSummaryDto, ThemeConfiguration, CreateThemeRequest, UpdateThemeRequest

Registration Pattern

Every .Clients package provides extension methods on IServiceCollection that register the API client via IHttpClientFactory. The pattern is identical across all 16 packages:

// Each extension method returns IHttpClientBuilder for chaining
services.AddConnectionApiClient("https://api.example.com/");
services.AddDataStoreApiClient("https://api.example.com/");
services.AddDataSetApiClient("https://api.example.com/");

The implementation delegates to services.AddHttpClient<TClient>:

public static IHttpClientBuilder AddConnectionApiClient(this IServiceCollection services, string baseUrl)
{
    return services.AddHttpClient<ConnectionApiClient>(client =>
    {
        client.BaseAddress = new System.Uri(baseUrl);
    });
}

Complete Registration Table

Package Extension Method(s)
Services.Connections.Clients AddConnectionApiClient
Services.Data.Clients AddDataStoreApiClient, AddDataSetApiClient
Schema.Clients AddSchemaApiClient, AddTableApiClient
Services.Pipelines.Clients AddPipelineClient, AddPipelineJobClient
Services.Scheduling.Clients AddScheduleApiClient
Operations.Clients AddLineageApiClient, AddDataflowApiClient, AddConfigurationApiClient
Services.Users.Clients AddUserApiClient
Services.Authorization.Clients AddRoleApiClient
Services.Authentication.Clients AddAuthenticationApiClient
Services.Multitenancy.Clients AddTenantApiClient
Services.Quality.Clients AddQualityApiClient
Services.Catalog.Clients AddCatalogApiClient
Web.Analytics.Clients AddAnalyticsApiClient, AddProfileApiClient, AddPromotionApiClient
Web.Calculations.Clients AddCalculationApiClient
Web.Search.Clients AddSearchApiClient
UI.Themes.Clients AddThemeApiClient

Adding Authentication

The IHttpClientBuilder return type allows chaining HTTP message handlers for JWT attachment:

services.AddConnectionApiClient("https://api.example.com/")
    .AddHttpMessageHandler<AuthenticatedHttpHandler>();

Error Handling

All API client methods return IGenericResult<T> (for data responses) or IGenericResult (for void operations). The consumer checks the result:

var result = await connectionApi.GetConnections(ct);

if (result.IsSuccess)
{
    var connections = result.Value;
    // Use connections
}
else
{
    // result.Messages contains structured error info
    // The error was already logged by ClientLog at the appropriate level
}

ApiClientBase catches three exception types and maps each to a ClientLog method:

Exception ClientLog Method EventId Level
HttpRequestException HttpRequestFailed 4404 Error
JsonException DeserializationFailed 4405 Error
Exception UnexpectedError 4406 Error

Non-success HTTP status codes (4xx, 5xx) do not throw -- they return GenericResult.Failure with RequestNonSuccess (EventId 4403, Warning level).

Package Summary

# Package Client(s) Methods Domain
1 Services.Connections.Clients ConnectionApiClient 7 Infrastructure
2 Services.Data.Clients DataStoreApiClient, DataSetApiClient 6 + 5 Infrastructure
3 Schema.Clients SchemaApiClient, TableApiClient 3 + 2 Infrastructure
4 Services.Pipelines.Clients IPipelineClient, IPipelineJobClient 5 + 2 ETL
5 Services.Scheduling.Clients ScheduleApiClient 6 ETL
6 Operations.Clients DataflowApiClient, LineageApiClient, ConfigurationApiClient 3 + 2 + 9 Operations
7 Services.Users.Clients UserApiClient 9 Identity
8 Services.Authorization.Clients RoleApiClient 9 Identity
9 Services.Authentication.Clients AuthenticationApiClient 4 Identity
10 Services.Multitenancy.Clients TenantApiClient 6 Identity
11 Services.Quality.Clients QualityApiClient 7 Data Quality
12 Services.Catalog.Clients CatalogApiClient 3 Data Quality
13 Web.Analytics.Clients AnalyticsApiClient, ProfileApiClient, PromotionApiClient 2 + 2 + 5 Analytics
14 Web.Calculations.Clients CalculationApiClient 10 Analytics
15 Web.Search.Clients SearchApiClient 1 UI
16 UI.Themes.Clients ThemeApiClient 7 UI

Totals: 16 packages, 23 client classes, 114 methods.

See Also

Clone this wiki locally