How-to › Operate integrations in production

How to choose between an official SDK, a generated SDK and fetch#

List the GitHub operations you call, then score Octokit, an SDK Catalog client, a Swagger Codegen client and plain fetch on coverage, paging, errors, and weight.

Audience
API consumer
Level
beginner
Topic
Evaluate, adopt and upgrade SDKs
Languages
TypeScript
Verified

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

ApproachWhen it fitsWhat it costs youWhen to pick something else
FernYou want a generated client whose paging is declared once in the descriptionA login, a guest session on Fern’s servers, or Docker for local runsYou need no account and nothing to configure
OctokitYou call GitHub and want GitHub’s own clientTwenty packages and 17310 KiB on disk, nearly all type declarationsBundle size matters and you call a handful of routes
plain fetchA few calls, and nothing to upgradeYou write paging, errors, escaping and auth yourself, and test themThe calls grow past what you want to maintain
SDK Catalog github-rest-sdkYour calls are inside its 21 operationsNot on npm, so you pack a clone; unofficial, and a call outside its model needs direct()Your list includes calls its model lacks
Swagger CodegenYou want a client for exactly the operations you listThe output fails tsc on this description, drops response headers, and needs isomorphic-fetchYou 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.

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.

  1. Five issues at two per page took the stand-in three pages.

Footnotes

  1. GitHub’s own pagination guide illustrates the Link header with repository 1300192, whose issues at two per page run to page ↩︎ Back to text

  2. GitHub’s reaction rollup names its thumbs-up and thumbs-down counts +1 and -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 _1 once an underscore goes in front of each digit, one of them counting approval and the other disapproval. ↩︎ 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.