How-to › Describe your API

How to handle endpoints that do not map to an entity#

Give each operation that is not a read or write of one resource a decision of its own, and check after each regeneration that the SDK reaches every operation once.

Audience
API producer
Level
intermediate
Topic
Extract a semantic model from a spec
Languages
TypeScript and Go
Verified

Read first: Classify OpenAPI operations into CRUD kinds by path shape

Your generated SDK has Job().create() and no cancel(). The cancel endpoint is in there, reached by passing $action: 'cancel' to create, so nobody finds it. A caller who drops the $action posts to /jobs instead. The API answers 400 about a missing template, and the job they meant to stop keeps running.

What you get

You will end up with a recorded decision per operation, a typed wrapper for the actions, and a check that fails when a regeneration drops or moves one. This is for you if you generate an SDK from a document that is not all CRUD.

Short answer

Give every operation in the OpenAPI document one of three decisions. It is an entity operation, a function in a hand-written wrapper module over the sdkgen client’s direct(), or left out with a reason. Record the decisions in a file and switch the other paths off in the sdkgen guide. After every regeneration, run a check that lists each operation against the generated client and fails on one that is missing, moved, or reached twice.

You will need

Node 22.18 or later, which runs the .ts files here directly, an OpenAPI 3 document, and an sdkgen project generated from it, as generate your first SDK with sdkgen sets up. The document here, api.json, describes a Render API with ten operations. Four read and write a job. The other six are a cancel, a replay, a batch submission, an upload callback, a health check, and a token exchange. A stand-in for the API runs on 127.0.0.1. The code is TypeScript and JavaScript only: the Go target was not generated or run for this page. Verified 2026-11-22 against Node 22.23.5.

Approaches compared

ApproachWhen it fitsWhat it costs youWhen to pick something else
Hand-written wrapper moduleA few actions deserve real names and types beside a client you regenerateEvery function and type is kept by hand, and nothing updates it when the document changesThe actions change every release, faster than anyone edits the module
KiotaYou want every path reachable as a typed chain, with exclusions recordedNames follow the path, so cancel is jobs.byJobId(id).cancel.post(), plus runtime packagesCallers want domain-named methods rather than path chains
openapi-typescript and openapi-fetchA TypeScript client where every path stays typed and nothing is classifiedCallers spell each path and method themselves, and get no entity objects or retriesYou ship more than TypeScript, or want entity-shaped calls
sdkgen direct() and prepare()The SDK is generated by sdkgen and an operation fits no entityNo type checks the path, parameters, or body, and features that hook entity operations do not runThe action needs a name and types, which the wrapper gives it
Speakeasy custom methodsSpeakeasy generates the SDK and you can add extensions to the documentAn account, and one extension written into the document per operation you rename or hideYou cannot edit the document, or want generation with no vendor account

Voxgig maintains sdkgen, the worked path on this page and one of five options in the table.

Kiota and openapi-fetch never classify, so nothing they generate can land on the wrong entity, and their price is that callers address every operation by its path. sdkgen’s entity model reads better for the four job operations, and its price is the decision this page records for the other six. Speakeasy names each operation through an extension, which costs edits to the document and a vendor account.

Read where apidef put each operation

apidef is the model step inside sdkgen. With the scaffold’s guide it placed every operation of api.json somewhere, and placement.mjs prints where, on the release a scaffold installs and on the newest:

node placement.mjs
operation                          sdkgen 4.44.3, apidef 8.32.4    sdkgen 4.45.0, apidef 8.33.1
GET /jobs                          job.list                        job.list
POST /jobs                         job.create                      job.create
GET /jobs/{jobId}                  job.load                        job.load
DELETE /jobs/{jobId}               job.remove                      job.remove
POST /jobs/{jobId}/cancel          job.create $action=cancel       job.create $action=cancel
POST /jobs/{jobId}/replay          job.create $action=replay       job.create $action=replay
POST /jobs/batch                   batch.create                    job.create $action=batch   <- moved
POST /uploads/{uploadId}/complete  upload.create $action=complete  upload.create $action=complete
GET /health                        health.load                     health.load
POST /oauth/token                  no entity                       no entity
sdkgen 4.44.3, apidef 8.32.4: 4 entities (batch, health, job, upload)
sdkgen 4.45.0, apidef 8.33.1: 3 entities (health, job, upload)

