Skip to main content

API and SDK support policy

Supported production contract​

Assayra's first production integration contract is REST API v1, served below /v1 and described by OpenAPI 3.1 at /openapi/json. A release is rejected when its generated contract differs from the reviewed v1 snapshot unless the change is intentionally approved and the snapshot, changelog and any required migration guide are updated together.

The hosted bridge protocol is 1.0. The Web, iOS, Android and React Native SDKs use semantic versions. SDK availability does not make a Preview module Live-eligible; clients must read /v1/capabilities and honour the returned prerequisites and exclusions.

Compatibility rules​

Within API v1, Assayra may add optional fields, endpoints, webhook event types and extensible enum values. Assayra does not silently remove fields, make optional fields required, change an existing field's meaning, weaken an authentication rule or reuse an error code for an incompatible condition.

SDK patch releases contain compatible fixes. Minor releases may add compatible capability. A breaking SDK change requires a new major version. Applications should pin an SDK range, ignore unknown additive fields and safely ignore webhook types they do not consume.

Deprecation and support​

  • A production API or hosted-protocol breaking change receives a new version.
  • A supported SDK major receives security and critical defect fixes for at least 12 months after its successor is generally available.
  • A planned deprecation is announced in release notes and the developer changelog at least 180 days before removal, except where immediate restriction is necessary to address an active security or legal risk.
  • Security restrictions may be applied earlier; affected customers receive the reason, required action and safe migration path.
  • Every migration guide identifies affected routes/events/packages, before-and-after examples, rollout order, rollback constraints and the final support date.

Timeouts, retries and ordering​

Clients should set an explicit connection timeout and a bounded end-to-end deadline appropriate to their workflow. Only 429 and transient 5xx responses should be retried, with exponential backoff and jitter. Mutating retries must reuse the original Idempotency-Key. A final read should reconcile an unknown network outcome.

Webhook delivery is at least once, not exactly once. Verify the signature and timestamp over the raw bytes, deduplicate by event or delivery ID, persist durably, acknowledge quickly and process asynchronously. Consumers must not infer ordering across different applications; reconcile the current application state through the API before performing irreversible downstream work.

End-of-life evidence​

Each release record identifies API/hosted/SDK versions, artifact hashes, the compatibility result, unresolved deprecations and the owner approving any exception. The current public changelog is the customer-facing record; repository release notes hold the full engineering evidence.