Versioning and deprecation
Plan SDK upgrades and API migrations.
The API serves the currently deployed service. SDK package versions select client code; they do not select a historical API response. OpenAPI's version describes the API document. Direct HTTP requests use the same deployed service.
Plan an upgrade
| Change | Release and migration |
|---|---|
| Compatible addition | An SDK feature uses a minor release. Existing response readers must remain compatible |
| Breaking change before SDK 1.0 | An SDK minor release marked BREAKING (0.x minor) includes migration steps |
| Breaking change after SDK 1.0 | An SDK major release includes migration steps |
Read the migration guidance and minimum supported SDK version before upgrading. Keep the supported version in your application's dependency settings and verify the affected requests. Direct HTTP consumers follow the published request and response migration examples.
Notice and deprecation
Once the service has a paid workspace, breaking API changes have at least 30 calendar days of notice and migration time. The period starts when both the consumer notice and usable replacement are available, including a compatible SDK release when required. Longer feature-specific commitments continue to apply.
Before paid workspaces, the pre-1.0 breaking-release convention and existing feature-specific migration periods apply. The terms' advance notice for significant service changes continues to apply. Security and emergency changes follow the applicable terms.
The seven SDK deprecations below have an earliest planned removal target of 1.0.0. Migrate using the listed replacements and imports. Actual removal requires a separate compatibility change and the applicable notice and migration period. If prerequisites remain unmet, the target is postponed and notice is updated. Recheck paid-workspace status at removal; a target set before the first paid workspace still follows the 30-day floor once one exists. Moving a target earlier requires fresh compliant notice.
| Deprecated surface | Replacement and migration | Earliest target |
|---|---|---|
ProductMediaResolutionSource | From @01.software/sdk, import ProductSelectionMediaSource for selection results or ProductDisplayMediaSource for display fallback results. Use their union when storing both. | 1.0.0 |
Comment | Import CommunityComment from @01.software/sdk and rename type references; the shape stays the same. | 1.0.0 |
community.addReaction({ type }) | On the client created with createClient from @01.software/sdk, rename type to typeSlug, keeping the same slug value. | 1.0.0 |
community.addCommentReaction({ type }) | On the same client, rename type to typeSlug, keeping the same slug value. | 1.0.0 |
customer.auth.logout() | On the same client, await customer.auth.logoutAsync() and handle rejection. It clears local credentials even on server revocation failure. A legacy access-only session has no refresh family to revoke. | 1.0.0 |
WebhookOptions | Import SignedWebhookOptions from @01.software/sdk/webhook; keep the required nonblank secret and optional toleranceSeconds. | 1.0.0 |
handleWebhook() | Import handleSignedWebhook from @01.software/sdk/webhook; pass the same request, handler and signed options. | 1.0.0 |
The synchronous logout method clears local credentials only. The asynchronous
replacement also revokes the current direct refresh family. The signed webhook
replacement preserves raw-body verification and the exact signing secret bytes.
Both legacy webhook names remain available at the root and webhook entry;
explicit signed receivers use the webhook entry. Keep the type input on
removeReaction and removeCommentReaction unchanged.
Migration guidance and notices carry the support floor and cutover schedule.
The API currently provides this lifecycle through those notices rather than
Deprecation or Sunset response headers.
Response compatibility
Use task-specific SDK helpers first. Some helpers validate the complete response and reject undeclared fields. An optional property in a newer SDK's types can therefore require a migration for an older SDK.
Where a feature documents an exact Accept media type, send that value to
request its additional representation. Other requests retain the feature's
default response. Follow each feature's rollout guidance for default response
changes. SDK 1.0 keeps the existing response validation boundaries.
Next Actions
Continue with the SDK guide, HTTP API guide, or webhook guide for the affected integration.