SDK Design Specification Template

Start with 2. Pick the top 2 languages from your API usage analytics. Maintaining an SDK is an ongoing commitment. Each language requires its own CI pipeline, package publishing workflow, and compatibility testing across runtime versions. It is better to have 2 excellent SDKs than 5 mediocre ones. Add languages based on developer demand after launch.

Yes, for transient errors (429, 500, 502, 503, network timeouts). No, for client errors (400, 401, 403, 404). Always respect the `Retry-After` header for [rate limit](/glossary/rate-limiting) responses. Use exponential backoff with jitter for server errors. Make retry behavior configurable so consumers can disable it if they handle retries at a higher level.

Use semantic versioning for the SDK. Pin each major SDK version to a specific API version. When the API ships a breaking change (v1 to v2), release a new major SDK version. SDK minor versions handle new API features, bug fixes, and DX improvements without changing the API version. Document the SDK-to-API version mapping in a compatibility matrix.

Hand-write the core SDKs for your top 2 languages. Auto-generated SDKs from tools like OpenAPI Generator produce functional but unidiomatic code with poor error handling and no auto-pagination. Hand-written SDKs feel native to each language. Consider auto-generation only for lower-priority languages where the maintenance cost of hand-writing is not justified. The [API-first design](/glossary/api-first-design) approach helps ensure your spec is clean enough for either path.

Follow semver strictly. Never remove a public method or change its signature in a minor release. Use deprecation warnings for at least 2 minor versions before removing anything in a major version. Provide a migration guide for every major version bump. If possible, ship the new version alongside the old one (different package name or import path) so consumers can migrate incrementally. ---