How-to › Describe your API

How to classify OpenAPI operations into CRUD kinds by path shape#

Print every operation in an OpenAPI document beside the entity operation @voxgig/apidef gave it, and correct the wrong guesses, such as a search filed as a create.

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

Read first: Normalize an inconsistent spec before extracting a model

Your document has POST /things/search, which takes a filter and answers an array of things. @voxgig/apidef 8.32.4 files it in the create slot of the thing entity, the slot POST /things gets, with search as an action. The model a generator reads from then says that searching creates a thing.

What you get

You will end up with a table that gives every operation’s operationId, method, path, and the kind apidef chose, and a guide correction for the wrong ones. This is for you if you generate from a model and want to read its guesses first.

Short answer

Run @voxgig/apidef as a library over the document and print one row per operation: operationId, method, path, and the entity and slot it landed in. The model drops operationId, so join it back by method and path. apidef has six slots: list, load, create, update, remove and patch. Fix a wrong guess in the guide file, pin the apidef version, and read the table again after every upgrade.

You will need

Node 22 or later and an OpenAPI 3 document. Verified 2026-11-22 against @voxgig/apidef 8.32.4, and again on 8.33.1. The sample document has eleven operations on six paths: /things, its item path, a search, an archive action, /health and /reports/{reportId}.

Approaches compared

ApproachWhen it fitsWhat it costs youWhen to pick something else
@voxgig/apidef heuristicsHundreds of operations, and SDKs shaped as entities with list, load and createGuesses that move between releases, and a guide file to correct the wrong onesMethod names must be exactly what the document’s authors wrote
Kiota request buildersA client that mirrors the URL tree, one request builder per path segmentNo kinds at all: a search is a POST on its own path, named by the methodCallers expect list, load and create on an entity
NSwag operation generation modesC# or TypeScript clients whose operationIds already read Things_ListThe mapping lives in every operationId, written and kept by peopleThe operationIds follow no convention and cannot change
OpenAPI Generator operationId methodsMethod names should be the operationIds, grouped into classes by tagNo kind for any operation, and untagged ones share one DefaultApi classThe generator should group operations into entities for you

Voxgig maintains apidef. It is the subject of this page, and its row says what the heuristics cost; the other three tools are not Voxgig’s.

Heuristics scale to a document nobody has read in full, and they get some operations wrong. The operationId conventions OpenAPI Generator and NSwag rely on are exact, and a person has to write and keep every one. Kiota avoids the question by naming nothing after a kind.

classify.mjs builds apidef’s model in memory, with ctrl.step.generate off so no model files are written. The model keeps the method and path of each point and drops the operationId, so the script joins each point back to the document.

  const kinds = new Map()
  for (const name of entities) {
    for (const [slot, op] of Object.entries(kit.entity[name].op ?? {})) {
      for (const point of op?.points ?? []) {
        const key = `${point.m} ${point.o}`
        const kind = `${name}.${slot}` + (point.q?.$action ? ` (action ${point.q.$action})` : '')
        kinds.set(key, kinds.has(key) ? `${kinds.get(key)}, ${kind}` : kind)
      }
    }
  }
  const rows = ops.map((o) => ({ ...o, kind: kinds.get(`${o.method} ${o.path}`) ?? 'none' }))

The rows come from the document, not the model. An operation the model leaves out still gets a row, marked none.

node classify.mjs api.json
@voxgig/apidef 8.32.4
operationId   method  path                       kind
listThings    GET     /things                    thing.list
createThing   POST    /things                    thing.create
headThings    HEAD    /things                    none
getThing      GET     /things/{thingId}          thing.load
replaceThing  PUT     /things/{thingId}          thing.update
deleteThing   DELETE  /things/{thingId}          thing.remove
patchThing    PATCH   /things/{thingId}          thing.patch
searchThings  POST    /things/search             thing.create (action search)
archiveThing  POST    /things/{thingId}/archive  thing.create (action archive)
healthCheck   GET     /health                    health.load
fetchReport   GET     /reports/{reportId}        thing.list

Read which signal decided each kind

The method decides the slot first. In 8.32.4, METHOD_IDOP in dist/guide/heuristic01.js (line 33) maps GET to load, POST to create, PUT to update, DELETE to remove, PATCH to patch and HEAD to head. Line 1002 then turns a load into a list when the response is a list, which is why fetchReport is not a load.

