01.software Docs

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

ChangeRelease and migration
Compatible additionAn SDK feature uses a minor release. Existing response readers must remain compatible
Breaking change before SDK 1.0An SDK minor release marked BREAKING (0.x minor) includes migration steps
Breaking change after SDK 1.0An 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 surfaceReplacement and migrationEarliest target
ProductMediaResolutionSourceFrom @01.software/sdk, import ProductSelectionMediaSource for selection results or ProductDisplayMediaSource for display fallback results. Use their union when storing both.1.0.0
CommentImport 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
WebhookOptionsImport 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.

On this page