How-to › Use AI to do the integration

How to port an API integration to Go with a coding agent#

Port a working TypeScript client to Go with a coding agent, tests first, then prove the port by comparing both clients' requests under a stated rule.

Audience
API consumer
Level
advanced
Topic
Write an integration with a coding agent
Languages
TypeScript, Python and Go
Verified

Your TypeScript client works, and another team needs the same calls from Go. The client carries conventions no document records: a bearer token, an x-client header, one idempotency key per write, retries that honor Retry-After, and ids escaped as one path segment. Translated line by line, its retry loop keeps a plain timer, so a cancelled Go caller still waits out the backoff.

What you get

You will end up with a Go port of a TypeScript client, its tests translated first, and a script that compares both clients’ requests on the wire under a stated rule. This is for you if you own an integration in one language and need it in another.

Short answer

Give a coding agent the TypeScript client, its tests and the OpenAPI document, and have it translate the tests to Go before the client. Name the Go idioms you expect: a context.Context on every call, http.NewRequestWithContext, and a backoff that waits on ctx.Done(). Then run both clients against one recording stand-in and compare their requests by method, path, body, and the headers your conventions set.

You will need

Node 22 with TypeScript type stripping, which runs the original .ts files as they are, and Go 1.24 or later. Verified 2026-11-22 against Node 22.23.5, Go 1.24.7, @voxgig/sdkgen 4.44.3, OpenAPI Generator 7.27.0 and @hey-api/openapi-python 0.0.24.

The port in port/ is one specimen, written in one pass by the AI coding agent that wrote this page. Its three inputs were original/client.ts, original/client.test.ts and api.json. It wrote port/client_test.go first, then port/client.go, which passed those tests on its first run. Nothing in the sample calls a model.

Approaches compared

ApproachWhen it fitsWhat it costs youWhen to pick something else
Agent port from sourceA working client whose conventions no generator knows, with tests to translateIt ports the original’s bugs too, and an idiom you do not name can come back literalThe client is mostly glue over a generated one
Hey API openapi-pythonThe target is Python and your TypeScript side already runs on Hey APINo Go generator, and release 0.0.24 wrote Python methods that take no argumentsThe target is Go, or you need a working Python client
OpenAPI Generator go with hand glueYou want idiomatic Go with a context.Context on every callYour conventions come back as glue you write and test, here an http.RoundTripperThe conventions are most of what the client does
sdkgen target add goThe TypeScript client is already sdkgen output, with retry and keys as featuresGo operations take no context.Context, and a token set in headers is droppedCallers must cancel, or the original was written by hand

Voxgig maintains sdkgen, one of the four routes measured here, and the page recommends none of them.

The agent port keeps every convention and inherits every bug, and it is only as idiomatic as the request. OpenAPI Generator writes idiomatic Go but leaves out your conventions, so the glue is yours to write. sdkgen carries retry and idempotency as features, at the cost of Go calls you cannot cancel. Hey API generates TypeScript and Python clients but not Go.

Ask for the Go idioms by name

The original’s retry loop waits on a timer its AbortSignal can end. The port’s loop waits on the context, and builds every request with it, so a cancel ends the backoff and the request in flight alike:

		retryable := res.StatusCode == 429 || res.StatusCode == 503
		if !retryable || attempt >= c.Retries {
			return &APIError{Status: res.StatusCode, Body: string(data)}
		}
		if err := c.Sleep(ctx, RetryDelay(res.Header.Get("retry-after"), attempt, c.MaxDelay)); err != nil {
			return err
		}

Two conventions needed more than a translation. encodeURIComponent escapes : and @, while Go’s url.PathEscape leaves them, so the port escapes the segment itself.1 Go’s JSON encoder writes an int of zero like any other number, so published is a pointer, and a book with no year sends no field.

Compare the requests on the wire

wire.mjs runs one scenario with each client against a fresh standin.mjs, a recording stand-in held to api.json. Unknown paths get 404, other methods 405, a write must be JSON, and every Book field is type-checked. Its one scripted fault is a 503 on the first POST.

