sdk-design

Design the caller-facing interface first, then implement a client class wrapping httpx with auth header injection, retry logic, and typed return models. Use namespaced sub-clients like client.orders for resource grouping and publish to PyPI with python -m build and twine.

Wrap cursor-based pagination in iterators or async generators so callers never manage cursors manually. The client fetches pages internally, yields each item, and stops when the API returns no next_cursor value.

Use exponential backoff with jitter for transient failures like 500, 502, 503, and 504 status codes, capping delays around 30 seconds. For 429 responses, honor the Retry-After header instead of computed backoff.

SDKs should raise typed exceptions like NotFoundError, ValidationError, and RateLimitError rather than raw HTTP errors. Typed exceptions let callers catch specific failure modes and access structured details like error codes and retry-after values.

Code generation from OpenAPI specs covers the API surface, but each language needs idiomatic customization. Sharing code across languages hurts developer experience, so maintain one SDK per language with language-native patterns.