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 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
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.jsonandopenapi.e2e.json, committed byte copies of dfe-engine'sopenapi/openapi.jsonandopenapi/openapi.e2e.json. - Generated code:
yarn workspace @repo/dfe-engine-types generateruns 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, typedsatisfies 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 andApiError. - Hooks: feature directories wrap endpoints in TanStack Query.
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:
- Copy dfe-engine's
openapi/openapi.jsonandopenapi/openapi.e2e.jsonover the two files inpackages/dfe-engine-types/specs/. yarn workspace @repo/dfe-engine-types generate- 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.