This page did not run Prism, the mock server Stoplight publishes for OpenAPI documents. Prism’s request validation guide answers a request that breaks the document with a 422 when the operation declares no 400 or 422. Its responses come from the document’s examples and schemas, so it stores no book and scripts no 503. The stand-in checks the same parts of a request, answers with 400 instead, and keeps the state the scenario needs.

The script states its rule for the same request, and it refuses an empty original recording. Two requests match when they share the method, the path as sent with its escapes, the query, the body as a parsed JSON value, and the values of authorization, x-client and content-type. An idempotency-key is compared as a pattern: none, a new key, or the key of the request before. Every other header belongs to the HTTP library and is ignored.

node wire.mjs
original TypeScript client: 6 requests
  list: 1 book(s)
  get b1: Dune
  get a/b: error, HTTP 404
  get isbn:9780141439518: error, HTTP 404
  get ..: error, refused before sending
  create: b2 Emma

Go port: 6 requests, 0 differences, 0 outcomes differ

OpenAPI Generator go: 6 requests, 7 differences, 2 outcomes differ
  GET /v1/books: authorization missing, x-client missing
  GET /v1/books/b1: authorization missing, x-client missing
  GET /v1/books/a%2Fb: authorization missing, x-client missing
  GET /v1/books/isbn%3A9780141439518: sent as /v1/books/isbn:9780141439518, authorization missing, x-client missing
  GET /v1/books/..: not sent by the original
  POST /v1/books: authorization missing, x-client missing, idempotency-key none
  POST /v1/books: not sent
  outcome: get ..: error, HTTP 404
  outcome: create: error, HTTP 503

OpenAPI Generator go + glue: 6 requests, 1 difference, 0 outcomes differ
  GET /v1/books/isbn%3A9780141439518: sent as /v1/books/isbn:9780141439518

sdkgen go, token in headers: 6 requests, 6 differences, 0 outcomes differ
  GET /v1/books: authorization missing, content-type added
  GET /v1/books/b1: authorization missing, content-type added
  GET /v1/books/a%2Fb: authorization missing, content-type added
  GET /v1/books/isbn%3A9780141439518: authorization missing, content-type added
  POST /v1/books: authorization missing
  POST /v1/books: authorization missing

sdkgen go, token as apikey: 6 requests, 4 differences, 0 outcomes differ
  GET /v1/books: content-type added
  GET /v1/books/b1: content-type added
  GET /v1/books/a%2Fb: content-type added
  GET /v1/books/isbn%3A9780141439518: content-type added

The port sends the original’s six requests under the rule and gets its six outcomes. The stock OpenAPI Generator client sends none of the conventions, sends the .. id, and does not retry the 503. The glue in glue/glue.go closes all of that but the escaping of :, which the generated code decides with url.PathEscape.

Keep the cancellation model in the retry loop

A literal translation turns AbortSignal into a flag and its timer into a sleep followed by a check:

func sleep(ms int, signal *Signal) error {
	time.Sleep(time.Duration(ms) * time.Millisecond)
	if signal.Aborted() {
		return ErrAborted
	}
	return nil
}

cmd/cancel cancels a list call 100 ms into a one-second Retry-After backoff in four clients, and counts a return within 400 ms of the cancel as prompt.

go run ./cmd/cancel
Go port                  context.Context              returned promptly: yes requests: 1  error: context canceled
literal translation      Signal checked after sleep   returned promptly: no  requests: 1  error: aborted
OpenAPI Generator + glue context.Context              returned promptly: yes requests: 1  error: context canceled
sdkgen go target         no context parameter         returned promptly: no  requests: 3  error: other: BookshelfSDK: list: request: 503: Service Unavailable

The literal port stops only once its one-second sleep has run out. The sdkgen client has no way to receive the cancel, so it made all three attempts.

Generate the client in the target language instead

