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

Source: https://voxgig.com/howto/port-an-integration-with-a-coding-agent

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

## 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](https://nodejs.org/api/typescript.html), 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

| Approach | When it fits | What it costs you | When to pick something else |
| --- | --- | --- | --- |
| [Agent port from source](https://go.dev/blog/context) | A working client whose conventions no generator knows, with tests to translate | It ports the original's bugs too, and an idiom you do not name can come back literal | The client is mostly glue over a generated one |
| [Hey API `openapi-python`](https://heyapi.dev/docs/openapi/python/get-started) | The target is Python and your TypeScript side already runs on Hey API | No Go generator, and release 0.0.24 wrote Python methods that take no arguments | The target is Go, or you need a working Python client |
| [OpenAPI Generator go with hand glue](https://openapi-generator.tech/docs/generators/go/) | You want idiomatic Go with a `context.Context` on every call | Your conventions come back as glue you write and test, here an `http.RoundTripper` | The conventions are most of what the client does |
| [sdkgen target add go](https://github.com/voxgig/sdkgen/blob/main/docs/how-to/add-a-target.md) | The TypeScript client is already sdkgen output, with retry and keys as features | Go operations take no `context.Context`, and a token set in `headers` is dropped | Callers 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:

```go title="port/client.go"
		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`](https://pkg.go.dev/net/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](https://github.com/stoplightio/prism/blob/master/docs/guides/02-request-validation.md)
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.

```bash
node wire.mjs
```

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

```go title="literal/client.go"
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.

```bash
go run ./cmd/cancel
```

```text output
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`](https://heyapi.dev/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:

```python title="generated/heyapi-python/sdk_gen.py"
    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](https://heyapi.dev/) 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

```bash
node --test wire.test.mjs
```

```text output
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](https://heyapi.dev/docs/openapi/typescript/clients/fetch#interceptors).

## Related how-tos

- [Compare an AI-written API client with generated clients](/howto/compare-an-ai-written-client-with-generator-output)

- [Let a coding agent customize a generated SDK safely](/howto/customise-a-generated-sdk-with-an-agent-safely)

- [Measure drift between two AI-written clients](/howto/measure-drift-between-two-ai-written-clients)

- [Generate your first SDK with sdkgen](/howto/first-sdk-with-sdkgen)

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

[^1]: [RFC 3986](https://www.rfc-editor.org/rfc/rfc3986.html#section-3.3) 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`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/encodeURIComponent)
escapes everything outside letters, digits and `-_.!~*'()`, so among the sub-delimiters the two
functions treat only `,` and `;` alike.

[^2]: The idiom is older in Go than in its standard library. The [Go blog
post](https://go.dev/blog/context) 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](https://go.dev/doc/go1.7) then move
`golang.org/x/net/context` into the standard library as `context`.