By the Octri team · Updated
Generated vs handwritten SDKs: which should you build?
An SDK has two competing requirements. It must stay faithful to an API that keeps changing, and it must read like a library somebody designed for the language in front of them. Generators are good at the first requirement. Experienced maintainers are often needed for the second. The useful decision is where to draw the boundary.
Generated or handwritten: which should you choose?
Generate the repetitive surface when an API has many operations, several target languages or frequent schema changes. Write by hand when a small API serves one ecosystem and its interface needs behavior that a specification cannot express. For most public APIs, a generated core with carefully maintained language-specific extensions is a practical middle ground.
The greatest danger is editing generated output as if it were source. Regeneration then destroys the fix, and the team begins treating the generator as an unreliable collaborator.
Generated vs handwritten SDKs at a glance
| Decision | Generated core | Handwritten code |
|---|---|---|
| New field in the API | Rebuild from the updated spec | Update every affected client |
| New target language | Add a generator target and test suite | Design and implement another library |
| Language-specific behavior | Requires configuration or templates | Can be designed directly |
| Keeping docs aligned | Can share the source spec | Needs explicit coordination |
| Review | Inspect templates, generated diff and tests | Review each implementation |
The cost of generation includes a trustworthy spec and stable templates. The cost of hand-written code includes engineers who can keep all language implementations aligned through future releases.
How large APIs build their SDKs
Algolia's engineering account of generating more than 100 SDK packages is unusually specific. In March 2026, its team described maintaining ten APIs across eleven languages with an automated pipeline that generates clients, tests, documentation and code samples before publishing packages. The entire pipeline takes about twenty minutes, according to their post.
The more interesting detail is where the team stopped automating. They estimated roughly 80% of their client code was generated and 20% handwritten. Python's asynchronous design, Java generics and retry behavior were among the cases where the spec couldn't make the right ecosystem decision. Rather than force those details into increasingly elaborate templates, the team kept a deliberate handwritten layer. That is a more credible definition of success than promising 100% generation.
What generating an SDK produces
A generator follows the spec's operationId, parameters, schemas and responses to build method signatures, request models and result types. For an operation like POST /orders, this might result in client.orders.create({ ... }) in TypeScript and client.orders.create(...) with a Python model. It also creates the less visible plumbing: serialization, headers, response parsing, and frequently tests and documentation.
Output quality depends on input quality. A name like post_v1_orders_create_order_post produces clumsy public methods unless you correct it or configure an override. A success response with no schema forces callers to handle untyped data.
What happens when the API changes
Suppose CreateOrder gains an optional delivery_note. With a generated core, one spec change should produce a small, explainable set of changes in every language: a new field, serialization logic and possibly an example. A second generation on the same source should be identical. If the diff unexpectedly touches hundreds of unrelated files, investigate the generator's ordering, naming and formatting stability.
Handwritten code has a different failure mode. One client may gain the field while another silently lags. Both approaches need tests against the API's actual contract and a release process that treats package artifacts as first-class products.
What handwritten code is still for
Pagination iterators, polling helpers, request signing, streaming abstractions and ergonomic error hierarchies often deserve code that a maintainer wrote and reviewed. The key is to keep that code outside generator-owned files and invoke it through stable extension points. When a template can implement a behavior cleanly in every language, move it upstream into the generator; when the behavior depends on local idioms, leave it in that ecosystem.
When handwriting the whole SDK makes sense
A tiny API for a single language may be easier to maintain as a small, readable library. It may also have an unusual workflow: a streaming protocol, a stateful desktop integration or a mobile UI component that doesn't map to simple endpoints. Handwriting is attractive when the domain complexity dominates the endpoint count.
It becomes harder to justify as the number of methods and languages increases. At that point a team spends much of its time copying schemas and keeping names aligned rather than designing a good interface.
Checklist for choosing
Count operations and how often they change; identify target languages; assess spec completeness; and decide which behaviors must be idiomatic. Then regenerate after one harmless spec edit and inspect the diff. Test how errors are represented and whether custom code survives a second build. These checks expose more than a glossy demo of the generated happy path.
Generated SDKs with Octri
Octri's SDK Studio supports generation from an API spec while exposing per-language customization for method interfaces, transport, retries and hooks. The goal should be a predictable generated foundation with a controlled place for the decisions a spec cannot make.
How to customize a generated SDK shows how to keep those changes through regeneration.