Your SDK has getBranches and fetchBranch on one resource, and listAllTags and tagDetails
on the next. Each name was reasonable on the day it was written. A user who has learned one
resource still has to look up every method on the other, and the Go build, generated a year
later, spells half of them differently.
What you get
You will end up with one verb per standard operation on every resource, a check that compares the method lists of two builds, and deprecated aliases for the names you replace. This is for you if you publish an SDK in more than one language.
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.
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 | 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 | 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 | 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 | 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 | 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:
node names.mjs
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:
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:
node method-list.mjs
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
setting applies an OpenAPI Overlay before it
generates. This one puts both resources on the verbs of Google’s standard methods:
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:
node oapi-names.mjs
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
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
says casing is adapted for each language. The names for the first operation, in an overlay:
- 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 in
sdk-config.yml. Without the extensions, Fern
takes the method name from the operationId.
This overlay has not been through Fern. Its
fern generate
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:
node --test names.test.mjs
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:
node compat-demo.mjs
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,
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
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
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.
Footnotes
-
The OpenAPI Specification 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. ↩︎ Back to text
-
In Go the capital is not a matter of style. The language specification exports an identifier only when its first character is a Unicode uppercase letter, so a method named
listwould be invisible outside its package. PEP 8 asks Python for the opposite, in a document that describes itself as a guide. ↩︎ Back to text -
The Semantic Versioning FAQ 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. ↩︎ Back to text