How-to › Ship an SDK

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.

Audience
API producer
Level
beginner
Topic
Design SDK ergonomics per language
Languages
TypeScript, Python and Go
Verified

Read first: Shape an SDK around entities instead of endpoint wrappers

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

ApproachWhen it fitsWhat it costs youWhen to pick something else
Fern group and method namesYou generate with Fern and want to choose every group and method name yourselfTwo extensions on each operation, kept in the document or an overlay, for you to keep consistentYou would rather inherit a vocabulary than maintain one
Google AIP standard methodsYou design the API as well, and want Get, List, Create, Update, and Delete defined in writingA design standard and not a generator, so something else must apply it to each SDKThe API exists and its operations cannot be reshaped
oapi-codegen operationId namesA Go client whose method names should match the operationIds your API reference printsNames as uneven as the operationIds, until an overlay you maintain renames each oneYou publish in languages other than Go
sdkgen operation vocabularyYou want one fixed set of verbs in every language, without writing a nameVerbs you did not choose: load and remove, where your API reference may say get and deleteMethod names must match the operationIds your documentation prints
Stripe method namingYou hand-write the SDK and want verbs many developers have met beforeA convention kept by review, with exceptions of its own: stripe-node spells delete as delYou 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.

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

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

  2. 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 list would be invisible outside its package. PEP 8 asks Python for the opposite, in a document that describes itself as a guide. ↩︎ Back to text

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

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.