Api Design

---
name: api-design
description: Design, review, or change HTTP API contracts for AI DIAL Chat. Use when adding or modifying REST endpoints, request/response DTOs, status codes, pagination, filtering, API versioning, auth requirements, cache behavior, OpenAPI/Swagger docs, or frontend server-api clients.
---

# API Design

Use this skill before implementing or reviewing any HTTP API contract. It defines the
contract-first procedure for this repo. For backend implementation mechanics (DTO/Swagger/SDK
patterns, tests, Nx verification) follow `apps/chat-api/AGENTS.md` — do not restate them here. For library isolation follow the
"Library isolation" section in the root `AGENTS.md`: host/API/transport details stay in apps;
hand-authored `libs/*` receive resolved data, values, or callbacks. Exception: `libs/chat-api-client`
is the generated OpenAPI client.

## Start Here

1. Read `openspec/config.yaml` for API architecture, project boundaries, and proposal/spec/task rules.
2. Inspect the closest existing endpoint and its matching frontend client before designing a new contract:
   - Backend controllers: `apps/chat-api/src/**/**.controller.ts`
   - Backend DTOs: `apps/chat-api/src/**/dto/*.dto.ts`
   - Frontend API helpers: `apps/chat/src/server-api/`
   - Shared interfaces: `libs/chat-shared/`

## Contract Checklist

For every new or changed endpoint, define these before coding:

- Method and full path. Business endpoints are URI-versioned (`/api/v1/<resource>`); infrastructure endpoints stay unversioned (`/api/<resource>`).
- Request shape: path params, query params, body DTO, headers, cookies.
- Success response shape and status code.
- Error status codes and what each means: at least validation/auth/authorization/not found, plus `502` (upstream non-OK), `503` (upstream timeout/unavailable). Never `500` exposing internals.
- Authentication and authorization requirements, including whether the endpoint is explicitly public.
- Cache behavior when applicable: TTL, invalidation, and key naming (`<domain>:<resource>[:<param>]`).
- Pagination for list endpoints: prefer cursor for large/append-heavy datasets; offset is acceptable for small admin-style or search flows.
- Frontend impact: thin domain wrapper in `apps/chat/src/server-api/` that delegates to generated `@epam/chat-api-client`, shared type in `libs/chat-shared/` if needed, and i18n strings for any errors surfaced in UI.
- Library impact: if a hand-authored lib needs the data/behavior, name the prop/callback/resolved value it receives (see lib-isolation note above).
- Generated client impact: expected SDK class, method name (derived from the controller handler name via `operationIdFactory`), request type, response type, and whether callers need `Raw` access for headers/status.

## Versioning And Compatibility

- Non-breaking changes need no new version: adding optional query params, adding response fields, or adding new endpoints.
- Breaking changes require a new versioned controller or endpoint path. Keep the previous version until callers are migrated.
- Proposals/specs must call out frontend migration impact and whether shared types change.

## OpenSpec Integration

When writing or reviewing an OpenSpec change that touches API behavior:

- Specs must include method, full versioned path, request body, response body, and error codes.
- Tasks must name concrete files, not vague "update API" wording.
- Include dedicated tasks for: Swagger DTO/annotation updates, `npm run openapi`, `npm run openapi:check`, `chat-api-client` build/lint, backend controller/service tests, generated API singleton updates in `apps/chat/src/server-api/api-client.ts`, and frontend wrappers using generated `@epam/chat-api-client`.
- Generated-client frontend usage is required for new or changed business REST endpoints. Direct `base.ts` get/post/put/del usage is allowed only for documented generator gaps, streaming calls, or infrastructure endpoints.
- If endpoint behavior is surfaced through a lib, tasks must keep the generated-client/server-api call in `apps/chat` and pass only resolved data, values, or callbacks into the lib.
- Changes under `libs/chat-api-client` must come from OpenAPI generation (`npm run openapi`, `npm run openapi:sdk`, or the documented check), not manual edits.
- Include cache requirements when relevant.

## Avoid

- Returning `200` for error cases.
- Designing backend-only contracts without checking the frontend `server-api` layer.
- Adding handwritten frontend REST helpers over `base.ts` for business endpoints the generated client can represent.
- Hand-editing generated files under `libs/chat-api-client/src/generated`.
- Adding unversioned business endpoints.
- Introducing a generic `{ data }` envelope unless the domain already uses it or the change explicitly standardizes responses.
- Mixing API redesign with unrelated implementation refactors.