What each approach really is
A hand-written SDK is code your team writes and maintains by hand, usually one repository per language. A generated SDK is produced by a tool from a machine-readable description of your API, most often an OpenAPI document. Open-source generators such as OpenAPI Generator and Microsoft Kiota and commercial ones such as Speakeasy all work this way; they differ in which languages they cover and how much behaviour (retries, pagination, typed errors) they build in. You can compare them side by side in the tool.
Maintenance: who does the work when the API changes
This is where the two approaches differ most, and where the cost shows up late. With a hand-written SDK, every new endpoint, field and deprecation is a change someone makes by hand, in every language, then reviews, versions and releases. When that work slips, the SDK drifts from the API and callers fall back to raw HTTP for the newest features.
With a generated SDK, the same change is an edit to the API description and a regeneration. The work moves rather than disappears: the description has to be accurate, and any custom code or templates have to survive each regeneration and each upgrade of the generator.
- Hand-written wins when the API is small and stable, or when you support a single language and have a team that already owns it.
- Generated wins when the API changes every sprint, you ship three or more languages, or you can't staff an SDK engineer per language.
Consistency: does every language behave the same way
Hand-written SDKs tend to diverge. The Python SDK retries on 429 and the Go one doesn't; the TypeScript SDK pages for you and the Java one returns a token. Each difference is a support ticket and a surprise for a team that uses two languages.
Generators apply the same rules to every operation in every language, because the behaviour comes from one description and one set of templates. The flip side is that a generator's gaps are also consistent: if it doesn't understand your pagination style, no language gets paging. Check each generator's per-language feature list rather than its headline language count.
- Hand-written wins when idiom matters more than uniformity, and each language team designs for its own community.
- Generated wins when callers use more than one language, or when you want retries, auth and errors to behave the same everywhere.
Control: can you make it do exactly what you need
Hand-written code can do anything: streaming with backpressure, request signing, long-running operations with polling, helpers that combine several calls into one. If your API has a flow that a description language can't capture, this is the strongest argument for writing it by hand.
Generators give you control through the description itself, through extensions and overlays that adjust it without editing the source, through templates, and through hooks or custom-code regions that survive regeneration. How much of that is available differs a lot between tools, so check it before you commit.
- Hand-written wins when the API's hardest parts sit outside request-and-response: streaming, signing, multi-step workflows.
- Generated wins when most of the API is ordinary CRUD and the custom parts fit in hooks or a small hand-written layer.
Side by side
| Hand-written | Generated | |
|---|---|---|
| Cost to start | High: a codebase per language | Low once the API description is accurate |
| Cost to keep | Grows with every endpoint and language | Mostly the description, plus custom code to carry forward |
| Consistency across languages | Depends on discipline | Built in, gaps included |
| Unusual flows | Anything you can write | Hooks, extensions and custom code, which vary by tool |
| Depends on | Your SDK engineers | An accurate OpenAPI description and the generator |
The hybrid: generate the core, hand-write the top
Generate the layer that maps one-to-one to the API (models, operations, auth, retries, paging) and write by hand only what adds real value on top: a helper that uploads a file in parts, a webhook verifier, a workflow that strings calls together. The generated core stays in step with the API; the hand-written layer stays small enough to keep up with.
Before you decide, answer these
- Which languages do your callers use today, and which will they ask for next year?
- Is your OpenAPI description accurate enough to generate from? If not, what would it take?
- How often does the API change, and who updates the SDKs when it does?
- Which parts of the API can't be described well: streaming, signing, long-running jobs?
- Will AI agents call the API too? If so, read SDKs when agents are the caller.
Run it on your own case
Start with Hand-written SDK vs OpenAPI Generator or No SDK vs hand-written SDK, then change the criteria and weights to match your situation in the comparison tool.