SDK Generation — API Platform & Lifecycle

SDKs reduce integration effort and errors: typed models, auth, retries with backoff, pagination helpers, idempotency keys and error classes. Generate them from the spec with OpenAPI Generator (open source) or commercial generators (Speakeasy, Stainless, Fern) that produce idiomatic code. Treat SDKs as products: semantic versioning, changelogs, deprecation warnings, and automated releases when the spec changes.

SDK approaches

Criterion	OpenAPI Generator	Commercial generators	Hand-written SDKs
Cost	Free	Paid	Engineering time
Idiomatic output	Varies by language	High	Highest
Retries/pagination built in	Limited	Yes	Custom
Keeps up with spec	Automated	Automated	Manual (drifts)

import Acme from "@acme/sdk";

const client = new Acme({ apiKey: process.env.ACME_API_KEY, maxRetries: 2, timeout: 10_000 });

const order = await client.orders.create(
  { items: [{ sku: "MUG-01", quantity: 2 }] },
  { idempotencyKey: crypto.randomUUID() },
);
for await (const o of client.orders.list({ status: "paid" })) {   // auto-pagination
  console.log(o.id);
}

from acme import Acme, RateLimitError

client = Acme(api_key=os.environ["ACME_API_KEY"], max_retries=2, timeout=10.0)
try:
    order = client.orders.create(items=[{"sku": "MUG-01", "quantity": 2}], idempotency_key=str(uuid4()))
except RateLimitError as e:
    time.sleep(e.retry_after)
for o in client.orders.list(status="paid"):   # auto-pagination
    print(o.id)

npx @openapitools/openapi-generator-cli generate \
  -i api/openapi.yaml -g typescript-fetch -o sdks/typescript \
  --additional-properties=npmName=@acme/sdk,supportsES6=true

Common pitfalls

Generated SDKs without retries/timeouts.
Breaking SDK releases for additive API changes.
SDK and API version numbers confused.

Key points

Generate from the spec
Built-in retries, pagination, idempotency
Version SDKs independently with semver

SDK approaches

Common pitfalls

Key points

Practice questions