# How to install an SDK Catalog package for a public API

> Install the SDK Catalog JSONPlaceholder client in Go, TypeScript, and Python by routes that work, call it offline, and compare one list in the SDK and the REPL.

Source: https://voxgig.com/howto/install-a-catalog-sdk-for-a-public-api

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

## Short answer

Pin the catalog's Go module at a pseudo-version of its main branch, because this SDK is on no registry but Go's and its @latest tag is stale. For TypeScript, pack the repository's ts/ folder and install the tarball; for Python, pip install from git at the same commit. Make the first call in each SDK's test mode, then run one list through the SDK and the Go CLI's REPL and compare the posts.

---
## You will need

Node 22 or later, Go 1.24.7 or later, and Python 3.12 or later for the pip route. The API is
[JSONPlaceholder](https://jsonplaceholder.typicode.com/#guide), a fake REST service that needs no
key, and the client is the
[catalog's JSONPlaceholder SDK](https://voxgig.com/voxgig-sdk/jsonplaceholder-sdk). Every call on
this page goes to the SDK's test mode or to a stand-in on 127.0.0.1; `record.sh` made the live calls
once.

## Approaches compared

| Approach | When it fits | What it costs you | When to pick something else |
| --- | --- | --- | --- |
| [Kiota](https://learn.microsoft.com/en-us/openapi/kiota/quickstarts/typescript) | You write or trust an OpenAPI document and want a typed client you regenerate | A runtime bundle to install, and the document is yours to keep current | A maintained client already exists for the API |
| [Octokit](https://github.com/octokit/octokit.js) | The API is GitHub, and you want what its README calls the all-batteries-included GitHub SDK | It covers GitHub alone, so every other API needs its own client | The API you call is not GitHub |
| [OpenAPI Generator](https://openapi-generator.tech/docs/generators/python/) | You need a language or a library style the catalog lacks | You generate, package, and upgrade the client yourself, per language | A pinned generated client already covers your language |
| [plain fetch](https://developer.mozilla.org/en-US/docs/Web/API/Window/fetch) | Two or three endpoints, one language, and nothing to upgrade | Types, retries, and a test double are yours to write and keep | You call many endpoints or several languages |
| [SDK Catalog package](https://github.com/voxgig-sdk/jsonplaceholder-sdk/blob/a21ce5a97d8ed4c85e02123b61a67a3a408d60a9/README.md) | A public API in the catalog, in Go, or by a source route elsewhere | An unofficial build; this one is published for Go only, with tags behind its main branch | The vendor ships an SDK, or you need registry installs |

Voxgig maintains the SDK Catalog, the subject of this page; Kiota, Octokit, OpenAPI Generator, and
fetch are other projects.

An official SDK, where a vendor ships one, brings support and the vendor's own error types. Plain fetch gives you nothing to upgrade. Kiota and OpenAPI Generator leave the
document and the build to you, where the catalog runs both on its own schedule.

## Pin the module, the tarball, and the git ref

The proxy's `@latest` for the Go module is the `v0.0.7` tag, and that build lists no posts live. Pin the main branch's pseudo-version instead, which [the module
reference](https://go.dev/ref/mod) lets `go get` resolve from a commit:

```text title="go/go.mod"
module example.com/jpfirst

go 1.24.7

require github.com/voxgig-sdk/jsonplaceholder-sdk/go v0.0.8-0.20261103055737-a21ce5a97d8e
```

The same `go.mod` holds the CLI as a `tool`, at the same pseudo-version. For TypeScript, `generate.sh`
clones the repository at that commit, runs [`npm pack`](https://docs.npmjs.com/cli/v10/commands/npm-pack/)
in `ts/`, and commits the tarball with the repository's MIT license file beside it:

```json title="package.json"
  "dependencies": {
    "@voxgig-sdk/jsonplaceholder-sdk": "file:tarballs/voxgig-sdk-jsonplaceholder-sdk-0.0.1-a21ce5a.tar.gz"
  }
```

`npm ci` then installs it with no registry. For Python, `record.sh` used
[pip's git support](https://pip.pypa.io/en/stable/topics/vcs-support/),
`git+https://github.com/voxgig-sdk/jsonplaceholder-sdk.git@a21ce5a97d8ed4c85e02123b61a67a3a408d60a9#subdirectory=py`.
The gate runs the TypeScript and Go commands below; the Python route ran in `record.sh` only.

## Make the first call offline

Each SDK has a test mode with an in-memory transport. Seed it with two posts and call `list` and
`load`:

```bash
node offline.mjs
```

```text output
TypeScript, JsonplaceholderSDK.test(...)
  {"call":"Post.List","count":2,"posts":[{"id":"p1","title":"seeded one"},{"id":"p2","title":"seeded two"}]}
  {"call":"Post.Load","id":"p1","title":"seeded one"}
Go, sdk.TestSDK(...)
  {"call":"Post.List","count":2,"posts":[{"id":"p1","title":"seeded one"},{"id":"p2","title":"seeded two"}]}
  {"call":"Post.Load","id":"p1","title":"seeded one"}
same output from both: true
```

`offline.mjs` builds the Go program with a `GOPATH` and a `GOCACHE` of its own, under the temp
folder. The operation names match across languages, `Post().list()` and `Post(nil).List()`.

## Compare one list through the SDK and the REPL

The repository also holds `go-cli/`, `go-mcp/`, and SDKs in `php/`, `rb/`, and `lua/`. The CLI with
no arguments is a REPL. `same-list.mjs` starts a stand-in on 127.0.0.1, gives all three surfaces the
key `k-test-0001`, and compares the posts each one returns:

```bash
node same-list.mjs
```

```text output
stand-in on 127.0.0.1 with 3 posts
  TypeScript SDK  Post().list()     3 posts, ids 1 2 3
  Go SDK          Post(nil).List()  3 posts, ids 1 2 3
  Go CLI REPL     list post         3 posts, ids 1 2 3
  same ids and titles in all three, and as served: true
requests the stand-in saw: 5, GET /posts, GET /posts/1
credential on the wire, key given to all three: authorization: <key>
```

JSONPlaceholder needs no key, so the first authenticated call is a key the API ignores. Each
surface still sent it as `Authorization`, with no prefix. The generated `prepare_auth.go` drops the
header only when the options carry no `auth` block, and the options schema fills one in. Do not
pass a key to an API that declares none: given no key, the three surfaces sent no header. The REPL prints `boru` notation with keys in
varying order, so the script reads `id` and `title` out of each record.

## Check it worked

Run the suite:

```bash
node --test catalog.test.mjs
```

```text output
1..8
# tests 8
# suites 0
# pass 8
# fail 0
# cancelled 0
# skipped 0
# todo 0
```

It holds the stand-in to the live service's recorded field names and its `404 {}` for a missing
post, and the records of the registries and the live calls to what the page says. It also checks
that a client given no key sends no `Authorization` header.

## Generate the client yourself with Kiota or OpenAPI Generator

A team on OpenAPI Generator builds the same client from an OpenAPI document. The catalog
repository keeps its own, `.sdk/def/jsonplaceholder_0.1.0.json`, and `record.sh` ran OpenAPI
Generator's `python` generator on it once. It wrote one class per tag, and `PostsApi.get_posts()`
returned 100 posts live. The client is yours to package and pin.

Kiota's [TypeScript quick start](https://learn.microsoft.com/en-us/openapi/kiota/quickstarts/typescript)
uses this API: a short `posts-api.yml`, `kiota generate -l typescript`, the
`@microsoft/kiota-bundle` runtime, and an anonymous authentication provider, because
JSONPlaceholder requires none. Kiota was not run for this page, so its route is from that page.[^1]

## When it goes wrong

`go get` gives a client whose list returns nothing. You took the `@latest` tag:

```bash
cat records/live.txt
```

```text output
pinned v0.0.8-0.20261103055737-a21ce5a97d8e:
  Post.List count 100
  Post.Load id 1
@latest v0.0.7:
  live Post.List count: 0
  against the stand-in: exit 1, requests GET /users/%7Buser_id%7D/posts
GET /users/%7Buser_id%7D/posts: 200 []
GET /posts/1 field names: body id title userId
GET /posts/9999: 404 {}
GET /posts?userId=1 count: 10
```

The `v0.0.7` build asks for `/users/%7Buser_id%7D/posts`, a path with its parameter unfilled,
and the live service answers that with `200 []`. The Python tag `py/v0.0.7` returned 0 too, and
main lists all hundred. Pin the commit, and
read its date and the generator versions from the commit message, which here says sdkgen 4.38.0 and
apidef 8.27.0.

A title with an apostrophe breaks a script that reads the REPL. `boru` notation prints `'it's ...'`
with the inner quote left as it is, and a newline in a body as a line break, so read values up to
the next key, or use the SDK.

A clean checkout has no tarball to install when a `.gitignore` rule such as `*.tgz` dropped it, as
this site's does. Ask `git check-ignore -v` about the file, commit the lockfile, and rename the
tarball if a rule matches.

## When not to do this

Do not adopt an SDK Catalog package where the vendor ships a supported SDK. The catalog regenerates
on its own schedule, and its package files say 0.0.1 while its Go tags reach v0.0.7.

Do not depend on `@latest` for a catalog module. Pin a commit you have run, and check its date
before an upgrade.

Generate with OpenAPI Generator when you need a language or library style the catalog does not
ship, or when you must own the document the client comes from. Kiota is the better choice when
your team writes the OpenAPI document itself and wants one regenerate command per language.

## Related how-tos

- [Choose between an official SDK, a generated SDK and fetch](/howto/choose-between-an-official-sdk-and-fetch)

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

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

- [Let an agent drive a CLI instead of tool schemas](/howto/let-an-agent-drive-a-generated-cli)

- [Call an endpoint your SDK does not model with direct()](/howto/call-an-unmodelled-endpoint-with-direct)

## Last verified

Verified 2026-11-22 against Node 22.23.5, Go 1.24.7 and the catalog's JSONPlaceholder SDK at commit
`a21ce5a`, Go module `v0.0.8-0.20261103055737-a21ce5a97d8e`. Every output block is what the command
before it printed. The registry checks, the live calls, the Python installs on Python 3.13, and
OpenAPI Generator 7.27.0 ran once in `record.sh`. Kiota was read from its documentation and not run.

[^1]: The quick start's document is small by design: it describes `/posts` and `/posts/{post-id}`
and nothing else, and [the page](https://learn.microsoft.com/en-us/openapi/kiota/quickstarts/typescript)
calls it a minimal OpenAPI description of how to call the `/posts` endpoint. The catalog's client comes from a
longer description of the same fake service, kept in the catalog's repository, so the two clients
come from two documents, one kept by each project.