designing-sdks_skill

Overview

This skill teaches how to design production-ready SDKs with clean APIs, robust error handling, retries, pagination, streaming, and multi-language support. It focuses on developer experience, consistent patterns across languages, and practical defaults for authentication, versioning, and configuration. Use it to produce client libraries that are reliable, easy to use, and maintainable.

How this skill works

The approach organizes SDKs around a Client → Resources → Methods hierarchy or a Command-based model for very large APIs. It includes language-specific patterns (TypeScript async-only, Python dual sync/async, Go with context), typed error hierarchies, retry/backoff strategies with jitter and rate-limit handling, async iterators for pagination, streaming primitives, and idempotency keys. Configuration and sensible defaults are provided for API keys, timeouts, retries, and version pinning.

When to use it

• Building a client library for a REST or HTTP API intended for external developers.
• Implementing retry and exponential backoff for transient network or server errors.
• Creating SDKs that must support pagination, streaming, or long-running requests.
• Designing multi-language client libraries (TypeScript, Python, Go) with consistent behavior.
• Adding authentication flows: API keys, OAuth refresh, or per-request bearer tokens.

Best practices

• Prefer resource-based organization for small-to-medium APIs and command-based for very large ones to optimize bundle size.
• Implement exponential backoff with jitter, respect Retry-After for 429, and cap max retries (3–5).
• Provide typed error classes with status, code, and requestId; surface request IDs in all error messages.
• Offer async iterators for automatic pagination and also expose manual pagination options.
• Support idempotency keys for unsafe retries and provide sensible client config defaults (apiKey, timeout, maxRetries).

Example use cases

• A Stripe-style SDK for a payments API with resource objects and convenience top-level methods.
• An enterprise internal SDK that refreshes OAuth tokens automatically and exposes onTokenRefresh hooks.
• A client library that streams AI model outputs via server-sent events or chunked responses.
• A Python package supplying both sync and async clients for web frameworks and background workers.
• A Go SDK that passes context.Context for cancellation, timeouts, and tracing integration.