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

Source: https://voxgig.com/howto/choose-between-an-official-sdk-and-fetch

- Audience: api-consumer
- Level: beginner
- Languages: typescript
- Verified: 2026-11-22
- Published: 2026-11-22

## 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](https://github.com/github/rest-api-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](https://buildwithfern.com/learn/cli-api-reference/cli-reference/sdk-commands) | 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](https://octokit.github.io/rest.js/) | 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](https://developer.mozilla.org/en-US/docs/Web/API/Fetch_API) | 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`](https://github.com/voxgig-sdk/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](https://github.com/swagger-api/swagger-codegen/tree/3.0.0) | 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:

```json title="endpoints.json"
[
  { "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" }
]
```

```bash
cat records/description.txt
```

```text output
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.

```bash
node coverage.mjs
```

```text output
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:

```js title="clients.mjs"
    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:

```bash
node score.mjs
```

```text output
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`](https://github.com/octokit/plugin-paginate-rest.js) follows the `Link` header that
[GitHub paginates with](https://docs.github.com/en/rest/using-the-rest-api/using-pagination-in-the-rest-api).[^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:

```bash
node decide.mjs
```

```text output
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:

```bash
node decide.mjs endpoints-wider.json
```

```text output
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`:

```bash
cat records/swagger.txt
```

```text output
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](https://buildwithfern.com/learn/cli-api-reference/cli-reference/sdk-commands)
says. Its
[pagination extension](https://buildwithfern.com/learn/api-definitions/openapi/extensions/pagination)
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:

```bash
node --test choose.test.mjs
```

```text output
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:

```bash
cat records/weight.txt
```

```text output
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

- [Evaluate a third-party SDK before you depend on it](/howto/evaluate-a-third-party-sdk)

- [Judge whether an unofficial SDK is safe to depend on](/howto/judge-an-unofficial-sdk-before-adoption)

- [Bootstrap an integration from a catalog SDK with an agent](/howto/bootstrap-an-integration-from-a-catalog-sdk)

- [Check whether a vendor SDK lets you control the transport](/howto/check-transport-control-in-a-vendor-sdk)

- [Generate a client from a vendor spec you cannot edit](/howto/generate-a-client-for-a-third-party-spec)

## 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]: GitHub's own [pagination guide](https://docs.github.com/en/rest/using-the-rest-api/using-pagination-in-the-rest-api)
illustrates the `Link` header with repository 1300192, whose issues at two per page run to page
7715. Five issues at two per page took the stand-in three pages.

[^2]: GitHub's reaction rollup names its thumbs-up and thumbs-down counts `+1` and `-1`, keys that
[GitHub's description](https://github.com/github/rest-api-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.