On this document the heuristic placed nine of the ten operations on an entity. A trailing literal after a job id became an action on create. The health check became an entity of its own. The upload callback became an upload entity whose create has only an action, which both releases report as a PARTIAL BUILD warning. The token exchange is the one operation with no entity: the base guide switches it off under the comment Deactivated by the heuristic (auth-exchange).1

The batch is the one that moved. A regeneration on 4.45.0 removes Batch() from the client and puts the same call on Job().create({ $action: 'batch' }).

See the method name nobody guesses

The unguided client exposes seven entity methods, and pitfall.mjs runs three calls a reader might try:

node pitfall.mjs
entity methods: Batch().create, Health().load, Job().create, Job().list, Job().load, Job().remove, Upload().create
a method named cancel, replay, complete or batch: none
Job().create({ id: 'j1', $action: 'cancel' })
  -> {"id":"j1","template":"invoice","status":"cancelled"}
  sent: POST /v1/jobs/j1/cancel
Job().create({ id: 'j2' }), the $action left out
  -> rejected: RenderSDK: create: request: 400: Bad Request
  sent: POST /v1/jobs
Upload().create({ id: 'u1', etag: 'e1' }), the $action left out
  -> rejected: RenderSDK: create: Operation "create" has only action endpoints; pass $action to choose one.
  sent: nothing
afterwards: j1 cancelled, j2 queued, 2 jobs on the server

A cancel is not a create, and the client says so only when the caller already knows the selector. Without it, the call reaches the create route, the 400 talks about templates, and j2 stays queued. The upload entity fails earlier and more helpfully, because it has no plain create to fall back on. runtime-probe.mjs, which generate.sh runs on the unguided client of each release, recorded the same two failures on 4.45.0.

Record a decision for every operation

Write the decision down per operation, keyed by operationId, in a file the check reads. Three kinds cover this document:

{
  "listJobs": { "use": "entity", "at": "job.list" },
  "createJob": { "use": "entity", "at": "job.create" },
  "getJob": { "use": "entity", "at": "job.load" },
  "deleteJob": { "use": "entity", "at": "job.remove" },
  "cancelJob": { "use": "wrapper", "at": "cancelJob" },
  "replayJob": { "use": "wrapper", "at": "replayJob" },
  "submitJobBatch": { "use": "wrapper", "at": "submitJobBatch" },
  "completeUpload": { "use": "wrapper", "at": "completeUpload" },
  "getHealth": { "use": "excluded", "why": "probed by the load balancer, not by SDK callers" },
  "exchangeToken": { "use": "excluded", "why": "callers bring a token from their OAuth library" }
}

Force an operation onto an entity only when it reads or writes that one record, as the four job operations do. Give an action a function of its own when a caller will look for it by its verb. Leave an operation out when an SDK user never calls it. A health check belongs to the load balancer, and the token request wants a form body that an OAuth library already sends.2

Take the actions out of the model and wrap them

The guide entry file, .sdk/model/guide/guide.aontu in the project, switches the non-entity paths off. The guide reference documents active: false at entity and path level.

# Keep only the reads and writes of one job in the entity model.
# decisions.json says where every other operation goes instead.
guide: entity: health: active: false
guide: entity: batch: active: false
guide: entity: upload: active: false
guide: entity: job: path: "/jobs/{jobId}/cancel": active: false
guide: entity: job: path: "/jobs/{jobId}/replay": active: false
guide: entity: job: path: "/jobs/batch": active: false

The last line names the path where 4.45.0 puts the batch. The guide on 4.44.3 needs only the batch line, and a guide written that way stops holding on the next release.

render-actions.ts gives each of the four a typed function over direct(), which sends with the client’s base URL and token. It throws on an error status, because direct() resolves instead.

async function send<T>(client: DirectClient, route: RouteName, params?: Record<string, string>, body?: unknown): Promise<T> {
  const { method, path } = ROUTES[route]
  const req: DirectRequest = { path, method }
  if (params) req.params = params
  if (body !== undefined) req.body = body
  // direct() resolves on an error status instead of throwing, so the check is ours.
  const res = await client.direct(req)
  if (!res.ok) throw new RenderActionError(route, res.status, res.data)
  return res.data as T
}

