Lightyshare uses a date-based versioning system inspired by Stripe’s approach, ensuring backward compatibility while continuously improving the API.

​
Version Format

API versions follow the YYYY-MM-DD format: 
2025-08-16
This format makes it immediately clear when a version was released and helps track API evolution over time.

​
How Versioning Works

1

Token-based Default

When you create an API token, it’s automatically tied to the latest API version available at that time
2

Stable by Default

Your token continues using its original version even as new versions are released
3

Optional Override

You can override the version for specific requests using the lighty-version header

​
Using API Versions

​
Default Version (Token-based)

Your token uses its default version automatically: 
curl -X GET https://lightyshare.com/api/token-secured/product/123 \
  -H "Authorization: Bearer lsh_live_abc123..."

​
Override Version (Per Request)

Use a different version for a specific request: 
curl -X GET https://lightyshare.com/api/token-secured/product/123 \
  -H "Authorization: Bearer lsh_live_abc123..." \
  -H "lighty-version: 2025-01-15"

​
Check Current Version

The API version used is always returned in the response header: 
X-API-Version: 2025-08-16

​
Version Compatibility

Backward Compatible

Existing endpoints continue working as expected

Non-Breaking Changes

New fields and endpoints don’t affect existing integrations

Deprecation Notices

Advance warning before removing features

Migration Guides

Documentation for upgrading between versions

​
Types of Changes

​
Non-Breaking Changes (No Version Update)

These changes don’t require a new version:
  • ✅ Adding new endpoints
  • ✅ Adding optional request parameters
  • ✅ Adding new response fields
  • ✅ Adding new webhook events
  • ✅ Performance improvements

​
Breaking Changes (New Version Required)

These changes trigger a new version:
  • ❌ Removing endpoints
  • ❌ Removing or renaming fields
  • ❌ Changing field types
  • ❌ Modifying validation rules
  • ❌ Changing authentication methods

​
Version Lifecycle

​
Support Timeline

StageDurationDescription
ActiveOngoingCurrent default version for new tokens
Supported12 monthsPrevious versions remain fully functional
Deprecated6 monthsWarning period before removal
Sunset-Version no longer available

​
Best Practices

# Test with specific version during development
export API_VERSION="2025-08-16"

curl -X GET https://lightyshare.com/api/token-secured/product/123 \
  -H "Authorization: Bearer $API_KEY" \
  -H "lighty-version: $API_VERSION"

​
Version History

Check the Changelog for detailed information about each version.

​
Current Version: 2025-08-16

  • Initial stable release
  • Full product, bundle, and rental management
  • Token-based authentication

​
Migration Guide

When upgrading to a new version:
  1. Review the changelog for breaking changes
  2. Test in development with the new version header
  3. Update your code to handle any changes
  4. Deploy gradually using version headers
  5. Update your token when ready

​
Version Testing

Test how your integration works with different versions: 
# Test with current version
curl -X GET https://lightyshare.com/api/token-secured/product/123 \
  -H "Authorization: Bearer lsh_test_..." \
  -H "lighty-version: 2025-08-16"

# Test with future version (if available)
curl -X GET https://lightyshare.com/api/token-secured/product/123 \
  -H "Authorization: Bearer lsh_test_..." \
  -H "lighty-version: 2025-09-01"

​
FAQ

Next: View the Changelog →