SDK Design Principles

SDKs should feel boring in the best way. Behavior should be predictable across languages. Defaults should be safe for production.

API parity is non-negotiable

SDKs are a typed, ergonomic wrapper over the REST surface.

• No hidden endpoints.

• No extra "magic" parameters.

• No undocumented default behavior.

When the API adds new capabilities, SDKs surface them via versioned releases. This keeps upgrades explicit and reviewable.

What parity means in practice

• Endpoint availability matches the REST API.

• Request and response fields keep the same meaning.

• Optional fields stay optional. Missing fields are handled safely.

• Client-side helpers never change server semantics.

Structured error handling

SDKs map API error responses into language-native error types. This enables reliable branching without parsing raw HTTP.

Expose enough context for debugging:

• HTTP status.

• Stable error code.

• Human-readable message.

• Optional details payload.

• Request identifier, when provided by the API.

Retry behavior stays conservative

SDKs only retry when it's safe by default.

• Transient network failures can be retried.

• Throttling responses can be retried, typically respecting Retry-After.

• Server errors can be retried when the request is idempotent.

If an operation is not idempotent, retries can duplicate side effects. SDKs should make this risk visible via configuration.

Configuration and extensibility

SDKs expose the same core knobs across languages. Names can differ. Semantics should not.

Core configuration should include:

• API key and auth strategy.

• Base URL / API host (prod vs staging).

• Timeouts (connect and total).

• Retry policy (attempts, backoff, jitter).

• Default headers (user-agent, tracing, request correlation).

• Optional logging hooks.

Extensibility points

Advanced users should be able to override defaults without forking:

• Plug in a custom HTTP transport.

• Add middleware / interceptors for headers and tracing.

• Customize serialization and response decoding when needed.

Community extensions

Acceso supports community-maintained SDKs and extensions.

Community SDKs can be reviewed for correctness. They are not officially maintained. Consumers should treat compatibility and support as best-effort.