OpenAPI Generator’s go generator wrote the client in generated/oaggo, with --package-name bookshelf. Every operation takes a context.Context and builds its request with it, which is why the glue’s retry, a RoundTripper set as cfg.HTTPClient, can wait on req.Context().2

Hey API’s documentation index, its llms.txt, lists TypeScript and Python generators and no Go one. @hey-api/openapi-python 0.0.24 ran on the same document, and its methods take no parameters and pass the path template through as it is:

    def get_book(self):
        return self.client.get("/books/{bookId}")

That is release 0.0.24 of the Python generator, and it says nothing about Hey API’s TypeScript client. Hey API’s home page labels Python soon and offers early access to it, while the get-started page documents the package.

In an sdkgen project the route is npx voxgig-sdkgen target add go, then npm run generate, inside .sdk. The Go SDK carries retry and idempotency as features switched on in the constructor. Its generated REFERENCE.md describes options["headers"] as “Custom headers for all requests.” Even so, utility/prepare_auth.go deletes an authorization header unless the options hold an auth block and an apikey, and then writes the header from those two. The port sends the same header through the same net/http and it arrives, so the drop is the SDK’s own. Neither the Go README nor REFERENCE.md names apikey. @voxgig/sdkgen 4.45.0 writes the same Go files, byte for byte.

Check it worked

node --test wire.test.mjs
1..9
# tests 9
# suites 0
# pass 9
# fail 0
# cancelled 0
# skipped 0
# todo 0

The tests record every client again and assert the differences in the wire output, run the original suite and go test ./port, and run cmd/cancel. One test feeds the rule each kind of difference, and one holds the stand-in to the document with a bad escape, a wrong type and a non-JSON body.

When it goes wrong

The token never arrives from the sdkgen client. A header named authorization passed in headers is removed before the request goes out. Pass the token as apikey with an auth.prefix, and compare the wire again.

The port passes its tests and ignores a cancel. Only a test that cancels during the backoff tells the two loops apart, which is why the original suite has one and cmd/cancel runs the same check on each Go client. Add one to your suite before the translation.

A path differs by one character. url.PathEscape and encodeURIComponent escape different sets, so ids with : or @ reach the server in two spellings. The stand-in decodes both to one id, but a server that compares raw paths, to sign a request or to cache it, sees two.

When not to do this

Do not port by hand or by agent a client that is mostly generated glue. Generate the Go client from the document and port only the conventions, as glue/glue.go does for OpenAPI Generator.

Do not use the sdkgen Go target where callers need to cancel. Its operations take no context.Context, so a cancel cannot reach a retry in progress. OpenAPI Generator suits that reader better, because every call it generates takes one.

Do not take an agent port without the original suite translated first and the wire compared. One pass produced a port with no wire differences here, which is one specimen and not a rate. Hey API suits a team that regenerates its TypeScript side too, because @hey-api/openapi-ts puts conventions in client interceptors.

Last verified

Verified 2026-11-22 against Node 22.23.5, Go 1.24.7, @voxgig/create-sdkgen 0.31.9, @voxgig/sdkgen 4.44.3, @voxgig/apidef 8.32.4, OpenAPI Generator 7.27.0 on OpenJDK 21, and @hey-api/openapi-python 0.0.24 with TypeScript 5.9.3. The generators ran once, in record.sh, and their output is committed under generated/. Prism was not run. Every output block is what the command preceding it printed.

Footnotes

  1. RFC 3986 defines a path segment as a run of pchar, and pchar admits the sub-delimiters, : and @ without escaping. Go’s url.PathEscape leaves :, @, $, &, + and = as they are, and escapes !, ', (, ), *, , and ;. encodeURIComponent escapes everything outside letters, digits and -_.!~*'(), so among the sub-delimiters the two functions treat only , and ; alike. ↩︎ Back to text

  2. The idiom is older in Go than in its standard library. The Go blog post that introduced it, dated July 29, 2014, opens with Google having developed a context package to carry request-scoped values, cancellation signals and deadlines across API boundaries. The Go 1.7 release notes then move golang.org/x/net/context into the standard library as context. ↩︎ 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.