How-to › Operate integrations in production

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.

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

Read first: Choose between an official SDK, a generated SDK and fetch

You run npm install @voxgig-sdk/jsonplaceholder-sdk and npm answers 404, and pip install fails the same way. The repository README lists SDKs for TypeScript, Python, PHP, Go, Ruby, and Lua, so you try Go. go get ...@latest installs a client whose Post list call returns zero records from an API that holds a hundred.

What you get

You will end up with the catalog’s JSONPlaceholder client installed in Go, TypeScript, and Python by routes that resolve. A first call runs offline, and one list is compared across the SDK and the REPL. This is for you if you want a ready client for a public API and can live with an unofficial one.

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, a fake REST service that needs no key, and the client is the catalog’s 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

ApproachWhen it fitsWhat it costs youWhen to pick something else
KiotaYou write or trust an OpenAPI document and want a typed client you regenerateA runtime bundle to install, and the document is yours to keep currentA maintained client already exists for the API
OctokitThe API is GitHub, and you want what its README calls the all-batteries-included GitHub SDKIt covers GitHub alone, so every other API needs its own clientThe API you call is not GitHub
OpenAPI GeneratorYou need a language or a library style the catalog lacksYou generate, package, and upgrade the client yourself, per languageA pinned generated client already covers your language
plain fetchTwo or three endpoints, one language, and nothing to upgradeTypes, retries, and a test double are yours to write and keepYou call many endpoints or several languages
SDK Catalog packageA public API in the catalog, in Go, or by a source route elsewhereAn unofficial build; this one is published for Go only, with tags behind its main branchThe 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 lets go get resolve from a commit:

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 in ts/, and commits the tarball with the repository’s MIT license file beside it:

  "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, 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:

node offline.mjs
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:

node same-list.mjs
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:

node --test catalog.test.mjs
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 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:

cat records/live.txt
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.

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.

Footnotes

  1. The quick start’s document is small by design: it describes /posts and /posts/{post-id} and nothing else, and the page 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. ↩︎ 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.