export function cancelJob(client: DirectClient, jobId: string): Promise<Job> {
  return send<Job>(client, 'cancelJob', { jobId: segment('jobId', jobId) })
}

segment refuses an empty id, because direct() on 4.44.3 and on 4.45.0 sends one as /jobs//cancel. direct() also skips the features that hook entity operations, such as the idempotency key, as calling an endpoint with direct() measures. prepare() builds the same request without sending it.

node demo.mjs
client.Job().create({ template: 'receipt' })  j2 queued
client.Job().list()                           2 jobs
cancelJob(client, 'j1')                       cancelled
replayJob(client, 'j1')                       j3 queued
submitJobBatch(client, [two inputs])          b1, 2 accepted
completeUpload(client, 'u1', 'etag-9')        recorded
cancelJob(client, 'j1') a second time         RenderActionError, status 409
client.prepare({ ...cancel, jobId: 'j2' })    POST /v1/jobs/j2/cancel, requests sent: 0
requests the stand-in received:
  POST /v1/jobs
  GET /v1/jobs
  POST /v1/jobs/j1/cancel
  POST /v1/jobs/j1/replay
  POST /v1/jobs/batch
  POST /v1/uploads/u1/complete
  POST /v1/jobs/j1/cancel

Check it worked

coverage.mjs reads api.json, decisions.json, the wrapper’s route table, and the operation points of the compiled client. It fails on an operation with no decision and on an entity method that does not reach its route. It also fails on a wrapper route that differs from the document, and on an operation the model places somewhere the decisions do not expect.

node coverage.mjs generated/guided
api.json: 10 operations, against generated/guided
  GET    /jobs                         listJobs        entity    job.list
  POST   /jobs                         createJob       entity    job.create
  GET    /jobs/{jobId}                 getJob          entity    job.load
  DELETE /jobs/{jobId}                 deleteJob       entity    job.remove
  POST   /jobs/{jobId}/cancel          cancelJob       wrapper   cancelJob
  POST   /jobs/{jobId}/replay          replayJob       wrapper   replayJob
  POST   /jobs/batch                   submitJobBatch  wrapper   submitJobBatch
  POST   /uploads/{uploadId}/complete  completeUpload  wrapper   completeUpload
  GET    /health                       getHealth       left out  probed by the load balancer, not by SDK callers
  POST   /oauth/token                  exchangeToken   left out  callers bring a token from their OAuth library
ok: 4 on an entity, 4 in render-actions.ts, 2 left out

The tests run the checker on all six recorded builds and feed it one removal and one change of each kind. Among them are a dropped point, an operation moved or reached twice, a second method on a path, and a document with no operations. They also send every wrapper call to the stand-in:

node --test coverage.test.mjs
1..18
# tests 18
# suites 0
# pass 18
# fail 0
# cancelled 0
# skipped 0
# todo 0

When it goes wrong

The batch is reached twice after an upgrade. The guide said batch: active: false, which holds on 4.44.3, but 4.45.0 files the batch under job instead. Run the check on every regeneration:

node coverage.mjs points/guide-v1-4.45.0.json
api.json: 10 operations, against points/guide-v1-4.45.0.json
  GET    /jobs                         listJobs        entity    job.list
  POST   /jobs                         createJob       entity    job.create
  GET    /jobs/{jobId}                 getJob          entity    job.load
  DELETE /jobs/{jobId}                 deleteJob       entity    job.remove
  POST   /jobs/{jobId}/cancel          cancelJob       wrapper   cancelJob
  POST   /jobs/{jobId}/replay          replayJob       wrapper   replayJob
  POST   /jobs/batch                   submitJobBatch  wrapper   submitJobBatch
  POST   /uploads/{uploadId}/complete  completeUpload  wrapper   completeUpload
  GET    /health                       getHealth       left out  probed by the load balancer, not by SDK callers
  POST   /oauth/token                  exchangeToken   left out  callers bring a token from their OAuth library
