SDK design patterns

Centralized client

Create one client responsible for base URL, Authorization, request IDs, timeouts, and error parsing. Do not scatter fetch or cURL calls across screens. The reference generates examples in four languages, but they are implementation samples rather than a published official SDK.

Data types

Generate types from OpenAPI or define them centrally. Handle nullable fields and ignore unknown properties. Use a decimal representation or agreed minor units in your accounting system; do not rely on binary floating point for authoritative accounting even when JSON transports a decimal number.

Client middleware

Attach a request ID automatically, obtain Authorization from a credential provider, and add an idempotency key when required. Apply retry rules by method and status. Never retry a financial POST unless the idempotency key is already persisted.

Unified result

Normalize transport, HTTP, and validation failures into a clear result containing status, code, request ID, and retryability. Retain a redacted response body for diagnostics, and never log secrets or personal data.

Testing

Use an OpenAPI-derived mock server for UI tests, then contract tests against sandbox. Test an unknown added field, both status and success envelope conventions, a timeout after sending a mutation, and a successful duplicate replay. Review Errors and Idempotency.