Two rules in dist/transform/operation.js come after that. Line 19 drops head, so HEAD lands on no slot.1 Line 113 moves patch into update when the entity has no update. The path shape names the entity and turns a trailing literal into an action, but it does not pick the slot: a GET on /things that answers one Thing is a load.

shapes.mjs changes api.json one way at a time and prints the kind of the operation each change is about, one row for each path shape.

node shapes.mjs
@voxgig/apidef 8.32.4
nothing: a collection                  GET /things                     thing.list
nothing: an item                       GET /things/{thingId}           thing.load
nothing: an action after an item       POST /things/{thingId}/archive  thing.create (action archive)
GET /things answers one Thing          GET /things                     thing.load
GET on the item answers an array       GET /things/{thingId}           thing.list
the item loses its PUT                 PATCH /things/{thingId}         thing.update
a nested collection is added           GET /things/{thingId}/parts     thing.list (action part)
GET / is added, no parameter, no noun  GET /                           service_index.load

The nested collection became an action on thing, not an entity of its own. With no noun in the path, the entity took its name from the operationId serviceIndex, although the model keeps no operationId field. 8.33.1 printed the same eight kinds.

The request body changed no kind in this document. body-probe.mjs removes all four request bodies and classifies again. The heuristics page does name rules that read a body. They name a command, or decide whether a PUT to a sub-path updates the item, and this document gives neither case.

node body-probe.mjs
@voxgig/apidef 8.32.4: 4 request bodies removed, 0 of 11 kinds changed

Correct the search in the guide

apidef reads corrections from the guide entry file, below the two include lines. This one switches off the create slot for the search path and puts it in list.

guide: entity: thing: path: "/things/search": op: create: { active: false, method: "POST" }
guide: entity: thing: path: "/things/search": op: list: method: "POST"
node classify.mjs api.json guide/search-is-a-list.aontu
@voxgig/apidef 8.32.4
operationId   method  path                       kind
listThings    GET     /things                    thing.list
createThing   POST    /things                    thing.create
headThings    HEAD    /things                    none
getThing      GET     /things/{thingId}          thing.load
replaceThing  PUT     /things/{thingId}          thing.update
deleteThing   DELETE  /things/{thingId}          thing.remove
patchThing    PATCH   /things/{thingId}          thing.patch
searchThings  POST    /things/search             thing.list (action search)
archiveThing  POST    /things/{thingId}/archive  thing.create (action archive)
healthCheck   GET     /health                    health.load
fetchReport   GET     /reports/{reportId}        thing.list

The search row moved and the other ten did not, which a test checks. create keeps method: "POST" inside the braces on purpose. The shorter op: create: active: false builds on 8.32.4 and stops the 8.33.1 build, because 8.33.1 already puts the search in list and has no create there to switch off. generate.sh ran both forms on 8.33.1.

--- with guide/search-is-a-list-bare.aontu
apidef 8.33.1 did not build: SUMMARY (1 errors): [aontu/mapval_spread_required]: Cannot unify values at path $.guide.entity.thing.path.op.method
exit 1
--- request bodies
@voxgig/apidef 8.33.1: 4 request bodies removed, 0 of 11 kinds changed

On 8.33.1 the uncorrected table differs in two rows: searchThings is thing.list (action search), and fetchReport gains (action report). 8.33.1 adds a rule after the method map: a POST whose last literal opens with a read verb such as search, and that answers a collection, is a list. The classification heuristics page on the main branch states that rule. So on 8.32.4 the search needs the correction, and on 8.33.1 it needs none and only the braced form builds. Pin the release in a lockfile, because the table belongs to one version.

Check it worked

Run the tests. They pin all eleven kinds and every path shape on 8.32.4, both guide forms, the PATCH rule, the body probe, and the entity an operationId names. They also read the records from 8.33.1 and the two other generators.

node --test classify.test.mjs
# tests 19
# suites 0
# pass 19
# fail 0
# cancelled 0
# skipped 0
# todo 0

A correction has worked when its row reads thing.list (action search) and no other row moved.

When it goes wrong

The table is empty and the build reported success. apidef builds a document cut short after "paths": and returns a model with no entity, and the test reproduces that. classify.mjs parses the document with JSON.parse first, refuses a run that classified no operation, and exits 1 for both.

