Frontend API Integrations

Relevant source files

The following files were used as context for generating this wiki page:

• packages/web/src/api/client.ts
• packages/web/src/api/schema.ts
• packages/web/src/features/customers/customers.functions.ts
• packages/web/src/features/users/users.functions.ts
• packages/web/src/features/users/users.server.ts
• packages/web/CLAUDE.md

Introduction

The frontend API integration layer provides a robust bridge between the TanStack Start web application and the .NET backend. It utilizes a combination of auto-generated TypeScript types, openapi-fetch for type-safe requests, and TanStack Start Server Functions to handle data fetching and mutations with built-in validation.

The architecture is designed for maximum type safety by deriving frontend schemas directly from the backend's OpenAPI specification. This ensures that data structures used in the UI, such as those for Customers and Users, remain synchronized with the server's data models.

Sources: packages/web/CLAUDE.md:27-31, packages/web/src/api/client.ts:38

Core API Architecture

The integration is built on a multi-layered approach that separates low-level HTTP concerns from high-level business logic.

API Client and Middleware

The foundation is an openapi-fetch client configured with middleware for authentication and error handling.

• Authentication Middleware: Automatically attaches a Bearer token to requests by retrieving it from the server context.
• Error Middleware: Intercepts non-OK responses and throws a custom ApiRequestError containing the status code and response body.

Type Generation

Type safety is enforced via packages/web/src/api/schema.ts, which is auto-generated from the backend's OpenAPI v1 JSON. This file contains interfaces for all API paths and schemas, including enums like UserRole and complex objects like Contract.

Sources: packages/web/src/api/schema.ts:7-13, packages/web/CLAUDE.md:34-35

Server Functions and Validation

The application uses TanStack Start createServerFn to encapsulate API calls. These functions are responsible for input validation, data transformation, and interfacing with "server-only" data access logic.

Data Flow Pattern

1. Input Validation: Every server function defines a Zod schema via .inputValidator to ensure type-safe inputs.
2. Server Logic: The handler calls server-side helper functions (e.g., getUsers, createCustomer) which use the openapi-fetch client.
3. Error Transformation: Catching specific ApiRequestError instances to return null (for 404s) or throw user-friendly error codes (e.g., EMAIL_ALREADY_IN_USE).

Key Resource Integrations

User Management

User operations support search, pagination, and logical sorting (e.g., sorting by User Role).

Operation	Method	Endpoint	Description
getUsers	GET	/api/users	Supports search, sort, and pagination.
getUserById	GET	/api/users/{id}	Retrieves detailed user info including leave allowances.
createUser	POST	/api/users	Validates user data and handles 409 Conflict for duplicate emails.
archiveUser	PATCH	/api/users/{id}/archive	Performs logical deletion.

Sources: packages/web/src/api/schema.ts:192-286, packages/web/src/features/users/users.server.ts:21-48

Customer Management

Customer integrations follow a similar CRUD pattern with specific sorting slugs for Number, Name, Contact Name, and City.

export const fetchCustomers = createServerFn({ method: 'GET' })
  .inputValidator(searchSchema)
  .handler(async ({ data }) => {
    const { sort, ...rest } = data;
    if (!sort) return await getCustomers(rest);
    const isDesc = sort.endsWith('-');
    const slug = (isDesc ? sort.slice(0, -1) : sort) as SortSlug;
    return await getCustomers({
      ...rest,
      sort: sortSlugs[slug],
      sortDirection: isDesc ? 'Desc' : 'Asc',
    });
  });

Sources: packages/web/src/features/customers/customers.functions.ts:7-21, packages/web/src/api/schema.ts:40-149

Error Handling

The system uses a centralized ApiRequestError class. Server functions often wrap calls in try/catch blocks to translate HTTP status codes into domain-specific exceptions that the UI can interpret (e.g., via sonner toasts).

HTTP Status	Translation/Action	Source File
404	Return null	users.functions.ts:30
409	Throw EMAIL_ALREADY_IN_USE	users.functions.ts:41
409	Throw DUPLICATE_LEAVE_ALLOWANCE	users.functions.ts:58
!ok	Throw ApiRequestError(status, body)	api/client.ts:34

Sources: packages/web/src/api/client.ts:9-15, packages/web/src/features/users/users.functions.ts:26-64

Summary

The frontend API integration layer prioritizes type safety and developer experience. By leveraging openapi-fetch and TanStack Start Server Functions, the project ensures that API interactions are validated at the edge, authenticated consistently, and typed from end-to-end. This structure simplifies maintenance by centralizing error handling and using shared Zod schemas between the UI forms and server-side processing.