SDK generation guides
Answers to the questions teams ask before and after they generate client libraries from an OpenAPI spec.
SDK basics
What an SDK is, what it does for the developers who call your API, and how it differs from the API itself.
What is an SDK? Meaning, parts and examples
What an API SDK contains, how it differs from platform toolkits, and why naming, types and errors determine whether the library is useful.
Start here6 min readSDK vs API: the difference, with code examples
Compare direct API calls and SDK calls with the same paginated task, showing where authentication, cursor handling and error logic live.
5 min readWhat is a client library? Meaning, examples and what's inside
Understand what an API client library does, how official and generated packages differ, and which behaviors callers should inspect.
5 min readWhy build an SDK for your API? Benefits and costs
Why official SDKs reduce repeated integration work, what they cost to maintain, and what Xero learned from relying on community libraries.
5 min readWhich languages should your SDK support? How to choose
Choose SDK languages using API traffic, audience needs and real maintenance capacity, with a lesson from GitHub’s 2026 language data.
5 min read
Build an SDK
Writing an SDK by hand, generating one from an OpenAPI spec, and testing either before release.
How to build an SDK: a step-by-step guide with code
Design and build a TypeScript API SDK with a shared transport, safe retries, typed errors and pagination, including a repeatable retry test.
6 min readHow to generate an SDK from OpenAPI: a step-by-step guide
Generate useful client libraries from OpenAPI by improving operation names and schemas, then testing and publishing reproducible packages.
5 min readGenerated vs handwritten SDKs: which should you build?
Choose between generated, handwritten and hybrid SDKs using Algolia’s experience maintaining over 100 packages.
5 min readHow to customize a generated SDK: overlays, hooks and wrappers
Customize a generated SDK through OpenAPI fixes, overlays, generator settings, request hooks and wrappers without patching generated files.
5 min readWhat is an idempotency key? How it works, with examples
Learn how idempotency keys protect retried API writes, including Stripe’s engineering rationale, replay rules and server requirements.
5 min readSDK error handling: how to design errors developers can use
Design SDK errors that preserve response status, request IDs, problem details and retry guidance while distinguishing network failures.
5 min readHow to test an SDK: unit, contract and release tests
Test SDK request construction, errors, pagination, contracts, docs examples and built packages, with an HTTPX mocked-transport exercise.
5 min readhttpx vs requests vs aiohttp: which Python HTTP client to use
Compare requests, HTTPX and aiohttp for Python SDK development using async support, timeout behavior and a local call through all three.
5 min read
Publish an SDK
Getting packages onto npm and the other registries, and releasing new versions safely.
How to publish an npm package: a step-by-step guide
Publish an npm SDK safely: inspect the tarball, release a version, and use trusted or staged CI publishing, including npm’s 2026 changes.
5 min readHow to publish a Python package to PyPI: a step-by-step guide
Prepare and publish a Python SDK to PyPI with pyproject.toml, a clean wheel test, TestPyPI and trusted CI publication.
5 min read
Maintain an SDK
Keeping SDKs, their docs and their versions in step as the API changes.
How to maintain an SDK: releases, runtimes and support
Keep SDKs current through coordinated API releases, runtime tests, dependency updates and support policies, informed by Stripe’s experience.
5 min readHow to keep SDKs and API docs in sync
Prevent SDK and documentation drift by sharing an OpenAPI contract, generating real code samples, and coordinating package releases.
5 min read
Try it on your own spec
Generate type-safe SDKs in ten languages from your OpenAPI spec, keep your custom code, and publish to npm, PyPI and Maven.