# How to name SDK methods the same across resources and languages

> Pick one verb for each standard operation, apply it to every resource in every language, and check it by comparing the method lists of two SDK builds.

Source: https://voxgig.com/howto/consistent-method-names-across-resources-and-languages

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

## Short answer

Pick one verb for each standard operation, write it down, and apply it to every resource in every language, changing only the casing each language expects. sdkgen does this by construction: it names operations `list`, `load`, `create`, `update`, and `remove` from the method and the path, in every target. Then compare the method lists of two builds in your pipeline. When a published name changes, keep the former one as a deprecated alias until the next major version.

---
## You will need

Node 22 or later, an OpenAPI 3 document, and two builds of the SDK to compare. The document here,
`api.json`, describes ten operations on two resources of a code host called Forge. The page
assumes resources are already the unit of your SDK, which is the subject of
[shape an SDK around entities instead of endpoint wrappers](/howto/entity-clients-instead-of-endpoint-wrappers).
Verified 2026-11-19 against Node 22.23.5, `@voxgig/sdkgen` 4.44.3, and `oapi-codegen` v2.8.2.

## Approaches compared

| Approach | When it fits | What it costs you | When to pick something else |
| --- | --- | --- | --- |
| [Fern group and method names](https://buildwithfern.com/learn/sdks/current/deep-dives/customize-method-names) | You generate with Fern and want to choose every group and method name yourself | Two extensions on each operation, kept in the document or an overlay, for you to keep consistent | You would rather inherit a vocabulary than maintain one |
| [Google AIP standard methods](https://google.aip.dev/130) | You design the API as well, and want Get, List, Create, Update, and Delete defined in writing | A design standard and not a generator, so something else must apply it to each SDK | The API exists and its operations cannot be reshaped |
| [`oapi-codegen` operationId names](https://github.com/oapi-codegen/oapi-codegen/blob/v2.8.2/README.md#modifying-the-input-openapi-specification-with-openapi-overlay) | A Go client whose method names should match the operationIds your API reference prints | Names as uneven as the operationIds, until an overlay you maintain renames each one | You publish in languages other than Go |
| [sdkgen operation vocabulary](https://github.com/voxgig/sdkgen/blob/main/docs/explanation/operation-pipeline.md) | You want one fixed set of verbs in every language, without writing a name | Verbs you did not choose: `load` and `remove`, where your API reference may say get and delete | Method names must match the operationIds your documentation prints |
| [Stripe method naming](https://github.com/stripe/stripe-node/blob/master/src/resources/Customers.ts) | You hand-write the SDK and want verbs many developers have met before | A convention kept by review, with exceptions of its own: stripe-node spells delete as `del` | You need a generator, not a reviewer, to hold the names |

Voxgig maintains sdkgen. It is one of five options here, not the recommendation.

The five rows are two kinds of thing. Stripe and Google publish vocabularies, which say what to
call an operation and leave the enforcing to you. stripe-node's verbs are `list`, `retrieve`,
`create`, `update`, and `del`, and Google's are List, Get, Create, Update, and Delete. The three
generators enforce a name and differ in where it comes from. `oapi-codegen` copies the
operationId, Fern reads the two names you give it, and sdkgen ignores both and names the
operation from its method and path.

## List the names you would publish

`api.json` has operationIds from two authors: `getBranches` beside `listAllTags`, `fetchBranch`
beside `tagDetails`.[^1] A generator that names methods from operationIds publishes those.
`names.mjs` prints each id beside the method that an sdkgen build exports for the same request,
in three languages:

```bash
node names.mjs
```

```text output
operationId   request                      TypeScript         Python             Go
getBranches   GET /branches                Branch().list()    Branch().list()    Branch(nil).List(nil, nil)
addBranch     POST /branches               Branch().create()  Branch().create()  Branch(nil).Create(nil, nil)
fetchBranch   GET /branches/{branchId}     Branch().load()    Branch().load()    Branch(nil).Load(nil, nil)
deleteBranch  DELETE /branches/{branchId}  Branch().remove()  Branch().remove()  Branch(nil).Remove(nil, nil)
branchUpdate  PATCH /branches/{branchId}   Branch().update()  Branch().update()  Branch(nil).Update(nil, nil)
listAllTags   GET /tags                    Tag().list()       Tag().list()       Tag(nil).List(nil, nil)
newTag        POST /tags                   Tag().create()     Tag().create()     Tag(nil).Create(nil, nil)
tagDetails    GET /tags/{tagId}            Tag().load()       Tag().load()       Tag(nil).Load(nil, nil)
removeTag     DELETE /tags/{tagId}         Tag().remove()     Tag().remove()     Tag(nil).Remove(nil, nil)
editTag       PATCH /tags/{tagId}          Tag().update()     Tag().update()     Tag(nil).Update(nil, nil)
```

The operation names do not come from the ids. sdkgen's model classifies each request by method and path, and every
target emits the operation's name. Both resources get the same five verbs. The casing is each
language's own. Go exports a method by capitalizing it,[^2] and the other two keep it in lower
case. Each name is one word, so `camelCase` and `snake_case` have nothing to disagree about.

## Compare the method lists of two builds

A vocabulary lasts only while something checks it. `method-list.mjs` collects the operation
methods of each build, lower-cases them, and compares the builds in pairs:

```js title="method-list.mjs"
export function methodLists({ ts = typescriptBuild(), py = pythonBuild(), go = goBuild() } = {}) {
  const lines = (build) => Object.entries(build)
    .flatMap(([entity, methods]) => methods.map((name) => `${entity}.${name.toLowerCase()}`))
    .sort()
  return { ts: lines(ts), py: lines(py), go: lines(go.operations) }
}
```

It finds an operation method by its last parameter, the per-call control argument, and never by
its name, because a filter on names would hide a rename. Run it over the three builds:

```bash
node method-list.mjs
```

```text output
ts  branch.create branch.list branch.load branch.remove branch.update tag.create tag.list tag.load tag.remove tag.update
py  branch.create branch.list branch.load branch.remove branch.update tag.create tag.list tag.load tag.remove tag.update
go  branch.create branch.list branch.load branch.remove branch.update tag.create tag.list tag.load tag.remove tag.update
go also exports 10 Typed twins, and 2 methods that return UnsupportedOp: Patch
ts against py: same operations
ts against go: same operations
py against go: same operations
```

The three lists match. The fourth line is what a plain diff would trip over. The Go build
exports a `Typed` twin of every operation, and a `Patch` method that returns an
unsupported-operation error. sdkgen's vocabulary has a sixth operation, `patch`, which stays empty
here because a `PATCH` on a path with no `PUT` is classified as `update`.
Report those and compare the rest. The command exits 1 when two builds differ, so run it after
every regeneration.

## Rename the operationIds in an overlay for the Go client

`oapi-codegen` turns each operationId into a Go method name, so its names are as consistent as
the ids. When the document is not yours to edit, its
[`output-options.overlay.path`](https://github.com/oapi-codegen/oapi-codegen/blob/v2.8.2/README.md#modifying-the-input-openapi-specification-with-openapi-overlay)
setting applies an [OpenAPI Overlay](https://spec.openapis.org/overlay/v1.0.0.html) before it
generates. This one puts both resources on the verbs of Google's standard methods:

```yaml title="oapi-codegen/names.overlay.yaml"
actions:
  - target: $.paths['/branches'].get
    update: { operationId: listBranches }
  - target: $.paths['/branches'].post
    update: { operationId: createBranch }
  - target: $.paths['/branches/{branchId}'].get
    update: { operationId: getBranch }
```

`oapi-names.mjs` reads the client interface from both generated files:

```bash
node oapi-names.mjs
```

```text output
request                      forge.gen.go    forge-renamed.gen.go
GET /branches                GetBranches     ListBranches
POST /branches               AddBranch       CreateBranch
GET /branches/{branchId}     FetchBranch     GetBranch
DELETE /branches/{branchId}  DeleteBranch    DeleteBranch
PATCH /branches/{branchId}   BranchUpdate    UpdateBranch
GET /tags                    ListAllTags     ListTags
POST /tags                   NewTag          CreateTag
GET /tags/{tagId}            TagDetails      GetTag
DELETE /tags/{tagId}         RemoveTag       DeleteTag
PATCH /tags/{tagId}          EditTag         UpdateTag
```

Every verb is yours to choose, where sdkgen hands you its own, and the Go methods match the ids
your API reference prints. The cost is the overlay: ten actions for ten operations, and an
eleventh operation ships whatever id its author writes. The
[`name-normalizer`](https://github.com/oapi-codegen/oapi-codegen/blob/v2.8.2/README.md#changing-the-names-of-generated-types)
output option changes how an id is cased, not which verb it carries.

## Give Fern a group and a method name

Fern takes two names for each operation. `x-fern-sdk-group-name` and `x-fern-sdk-method-name` sit
on the operation, in the document or in an overlay, and its
[method names page](https://buildwithfern.com/learn/sdks/current/deep-dives/customize-method-names)
says casing is adapted for each language. The names for the first operation, in an overlay:

```yaml title="fern/names.overlay.yaml"
  - target: $.paths['/branches'].get
    update: { x-fern-sdk-group-name: branches, x-fern-sdk-method-name: list }
```

The page's own example reads `client.users.create()`, with `snake_case` in Python, `camelCase`
in TypeScript, and `PascalCase` in Go. Fern's current configuration format lists the overlay under
[`source.specs[].overlays`](https://buildwithfern.com/learn/sdks/current/reference/sdk-config) in
`sdk-config.yml`. Without the extensions, Fern
[takes the method name from the operationId](https://buildwithfern.com/learn/api-definitions/openapi/extensions/method-names).

This overlay has not been through Fern. Its
[`fern generate`](https://buildwithfern.com/learn/cli-api-reference/cli-reference/sdk-commands)
command runs on Fern's cloud by default, which takes a login or a guest session, or in Docker
with `--local`. A test confirms only that the overlay names all ten operations with one verb per
request shape.

## Check it worked

Run the suite:

```bash
node --test names.test.mjs
```

```text output
1..11
# tests 11
# suites 0
# pass 11
# fail 0
# cancelled 0
# skipped 0
# todo 0
```

`# pass 11` includes one test that renames `remove` to `delete` in a copy of the Python build and
expects `method-list.mjs` to exit 1.

## When it goes wrong

A minor release renames a method, and a caller's code fails on upgrade with
`client.getBranches is not a function`. The rename was silent. Keep each former name as a deprecated
alias that calls the replacement, and remove it in a major version.[^3] `compat-demo.mjs` builds
the aliases from the document's operationIds:

```bash
node compat-demo.mjs
```

```text output
a silent rename: the name the first release published is gone
  typeof client.getBranches   undefined
the same rename with deprecated aliases
  legacy.getBranches()        main, release-3
  client.Branch().list()      main, release-3
  aliases kept                10 of 10 published names
  warnings after two calls    1
  getBranches() is deprecated: call Branch().list() instead. It is removed in 3.0.0.
```

Each alias warns once, through Node's
[`process.emitWarning`](https://nodejs.org/docs/latest-v22.x/api/process.html#processemitwarningwarning-type-code-ctor),
and names both its replacement and the version that removes it.

The comparison reports methods that only one build has. A language target may export helpers
beside the operations, as the Go build does. Recognize an operation by its signature, and print
what you set aside.

## When not to do this

Do not rename the methods of a published SDK for consistency alone. Every rename costs your
users an edit, and the aliases cost you a major version of upkeep.

Do not stretch the vocabulary over an action. Merging a branch is not an update, and a verb
that hides it is harder to find than a plain `merge` would be. sdkgen does stretch it: its
[classification notes](https://github.com/voxgig/apidef/blob/main/docs/explanation/classification-heuristics.md)
put `PUT .../merge` in the `update` slot, reached through `update()` with an `$action` selector.

Do not choose sdkgen for its names when your API reference already says get and delete. Its
verbs are `load` and `remove`, and users will meet both spellings. `oapi-codegen` is the better
choice for a Go-only SDK whose users search for the operationIds in your reference. Fern is the
better choice when you want to pick the verbs yourself and still define each name once for
every language.

## Related how-tos

- [Shape an SDK around entities instead of endpoint wrappers](/howto/entity-clients-instead-of-endpoint-wrappers)

- [Rename a generated SDK method without editing the output](/howto/rename-generated-methods-without-editing-output)

- [Write operationIds that generate clean SDK method names](/howto/operationids-that-generate-clean-sdk-method-names)

- [Tell an entity-shaped SDK from an endpoint-shaped one](/howto/measure-entity-versus-endpoint-shaped-output)

- [Design an SDK constructor that takes configuration once](/howto/sdk-client-constructor-and-configuration)

- [Expose typed SDK errors callers match without parsing text](/howto/typed-sdk-errors-callers-can-match)

## Last verified

Verified 2026-11-19 against Node 22.23.5, `@voxgig/create-sdkgen` 0.31.9, `@voxgig/sdkgen` 4.44.3,
and `oapi-codegen` v2.8.2. Every output block is what the command preceding it printed. sdkgen
and `oapi-codegen` each ran once, through `generate.sh`, and what they wrote is committed: the
compiled TypeScript build, the entity files of the Python and Go builds, and both Go clients.
The Go build was also compiled and the Python build imported, once, to confirm the method lists.
Fern was not run. Its extensions and its configuration key come from its documentation. Stripe's
and Google's vocabularies are read from the pages linked in the table.

[^1]: The [OpenAPI Specification](https://spec.openapis.org/oas/v3.0.3#operation-object) asks
only that an operationId be unique among the operations of the API, and notes that it is
case-sensitive. It adds that tools MAY use the id to identify an operation, and that it is
therefore RECOMMENDED to follow common programming naming conventions, without saying which
language's conventions those are.

[^2]: In Go the capital is not a matter of style. The
[language specification](https://go.dev/ref/spec#Exported_identifiers) exports an identifier
only when its first character is a Unicode uppercase letter, so a method named `list` would be
invisible outside its package. [PEP 8](https://peps.python.org/pep-0008/#function-and-variable-names)
asks Python for the opposite, in a document that describes itself as a guide.

[^3]: The [Semantic Versioning FAQ](https://semver.org/spec/v2.0.0.html#how-should-i-handle-deprecating-functionality)
sets the order: document the change, ship a minor release with the deprecation in place, and
only then remove the feature in a major one. It asks for at least one minor release
between the warning and the removal, so that users can transition smoothly.