# 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.

Source: https://voxgig.com/howto/classify-openapi-operations-by-path-shape

- Audience: api-producer
- Level: beginner
- Languages: typescript, go
- Verified: 2026-11-22
- Published: 2026-11-22

## 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

| Approach | When it fits | What it costs you | When to pick something else |
| --- | --- | --- | --- |
| [@voxgig/apidef heuristics](https://github.com/voxgig/apidef/blob/main/docs/explanation/classification-heuristics.md) | Hundreds of operations, and SDKs shaped as entities with list, load and create | Guesses that move between releases, and a guide file to correct the wrong ones | Method names must be exactly what the document's authors wrote |
| [Kiota request builders](https://learn.microsoft.com/en-us/openapi/kiota/request-builders) | A client that mirrors the URL tree, one request builder per path segment | No kinds at all: a search is a POST on its own path, named by the method | Callers expect list, load and create on an entity |
| [NSwag operation generation modes](https://github.com/RicoSuter/NSwag/wiki/ClientGeneratorBaseSettings) | C# or TypeScript clients whose operationIds already read `Things_List` | The mapping lives in every operationId, written and kept by people | The operationIds follow no convention and cannot change |
| [OpenAPI Generator operationId methods](https://openapi-generator.tech/docs/customization/#name-mapping) | Method names should be the operationIds, grouped into classes by tag | No kind for any operation, and untagged ones share one `DefaultApi` class | The 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.

## Print the kind of every operation

`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.

```js title="classify.mjs"
  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`.

```bash
node classify.mjs api.json
```

```text output
@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`](https://unpkg.com/@voxgig/apidef@8.32.4/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`](https://unpkg.com/@voxgig/apidef@8.32.4/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.

```bash
node shapes.mjs
```

```text output
@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.

```bash
node body-probe.mjs
```

```text output
@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`.

```aontu title="guide/search-is-a-list.aontu"
guide: entity: thing: path: "/things/search": op: create: { active: false, method: "POST" }
guide: entity: thing: path: "/things/search": op: list: method: "POST"
```

```bash
node classify.mjs api.json guide/search-is-a-list.aontu
```

```text output
@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.

```text title="records/apidef-8.33.1.txt"
--- 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](https://github.com/voxgig/apidef/blob/main/docs/explanation/classification-heuristics.md)
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.

```bash
node --test classify.test.mjs
```

```text output
# 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`](https://openapi-generator.tech/docs/customization/#name-mapping)
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](https://github.com/RicoSuter/NSwag/wiki/ClientGeneratorBaseSettings) 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.

```bash
node methods.mjs PathSegments
```

```text output
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.

```text title="records/tsc.txt"
== 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.

```bash
node methods.mjs controller
```

```text output
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.

## Related how-tos

- [Normalize an inconsistent spec before extracting a model](/howto/normalise-an-inconsistent-spec-before-extraction)

- [Diff two semantic models from successive spec versions](/howto/diff-two-semantic-models-across-versions)

- [Enforce a naming convention across 40 microservice specs](/howto/enforce-naming-conventions-across-many-specs)

- [Decide if an endpoint is an entity operation or an action](/howto/entity-operation-or-standalone-action)

- [Generate your first SDK with sdkgen](/howto/first-sdk-with-sdkgen)

- [Handle endpoints that do not map to an entity](/howto/endpoints-that-map-to-no-entity)

## 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.

[^1]: HEAD asks for what GET would return, minus the content, as
[RFC 9110 section 9.3.2](https://www.rfc-editor.org/rfc/rfc9110.html#section-9.3.2) puts it,
which leaves an entity model little to hold. PATCH has a definition of its own in
[RFC 5789](https://www.rfc-editor.org/rfc/rfc5789.html#section-2), 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.