​
API Versioning

Lightyshare uses date-based API versioning inspired by Stripe’s approach to maintain backward compatibility while allowing for API evolution.

​
Version Format

API versions use the format YYYY-MM-DD (e.g., 2025-08-16).

​
How Versioning Works

​
1. Token-based Versioning

When you create an API token, it’s automatically tied to the latest API version available at that time. This version becomes the default for all requests made with that token.

​
2. Request-level Override

You can override the token’s version for specific requests using the lighty-version header: 
curl -H "Authorization: Bearer YOUR_TOKEN" \
     -H "lighty-version: 2025-01-15" \
     https://lightyshare.com/api/token-secured/rental/123

​
3. Stable URLs

API URLs remain stable across versions. The version is handled transparently via token or header, so you don’t need to change your endpoint URLs when new versions are released.

​
Examples

​
Using Token’s Default Version

# Uses the version tied to your token (e.g., 2025-08-16)
curl -H "Authorization: Bearer lsh_live_abc123..." \
     https://lightyshare.com/api/token-secured/rental/123

​
Override with Header

# Override to use a specific version
curl -H "Authorization: Bearer lsh_live_abc123..." \
     -H "lighty-version: 2025-01-15" \
     https://lightyshare.com/api/token-secured/rental/123

​
Version Information

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

​
Migration Strategy

  • Gradual migration: You can test new API versions before fully migrating
  • Backward compatibility: Old versions remain supported for a reasonable period
  • Deprecation notices: You’ll receive advance notice before versions are deprecated

​
Best Practices

  1. Pin your version: Use a specific version header for production applications
  2. Test new versions: Test with newer versions in development before upgrading
  3. Monitor deprecations: Stay informed about version deprecation timelines
  4. Plan migrations: Schedule regular updates to stay current with the latest features