Your service makes five calls to GitHub. A reviewer asks which of Octokit’s thousand methods the code uses, because the pull request adds twenty packages for them. A generated client looked lighter until the one call it lacks turned up after the integration was half written.
What you get
You will end up with a list of the operations you call and a scored run of four clients against a stand-in for exactly those operations. This is for you if you call a public API that already has an official client and must pick one.
Short answer
List the operations your code calls before you pick a client, then run each candidate against a
stand-in for those operations. For five GitHub calls, Octokit covered all five and paged by
itself, at 20 packages. The SDK Catalog’s github-rest-sdk covered four, at one package.
Counting the pieces you would write by hand within a package budget then picks Octokit at 20
packages or more, the catalog client below that, and plain fetch at none.
You will need
Node 22 or later, and the OpenAPI description of the API you call. The sample reads GitHub’s REST description at tag v2.1.0 and calls a 127.0.0.1 stand-in for five of its operations, so it needs no GitHub account.
Approaches compared
| Approach | When it fits | What it costs you | When to pick something else |
|---|---|---|---|
| Fern | You want a generated client whose paging is declared once in the description | A login, a guest session on Fern’s servers, or Docker for local runs | You need no account and nothing to configure |
| Octokit | You call GitHub and want GitHub’s own client | Twenty packages and 17310 KiB on disk, nearly all type declarations | Bundle size matters and you call a handful of routes |
| plain fetch | A few calls, and nothing to upgrade | You write paging, errors, escaping and auth yourself, and test them | The calls grow past what you want to maintain |
SDK Catalog github-rest-sdk | Your calls are inside its 21 operations | Not on npm, so you pack a clone; unofficial, and a call outside its model needs direct() | Your list includes calls its model lacks |
| Swagger Codegen | You want a client for exactly the operations you list | The output fails tsc on this description, drops response headers, and needs isomorphic-fetch | You want typed TypeScript that compiles as generated |
Voxgig maintains the SDK Catalog, which generates github-rest-sdk with sdkgen. It is one of five
options here, not the recommendation, and the client is not GitHub’s.
Octokit is the only one of the four run here that GitHub maintains, so it follows the API by its own releases. The catalog client and a generated one cover what their description covers. Plain fetch has nothing to upgrade and nothing to help you.
List the operations you call
Write the list down as data. trim.mjs checks each entry against GitHub’s description and keeps
only those operations, for the generator and the stand-in:
[
{ "method": "GET", "path": "/repos/{owner}/{repo}", "operationId": "repos/get" },
{ "method": "GET", "path": "/repos/{owner}/{repo}/issues", "operationId": "issues/list-for-repo" },
{ "method": "POST", "path": "/repos/{owner}/{repo}/issues", "operationId": "issues/create" },
{ "method": "POST", "path": "/repos/{owner}/{repo}/issues/{issue_number}/comments", "operationId": "issues/create-comment" },
{ "method": "GET", "path": "/repos/{owner}/{repo}/pulls/{pull_number}", "operationId": "pulls/get" }
]
cat records/description.txt
GitHub v3 REST API 1.1.4, OpenAPI 3.0.3
operations in the description: 860
operations kept: 5
components kept: 43
Five of 860. The choice turns on those five, so score them and nothing else.
Find each call in each client
coverage.mjs asks each client for the method behind each operation: Octokit’s endpoint
defaults, the catalog SDK’s entity config, and the classes Swagger Codegen wrote.
node coverage.mjs
operation Octokit SDK Catalog github-rest-sdk Swagger Codegen
repos/get rest.repos.get Repo.load ReposApi.reposget
issues/list-for-repo rest.issues.listForRepo Issue.list IssuesApi.issueslistForRepo
issues/create rest.issues.create Issue.create IssuesApi.issuescreate
issues/create-comment rest.issues.createComment none IssuesApi.issuescreateComment
pulls/get rest.pulls.get Pull.load PullsApi.pullsget
operations in the client 1028 21 5
The catalog’s GitHub model holds 21 operations, and issue comments are not among them. Its
direct() call takes a path and returns the status, headers and body, so the comment still
works:
comment: async (owner, repo, number, body) => {
const res = await gh.direct({ path: 'repos/{owner}/{repo}/issues/{issue_number}/comments', method: 'POST',
params: { owner, repo, issue_number: number }, body: { body } })
if (!res.ok) throw Object.assign(res.err ?? new Error(`comment: status ${res.status}`), { status: res.status })
return res.data
},
The catalog repository’s install table marks the TypeScript package publish pending, and npm
answered E404 for the name. The sample packs ts/ from a clone at a pinned commit and commits the
tarball, with its MIT license beside it.
Run the five calls through each client
score.mjs gives each client a fresh stand-in holding five issues, lists them two per page, and
asks for a pull request that does not exist. Every client gets localFetch, which keeps loopback
traffic off any proxy:
node score.mjs
5 operations: repos/get, issues/list-for-repo, issues/create, issues/create-comment, pulls/get
client calls list issues missing pull Authorization
Octokit 5 of 5 5 of 5 issues, 3 requests RequestError, status 404 token test-token
SDK Catalog github-rest-sdk 5 of 5 5 of 5 issues, 3 requests GithubRestError, status 404 Bearer test-token
Swagger Codegen 5 of 5 5 of 5 issues, 3 requests a Response, status 404 Bearer test-token
plain fetch 5 of 5 5 of 5 issues, 3 requests Error, status 404 Bearer test-token
The rows match because each adapter in clients.mjs did the missing work. Octokit’s
paginate follows the Link header that
GitHub paginates with.1
The catalog’s list() returns one page and no headers, so its adapter asks for pages until one
comes back short. A test with four issues shows the cost: that loop sends a third request, and
Octokit sends two.
Errors differ more. Swagger Codegen throws the Response itself, so the caller reads its status
and body. Plain fetch throws nothing on a 404 until you write the check.
Turn the scores into a choice
decide.mjs counts the pieces you would write by hand for each client: a call the client does not
name, a paging loop when it has no pager, and a compile fix when tsc failed. Among the clients
inside your package budget it takes the fewest pieces, then the fewest packages:
node decide.mjs
5 operations
client packages calls by hand paging by hand compile fix pieces
Octokit 20 0 no no 0
SDK Catalog github-rest-sdk 1 1 yes no 2
Swagger Codegen 6 0 yes yes 2
plain fetch 0 5 yes no 6
package budget choice
20 or more Octokit
1 to 19 SDK Catalog github-rest-sdk
0 plain fetch
Swagger Codegen ties the catalog client at two pieces and loses on packages. Add one more call the catalog lacks, listing an issue’s comments, and the middle band moves:
node decide.mjs endpoints-wider.json
6 operations
client packages calls by hand paging by hand compile fix pieces
Octokit 20 0 no no 0
SDK Catalog github-rest-sdk 1 2 yes no 3
Swagger Codegen 6 0 yes yes 2
plain fetch 0 6 yes no 7
package budget choice
20 or more Octokit
6 to 19 Swagger Codegen
1 to 5 SDK Catalog github-rest-sdk
0 plain fetch
So Octokit wins whenever 20 packages are acceptable, plain fetch when none are, and the two generated clients split the band between by how many of your calls the catalog’s model holds. The weights are a starting point: give your team’s own costs a column before you trust the answer.
Generate the client with Swagger Codegen or Fern
generate.sh ran Swagger Codegen 3.0.85’s typescript-fetch on the five-operation description,
then tsc:
cat records/swagger.txt
Swagger Codegen 3.0.85, typescript-fetch, from the 5-operation description
generated: api.ts api_test.spec.ts configuration.ts custom.d.ts index.ts
imports: url isomorphic-fetch ./configuration
tsc exit 2
api.ts(4062,5): error TS2300: Duplicate identifier '_1'.
api.ts(4068,5): error TS2300: Duplicate identifier '_1'.
the two lines tsc names, from api.ts:
4062: _1: number;
4068: _1: number;
GitHub's ReactionRollup properties: url total_count +1 -1 laugh confused heart hooray eyes rocket
The TypeScript does not compile as written, because GitHub’s +1 and -1 reaction counts both
became _1.2 The JavaScript still emits, and the sample commits it. Each call returns the parsed
body only, so the Link header never reaches you, and the description declares no security
scheme, so the token goes on every call.
Fern was not run, because generation needs a login, a guest session, or Docker, as its
SDK commands page
says. Its
pagination extension
reads the next page from the request or the response body, and that page names no option for a
Link header. offset: $request.page is the documented form nearest GitHub’s numbered pages,
though every example there reads results from a field, where GitHub returns a bare array.
Check it worked
The tests hold the coverage table, every request each client sent, the error each one threw, the decision on both lists, and the stand-in’s statuses and body types against GitHub’s description:
node --test choose.test.mjs
1..13
# tests 13
# suites 0
# pass 13
# fail 0
# cancelled 0
# skipped 0
# todo 0
The test that carries the page asserts none for the catalog’s comment call and five named
methods for the other two clients.
When it goes wrong
The tagged release will not install. The catalog’s tag ts/v0.0.9 carries another package name
and no compiled dist/, as records/catalog.txt shows, so pin the commit you packed, not the
tag.
The dependency weight surprises the reviewer. record.sh installed each client alone:
cat records/weight.txt
installed alone into an empty folder, files under node_modules
Octokit (@octokit/rest 22.0.1) 20 packages 17310 KiB, 16639 KiB of it .d.ts
SDK Catalog github-rest-sdk 1 packages 1179 KiB, 84 KiB of it .d.ts
Swagger Codegen runtime 6 packages 546 KiB, 0 KiB of it .d.ts
plus the generated client 66 KiB of JavaScript, from the 5-operation description
plain fetch 0 packages, globalThis.fetch is a function on Node v22.23.5
Most of Octokit’s weight is type declarations, which a bundler drops. Measure your bundle, not
node_modules, before you rule it out.
A next link points elsewhere. The plain fetch loop refuses a Link URL on another origin, which
a test checks, because the token would follow it.
When not to do this
Do not score clients before the list exists. Without it, the comparison is Octokit’s 1028 methods against the catalog’s 21 operations, totals that cannot show whether your fifth call is there.
Do not adopt the catalog client when your list leans on operations outside its model. Each one
becomes a direct() call with no types, which costs what plain fetch costs inside a client you
also have to update.
Choose Swagger Codegen when you want a client for exactly your list and can patch the output it
fails to compile. Choose Fern when your team already uses it, because its paging is declared once
in the description rather than written in every adapter. Prefer Octokit when you call GitHub’s
GraphQL API as well, since @octokit/rest installs @octokit/graphql beside it.
Related how-tos
Last verified
Verified 2026-11-22 against Node 22.23.5, @octokit/rest 22.0.1, the catalog’s github-rest-sdk
at commit 04170be, and isomorphic-fetch 3.0.0. generate.sh ran Swagger Codegen 3.0.85, the
release Maven Central listed that day, on OpenJDK 21 once and committed its JavaScript. Fern was not run: its half comes from two pages of
its documentation, read that day.
- Five issues at two per page took the stand-in three pages.
Footnotes
-
GitHub’s own pagination guide illustrates the
Linkheader with repository 1300192, whose issues at two per page run to page ↩︎ Back to text -
GitHub’s reaction rollup names its thumbs-up and thumbs-down counts
+1and-1, keys that GitHub’s description publishes as they are and that no TypeScript identifier can hold. Swagger Codegen drops the sign from each, which leaves two properties called_1once an underscore goes in front of each digit, one of them counting approval and the other disapproval. ↩︎ Back to text