The build fails after an upgrade with mapval_spread_required. A guide correction names a slot the release no longer fills. Write the switched-off slot with its method, as guide/search-is-a-list.aontu does, and run the table on both versions before you merge the upgrade.

An operation reads none. HEAD gives no slot in this run, and the heuristics page says the same of OPTIONS and TRACE. Decide for each none whether the SDK needs it, and reach it some other way if it does.

Name operations the way OpenAPI Generator and NSwag do

Neither run assigned a kind. OpenAPI Generator names each method after its operationId and puts untagged operations in DefaultApi; the committed typescript-fetch client has exactly the eleven operationIds. Given a tag on each operation, the same release wrote HealthApi, ReportsApi and a ThingsApi holding nine methods. Its --operation-id-name-mappings option renames one method without editing the document.

NSwag’s OperationGenerationMode is the closer match, because one of its modes reads path shape. Its settings page says MultipleClientsFromPathSegments takes the operation name from the nth segment and the client name from the one before it. In this run, the operations on /things and its item also got the HTTP method.

node methods.mjs PathSegments
NSwag, MultipleClientsFromPathSegments
  Client.thingsGet           GET    /things
  Client.thingsPost          POST   /things
  Client.thingsHead          HEAD   /things
  Client.thingsGet           GET    /things/{thingId}
  Client.thingsPut           PUT    /things/{thingId}
  Client.thingsPatch         PATCH  /things/{thingId}
  Client.thingsDelete        DELETE /things/{thingId}
  Client.health              GET    /health
  Client.reports             GET    /reports/{reportId}
  ThingsClient.search        POST   /things/search
  ThingsClient.archive       POST   /things/{thingId}/archive

The list and the load are both thingsGet, and tsc refuses the file. NSwag 14.8.0 was the newest release on npm on the day.

== path-segments.ts exit 2
generated/nswag/path-segments.ts(23,5): error TS2393: Duplicate function implementation.

The default mode, MultipleClientsFromOperationId, reads operationIds in the form {controller}_{action}, and put all eleven of this document’s ids in one Client. Write the classification into the ids, as controller-ids.mjs does, and NSwag groups the operations by entity.

node methods.mjs controller
NSwag, {controller}_{action} ids
  ThingsClient.list          GET    /things
  ThingsClient.create        POST   /things
  ThingsClient.head          HEAD   /things
  ThingsClient.load          GET    /things/{thingId}
  ThingsClient.update        PUT    /things/{thingId}
  ThingsClient.patch         PATCH  /things/{thingId}
  ThingsClient.remove        DELETE /things/{thingId}
  ThingsClient.search        POST   /things/search
  ThingsClient.archive       POST   /things/{thingId}/archive
  HealthClient.load          GET    /health
  ReportsClient.list         GET    /reports/{reportId}

That client compiles. The search is ThingsClient.search, a name a person chose, so no heuristic can file it under create.

When not to do this

Do not trust a classification you have not printed. apidef’s heuristics page says they are tuned for conventional REST APIs, and the table is where a wrong guess shows before an SDK ships.

Do not leave the apidef version floating. The same document gave two different tables on 8.32.4 and 8.33.1, and a correction written for one stopped the other’s build.

Do not use apidef for a small API whose operationIds you control. Writing Things_List by hand for twenty operations is a short job, and NSwag or OpenAPI Generator then needs no correction file and gives exactly the names you wrote. Kiota suits a team that wants its client to follow the URL tree and not to name kinds at all.

Last verified

Verified 2026-11-22 against Node 22.23.5 and @voxgig/apidef 8.32.4, with 8.33.1 run by generate.sh in a scratch copy. OpenAPI Generator 7.27.0, NSwag 14.8.0 on the ASP.NET Core 10 runtime, and TypeScript 5.9.3 also ran once there, and their output is committed. Every output block is what the command preceding it printed. Kiota was not run; its row comes from its documentation, read on the same day.

Footnotes

  1. HEAD asks for what GET would return, minus the content, as RFC 9110 section 9.3.2 puts it, which leaves an entity model little to hold. PATCH has a definition of its own in RFC 5789, which tells it from PUT by the body. A PUT body is a modified version of the resource, and a PATCH body is a set of instructions for modifying it. ↩︎ 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.