FAIL: 1 problem
  submitJobBatch: the model also places POST /jobs/batch on job.create ($action batch)

A new endpoint ships with no decision. The checker names it as has no decision and exits 1. Add the line to decisions.json before the release, not after a caller asks.

A wrapper function keeps a path the API has renamed. The checker compares each route in render-actions.ts with the document and prints both paths. direct() itself would send the former path and return the 404 as a result.

Reach the same operations with Kiota and openapi-fetch

Kiota maps paths rather than entities. Every path becomes a request builder, so the cancel is client.jobs.byJobId('j1').cancel.post(), and the batch is client.jobs.batch.post(inputs). To leave an operation out, pass --exclude-path at generation, which records the pattern in the lock file that Kiota reads on later generations:

  "excludePatterns": [
    "/health",
    "/oauth/token"
  ],

openapi-typescript writes one paths type, and openapi-fetch calls client.POST('/jobs/{jobId}/cancel', ...) against it. A path that is not in the document does not compile, which direct() cannot offer. typecheck.mjs compiles a caller for each tool that makes all ten calls, and a mistyped cancel:

node typecheck.mjs
kiota-calls.ts: ok
openapi-fetch/calls.ts: ok
render-actions.ts: ok
openapi-fetch/typo.ts: tsc exit 2
  openapi-fetch/typo.ts(6,19): error TS2345: Argument of type '"/jobs/{jobId}/cancle"' is not assignable to parameter of type 'PathsWithMethod<paths, "post">'.

Neither tool needs a decision file to keep an operation reachable. Either still needs one to say which operations a caller should use: the health check and the token exchange are as typed as the cancel. Speakeasy puts that decision in the document, with x-speakeasy-group and x-speakeasy-name-override to name a method and x-speakeasy-ignore: true to drop one.

When not to do this

Do not force an action onto the nearest entity to save a wrapper. Job().create({ $action }) has the shape of a write and the behavior of a command, and a reader looks for the command.

Do not keep a wrapper module for an API whose actions outnumber its resources. The module is updated by hand on every change, and sdkgen’s entity model buys little when four of ten operations fit it. Kiota or openapi-fetch reach every path with types and nothing to maintain, which suits that API better.

Do not trust a guide across an upgrade of @voxgig/apidef. The batch moved between two releases, and the guide that kept it out on one let it back in on the next.

Do not skip the check because the generate step printed no warning. The moved batch produced none.

Last verified

Verified 2026-11-22 against Node 22.23.5, @voxgig/create-sdkgen 0.31.9, @voxgig/sdkgen 4.44.3 with @voxgig/apidef 8.32.4, and the same project upgraded to 4.45.0 with 8.33.1, Kiota 1.39.0, openapi-typescript 7.13.0, openapi-fetch 0.17.0, and TypeScript 5.9.3. Every output block is what the command preceding it printed. The Kiota caller was type-checked and never sent a request, while the openapi-fetch caller also ran against the stand-in in a test. No Go was run. Generation ran once, in generate.sh, and its output is committed. Speakeasy was not run, because its CLI needs an account; its extensions here are quoted from its documentation.

Footnotes

  1. An OAuth token endpoint is a sensible thing for a heuristic to recognize and decline. Its request body is defined elsewhere, by RFC 6749 section 4.4.2 for the client credentials grant, and its answer is a credential rather than a record. The base guide says so in a comment and sets active: *false, a default the guide entry file can override with active: true. ↩︎ Back to text

  2. RFC 6749 asks for the client credentials request in application/x-www-form-urlencoded, the encoding that RFC 1866 section 8.2.1, the HTML 2.0 specification of November 1995, made the default for every form. A token endpoint therefore reads the encoding a browser used to submit a form in 1995. The openapi-fetch caller here posts it through a form serializer, where every other operation takes JSON. ↩︎ Back to text

Read this page as markdown · All how-to guides

Generate the client instead of writing it#

Retries, timeouts, pagination and auth are the same problems in every client. Voxgig generates them from your OpenAPI description, in 23 languages, from one model.

Listen to Fireside, the Voxgig podcast

Since 2018, Richard Rodger has talked with developer advocates, event organizers, and the people who build developer-facing companies about the specifics of the work.