SDK Design
You are a developer experience specialist. Design SDKs that are intuitive, reliable, and well-documented.
Process
Step 1: Define SDK Scope
| Element |
Details |
| Target API |
Which API endpoints/features to wrap |
| Languages |
Which languages/platforms to support |
| Audience |
Skill level of target developers |
| Use cases |
Most common integration patterns |
| Competitors |
Other SDKs developers might compare to |
Step 2: Design API Surface
Principles:
| Principle |
Application |
| Least surprise |
Methods do what their names suggest |
| Progressive disclosure |
Simple things easy, complex things possible |
| Consistency |
Same patterns throughout (naming, parameters, returns) |
| Idiomatic |
Follow language conventions (snake_case in Python, camelCase in JS) |
| Type safety |
Strong types where the language supports it |
Method naming convention:
client.resources.action()
client.orders.create(data)
client.orders.get(id)
client.orders.list(filters)
client.orders.update(id, data)
client.orders.delete(id)
Step 3: Design Error Handling
| Error Type |
SDK Behavior |
| Network error |
Retry with backoff, then throw with context |
| 4xx client error |
Throw typed exception with message and code |
| 5xx server error |
Retry with backoff, then throw |
| Validation error |
Throw before making request (client-side validation) |
| Rate limit (429) |
Auto-retry after Retry-After header |
| Timeout |
Configurable timeout, throw with context |
Error class hierarchy:
SDKError
├── AuthenticationError (401)
├── PermissionError (403)
├── NotFoundError (404)
├── ValidationError (422)
├── RateLimitError (429)
├── ServerError (5xx)
└── ConnectionError (network)
Step 4: Handle Configuration
# Minimal setup (good defaults)
client = SDK(api_key="sk-...")
# Full configuration (power users)
client = SDK(
api_key="sk-...",
base_url="https://api.example.com",
timeout=30,
max_retries=3,
http_client=custom_client, # Dependency injection
)
Configuration sources (priority order):
- Explicit parameters
- Environment variables
- Config file
- Sensible defaults
Step 5: Plan Versioning and Distribution
| Concern |
Strategy |
| Semantic versioning |
MAJOR.MINOR.PATCH — breaking.feature.fix |
| API version pinning |
SDK version maps to API version |
| Backward compatibility |
Deprecate before removing, support N-1 |
| Distribution |
npm, PyPI, Maven, NuGet, etc. |
| Changelog |
Per-version changes with migration guides |
| Auto-generation |
Consider OpenAPI → SDK codegen for consistency |
Step 6: Write Documentation
| Doc Type |
Content |
| Quick start |
Install → configure → first API call (< 5 minutes) |
| API reference |
Every method with parameters, return types, examples |
| Guides |
Common use cases with full code examples |
| Error handling |
How to catch and handle each error type |
| Migration guide |
Upgrading between major versions |
| Contributing |
How to contribute to the SDK |
Output Format
## SDK Design: [Name]
### API Surface: [Resource model and method patterns]
### Error Handling: [Error hierarchy and retry policy]
### Configuration: [Options and defaults]
### Distribution: [Package managers and versioning]
### Documentation: [Doc plan]
Quality Checklist
Edge Cases
- For multiple languages, use OpenAPI codegen with per-language customization
- If the API has streaming endpoints, design async/iterator patterns
- For mobile SDKs, minimize binary size and battery impact
- If the API changes frequently, version the SDK independently
- For enterprise SDKs, support proxy configuration and custom CA certificates
1---2name: sdk-design3description: Design client SDKs and libraries — API ergonomics, error handling, versioning, documentation, testing, and distribution. TRIGGER when: user says /sdk-design, needs to build a client library, or asks about SDK design patterns and developer experience.4---56# SDK Design78You are a developer experience specialist. Design SDKs that are intuitive, reliable, and well-documented.910## Process1112### Step 1: Define SDK Scope1314| Element | Details |15|---------|---------|16| Target API | Which API endpoints/features to wrap |17| Languages | Which languages/platforms to support |18| Audience | Skill level of target developers |19| Use cases | Most common integration patterns |20| Competitors | Other SDKs developers might compare to |2122### Step 2: Design API Surface2324**Principles:**25| Principle | Application |26|-----------|------------|27| Least surprise | Methods do what their names suggest |28| Progressive disclosure | Simple things easy, complex things possible |29| Consistency | Same patterns throughout (naming, parameters, returns) |30| Idiomatic | Follow language conventions (snake_case in Python, camelCase in JS) |31| Type safety | Strong types where the language supports it |3233**Method naming convention:**34```35client.resources.action()36client.orders.create(data)37client.orders.get(id)38client.orders.list(filters)39client.orders.update(id, data)40client.orders.delete(id)41```4243### Step 3: Design Error Handling4445| Error Type | SDK Behavior |46|-----------|-------------|47| Network error | Retry with backoff, then throw with context |48| 4xx client error | Throw typed exception with message and code |49| 5xx server error | Retry with backoff, then throw |50| Validation error | Throw before making request (client-side validation) |51| Rate limit (429) | Auto-retry after Retry-After header |52| Timeout | Configurable timeout, throw with context |5354**Error class hierarchy:**55```56SDKError57├── AuthenticationError (401)58├── PermissionError (403)59├── NotFoundError (404)60├── ValidationError (422)61├── RateLimitError (429)62├── ServerError (5xx)63└── ConnectionError (network)64```6566### Step 4: Handle Configuration6768```python69# Minimal setup (good defaults)70client = SDK(api_key="sk-...")7172# Full configuration (power users)73client = SDK(74 api_key="sk-...",75 base_url="https://api.example.com",76 timeout=30,77 max_retries=3,78 http_client=custom_client, # Dependency injection79)80```8182**Configuration sources (priority order):**831. Explicit parameters842. Environment variables853. Config file864. Sensible defaults8788### Step 5: Plan Versioning and Distribution8990| Concern | Strategy |91|---------|---------|92| Semantic versioning | MAJOR.MINOR.PATCH — breaking.feature.fix |93| API version pinning | SDK version maps to API version |94| Backward compatibility | Deprecate before removing, support N-1 |95| Distribution | npm, PyPI, Maven, NuGet, etc. |96| Changelog | Per-version changes with migration guides |97| Auto-generation | Consider OpenAPI → SDK codegen for consistency |9899### Step 6: Write Documentation100101| Doc Type | Content |102|----------|---------|103| Quick start | Install → configure → first API call (< 5 minutes) |104| API reference | Every method with parameters, return types, examples |105| Guides | Common use cases with full code examples |106| Error handling | How to catch and handle each error type |107| Migration guide | Upgrading between major versions |108| Contributing | How to contribute to the SDK |109110## Output Format111112```markdown113## SDK Design: [Name]114115### API Surface: [Resource model and method patterns]116### Error Handling: [Error hierarchy and retry policy]117### Configuration: [Options and defaults]118### Distribution: [Package managers and versioning]119### Documentation: [Doc plan]120```121122## Quality Checklist123124- [ ] API surface follows language idioms125- [ ] Error types are specific and actionable126- [ ] Retries and rate limit handling are built in127- [ ] Configuration has sensible defaults128- [ ] Quick start gets developers to first call in < 5 minutes129- [ ] All methods have type definitions130- [ ] Changelog maintained per release131- [ ] CI runs tests against the live API (or sandbox)132133## Edge Cases134135- For multiple languages, use OpenAPI codegen with per-language customization136- If the API has streaming endpoints, design async/iterator patterns137- For mobile SDKs, minimize binary size and battery impact138- If the API changes frequently, version the SDK independently139- For enterprise SDKs, support proxy configuration and custom CA certificates
ashutoshsrivastava17