Skip to content

API_TYPES.md

Latest commit

 

History

History
82 lines (58 loc) · 3.45 KB

API_TYPES.md

File metadata and controls

82 lines (58 loc) · 3.45 KB
Raw

API Types

All TypeScript types for the Credence backend API are derived from the OpenAPI 3.1 specification at /openapi.yaml. This keeps the frontend's compile-time contracts in sync with the backend contract, making drift visible as a type error rather than a runtime surprise.

How it works

openapi.yaml          →  npm run generate:api  →  src/api/generated.ts
    ↓                                                       ↓
single source of truth               named aliases re-exported from src/api/types.ts
  1. openapi.yaml — The canonical API contract. Defines schemas, operations, parameters, and responses.
  2. src/api/generated.ts — Auto-generated by openapi-typescript. Never edit this file by hand; run npm run generate:api instead.
  3. src/api/types.ts — Public type surface consumed by the rest of the codebase. Exports backwards-compatible named aliases (TrustScore, Bond, etc.) that map onto the generated schema types.

Usage

Import named types (recommended for most cases)

import type { TrustScore, Bond, Transaction, BondStatus, TrustTier } from '@/api/types'

All names that existed before the codegen migration are still exported, so existing code requires no changes.

Derive a response type directly from an operation

import { apiFetch } from '@/api/client'
import type { operations, ApiResponse } from '@/api/types'

// The return type is inferred from the spec — no manual annotation.
const score = await apiFetch<ApiResponse<operations['getTrustScore']>>(
  `/trust-score/${address}`
)

ApiResponse<Op> extracts the application/json body of the HTTP 200 response for a given operation, so the type always mirrors the spec.

Access the raw generated schema

For advanced scenarios (e.g. response guards, schema-level utilities):

import type { components, operations, paths } from '@/api/types'

type TrustTierFromSpec = components['schemas']['TrustTier']
// "bronze" | "silver" | "gold" | "platinum"

Regenerating types after a spec change

Whenever openapi.yaml is updated, regenerate the type file and re-run the type checker:

npm run generate:api   # rewrites src/api/generated.ts
npm run build          # tsc will surface any drift between spec and usage
npm test               # src/api/types.test.ts guards all public aliases

src/api/generated.ts is committed to the repository so that CI and reviewers see the full diff of any spec change alongside the code that consumes it.

What to do when the backend changes a schema

Change Impact Action
Add optional field Non-breaking Run generate:api, types remain backwards-compatible
Add required field Breaking Run generate:api, fix any callers that produce the type
Remove / rename a field Breaking Run generate:api, tsc will surface every affected callsite
Change an enum value Breaking Run generate:api, tsc will surface literal-type mismatches
Add a new endpoint Non-breaking Add path + schema to spec, run generate:api, write a hook

File index

File Purpose
openapi.yaml OpenAPI 3.1 spec — the single source of truth
src/api/generated.ts Auto-generated types (do not edit by hand)
src/api/types.ts Public aliases + ApiResponse<Op> helper
src/api/client.ts apiFetch<T>() generic HTTP wrapper
src/api/types.test.ts Structural type + runtime shape tests