Auto-generate or handwrite?

  • Auto-generated (openapi-generator, Speakeasy) — always in sync with the spec, covers all endpoints, zero manual effort. Output quality varies by generator and language.
  • Handwritten — better ergonomics, idiomatic for the target language, handles edge cases better. High maintenance burden.

Recommended: auto-generate as a baseline, then add an idiomatic wrapper layer on top for the most important methods.

What every SDK must include

  • Retry with exponential backoff for transient errors (429, 503).
  • Configurable timeout.
  • Clear error types — not just a generic "API error" string.
  • Request/response logging toggle (off by default, on when DEBUG env is set).
  • Idempotency key support for mutation methods.

Versioning the SDK

Publish to the language package registry (npm, PyPI, Packagist, Maven Central). Follow semver. A breaking SDK change is a MAJOR bump regardless of whether the underlying API changed.

Documentation

Every SDK needs a README with installation, authentication, and a working example in under 20 lines. The first 5 minutes of developer experience determines adoption.