Skip to content

Latest commit

 

History

History
50 lines (36 loc) · 3.27 KB

engine-api-client.md

File metadata and controls

50 lines (36 loc) · 3.27 KB

Engine API client - one typed client for every engine call

Feature code reaches the engine through one typed client generated from the engine's OpenAPI spec. The endpoint map is compile-time checked against the generated types, so a route that disappears from the spec fails the build, not the user.

The spec becomes typed calls

The endpoint map sits between the generated types and the client, so a route the spec drops fails compilation there.

flowchart LR
    accTitle: L4 Detail -- Engine API client
    accDescr: openapi-typescript turns the copied engine spec into the paths types. The endpoint map is checked against those types, the API client sends requests from the map, and the TanStack Query hooks in each feature directory call the client.

    spec[("Engine spec copy")]
    types["Paths types"]
    map["Endpoint map"]
    client["API client"]
    hooks["Query hooks"]

    spec --> types
    types --> map
    map -->|routes| client
    client -->|typed calls| hooks

    classDef default fill:#F8FAFC,stroke:#64748B,stroke-width:1px,color:#0F172A
    classDef core fill:#DCEBF7,stroke:#0072B2,stroke-width:2px,color:#0B2A3F
    classDef store fill:#DDF3EC,stroke:#00785A,stroke-width:1px,color:#0B3327
    class spec store
    class client core
Loading

Figure 1. L4 Detail -- Engine API client. The blue box is the client. Up: L3 Components -- dfe-ui.

  • Engine spec: packages/dfe-engine-types/specs/openapi.json and openapi.e2e.json, committed byte copies of dfe-engine's openapi/openapi.json and openapi/openapi.e2e.json.
  • Generated code: yarn workspace @repo/dfe-engine-types generate runs openapi-typescript over both specs (types/index.d.ts, types/e2e.d.ts) and writes the scope and limit constants (scopes/index.ts, limits/index.ts).
  • Endpoint map: apps/dfe-core-ui/src/core/config/api/endpoints/index.ts, typed satisfies Record<string, Record<string, keyof paths>>, so every entry must exist in the spec.
  • Client: apps/dfe-core-ui/src/core/config/api/client.ts, a fetch wrapper adding auth, JSON handling and ApiError.
  • Hooks: feature directories wrap endpoints in TanStack Query.

The engine opens the sync PR

A push to dfe-engine's main that changes either spec runs its Sync dfe-engine-types workflow (sync-dfe-engine-types.yml in dfe-engine). It copies both specs here, runs generate, and opens a sync-dfe-engine-types-<sha> pull request, closing any older one. The compile errors that PR raises in the endpoint map are the drift check working.

To do the same by hand against a local engine checkout:

  1. Copy dfe-engine's openapi/openapi.json and openapi/openapi.e2e.json over the two files in packages/dfe-engine-types/specs/.
  2. yarn workspace @repo/dfe-engine-types generate
  3. Fix any compile errors in the endpoint map.

The spec's info.version moves with every engine release, because each release commit rewrites openapi/openapi.json. A version comparison detects drift between releases but not edits within one, so compare the files. The type-safety sync is documented engine-side in type-safety-sync.md.