Versioning

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

Token-based Default

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

Stable by Default

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

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

Stage	Duration	Description
Active	Ongoing	Current default version for new tokens
Supported	12 months	Previous versions remain fully functional
Deprecated	6 months	Warning period before removal
Sunset	-	Version no longer available

Best Practices

Development
Production

# 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"

// Lock version in production code
const LIGHTYSHARE_API_VERSION = '2025-08-16';

fetch('https://lightyshare.com/api/token-secured/product/123', {
  headers: {
    'Authorization': `Bearer ${API_KEY}`,
    'lighty-version': LIGHTYSHARE_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:

Review the changelog for breaking changes
Test in development with the new version header
Update your code to handle any changes
Deploy gradually using version headers
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

What happens if I don't specify a version?

Your API token’s default version is used automatically. This is the version that was current when your token was created.

Can I change my token's default version?

No, but you can create a new token which will use the latest version, or override the version per request using headers.

How do I know which version I'm using?

Check the X-API-Version header in any API response to see which version was used for that request.

Will my integration break when new versions are released?

No, your token continues using its original version. New versions don’t affect existing integrations unless you explicitly upgrade.

Next: View the Changelog →

Getting Started

Core Resources

Examples

Version Format

How Versioning Works

Using API Versions

Default Version (Token-based)

Override Version (Per Request)

Check Current Version

Version Compatibility

Backward Compatible

Non-Breaking Changes

Deprecation Notices

Migration Guides

Types of Changes

Non-Breaking Changes (No Version Update)

Breaking Changes (New Version Required)

Version Lifecycle

Support Timeline

Best Practices

Version History

Current Version: 2025-08-16

Migration Guide

Version Testing

FAQ

​Version Format

​How Versioning Works

​Using API Versions

​Default Version (Token-based)

​Override Version (Per Request)

​Check Current Version

​Version Compatibility

Backward Compatible

Non-Breaking Changes

Deprecation Notices

Migration Guides

​Types of Changes

​Non-Breaking Changes (No Version Update)

​Breaking Changes (New Version Required)

​Version Lifecycle

​Support Timeline

​Best Practices

​Version History

​Current Version: 2025-08-16

​Migration Guide

​Version Testing

​FAQ

Version Format

How Versioning Works

Using API Versions

Default Version (Token-based)

Override Version (Per Request)

Check Current Version

Version Compatibility

Types of Changes

Non-Breaking Changes (No Version Update)

Breaking Changes (New Version Required)

Version Lifecycle

Support Timeline

Best Practices

Version History

Current Version: 2025-08-16

Migration Guide

Version Testing

FAQ