SALZ
Sign Up

API Versioning

How SALZ handles API versioning -- backward compatibility, deprecation policy, and migration guides between versions.

SALZ uses URL-based versioning to ensure your integrations remain stable as the API evolves. This page explains the versioning strategy, backward compatibility guarantees, and how to handle version transitions.

Current Version

The current and only production version is v1:

https://add-salz.io/api/v1/optimize

All requests must include the version prefix in the URL path.

Versioning Strategy

SALZ follows a conservative versioning approach:

  • Minor improvements (better optimization quality, faster processing) are rolled out to the current version without a version bump. These changes are always backward-compatible.
  • Additive changes (new optional fields in request/response) are added to the current version. Existing integrations are unaffected because new fields are optional.
  • Breaking changes (removing fields, changing field types, altering behavior) trigger a new major version (e.g., v2).

What Counts as a Breaking Change

The following changes would require a new API version:

  • Removing or renaming a field in the request or response
  • Changing the type of an existing field
  • Changing the meaning or behavior of an existing field
  • Requiring a previously optional field
  • Changing authentication mechanisms
  • Changing error response structure

The following changes are not breaking and may happen in the current version:

  • Adding new optional fields to the request body
  • Adding new fields to the response body
  • Improving optimization quality
  • Reducing response times
  • Adding new endpoints

Backward Compatibility

When v2 is released, v1 will continue to work. SALZ maintains previous versions for at least 12 months after a new version is released.

During the overlap period, both versions are fully supported:

# v1 continues to work
curl -X POST https://add-salz.io/api/v1/optimize ...

# v2 is also available
curl -X POST https://add-salz.io/api/v2/optimize ...

Deprecation Policy

When a version is deprecated:

  1. Announcement -- SALZ sends an email and adds a Deprecation header to API responses at least 6 months before end-of-life.
  2. Warning headers -- Responses from the deprecated version include a Sunset header with the retirement date.
  3. Migration guide -- Documentation for migrating to the new version is published.
  4. End of life -- After the sunset date, requests to the deprecated version return a 410 Gone response with a message directing you to the new version.

Deprecation Headers

Deprecation: true
Sunset: Sat, 01 Mar 2027 00:00:00 GMT
Link: <https://add-salz.io/docs/migration/v1-to-v2>; rel="successor-version"

Checking Your Version

You can verify which version you are using by checking the URL path in your API calls. The response does not include a version field -- the URL is the source of truth.

Best Practices

  • Pin your integration to a specific version. Always include /v1/ in your API URLs rather than using an unversioned path.
  • Monitor deprecation headers. Check API responses for Deprecation and Sunset headers in your logging or monitoring.
  • Test against new versions early. When a new version is announced, test your integration against it in a staging environment before switching production.
  • Subscribe to announcements. SALZ sends version update notifications to the email on your account.