API Versioning Strategy

This document outlines the versioning strategy for the AllureLMS SCORM API to ensure backward compatibility, clear communication of changes, and smooth client upgrades.

Versioning Approach
Version Format
Compatibility Policy
Deprecation Process
Breaking Changes
Migration Guide

Versioning Approach

The SCORM API uses URI path versioning with semantic versioning principles for clear, explicit version communication.

Current Version

v1 - Production (Current)

Base URL: https://connect.allurelms.com/api/v1
Introduced: 2025-01-01
Status: Stable
OpenAPI Version: 2025-10-27

Why URI Path Versioning?

We chose URI path versioning (/api/v1/, /api/v2/) over header-based or query parameter versioning for:

Clarity: Version is immediately visible in URL
Simplicity: Easy to understand and test
Caching: CDN and browser caching work naturally
Documentation: Self-documenting URLs
Tooling: Better support in API gateways and testing tools

Version Format

API Version

Format: /api/v{MAJOR}

Examples:

/api/v1/packages - Version 1
/api/v2/packages - Version 2 (future)

OpenAPI Document Version

Format: YYYY-MM-DD

Date-based versioning for OpenAPI spec to track documentation changes.

Current: 2025-10-27

Compatibility Policy

Major Version (v1 → v2)

When to increment:

Breaking changes to request/response formats
Removal of endpoints
Changed authentication mechanisms
Fundamental restructuring

Support period:

Previous major version supported for 12 months minimum
Deprecation warnings given 6 months before removal
Migration guide provided with new major version

Minor Version (Internal)

Minor changes within a major version:

New endpoints (backward compatible)
New optional parameters
New response fields (additive only)
Performance improvements
Bug fixes

Guarantee:

All changes are backward compatible
Existing clients continue working without modifications
No deprecation notices required

Patch Version (Internal)

Bug fixes and security patches:

Security vulnerability fixes
Bug fixes
Documentation updates
No API contract changes

Guarantee:

Transparent to clients
No behavior changes
Emergency patches deployed immediately

Deprecation Process

Timeline

Month 0: Deprecation Announced
  ↓
Month 1-6: Warning Period
  - Deprecation headers in responses
  - Documentation updated with warnings
  - Migration guide published
  ↓
Month 6: Deprecation Enforced (Optional Features)
  - Optional features may be removed
  - Core features still supported
  ↓
Month 12: End of Life
  - Feature or version fully removed
  - Clients must migrate

Deprecation Headers

Deprecated endpoints include headers:

Deprecation: true
Sunset: Sat, 01 Jan 2026 00:00:00 GMT
Link: <https://docs.allurelms.com/api/migration/v1-to-v2>; rel="deprecation"

Deprecation Response

Deprecated endpoints return X-API-Deprecation header:

HTTP/1.1 200 OK
X-API-Deprecation: This endpoint is deprecated. Migrate to /api/v2/packages
X-API-Sunset-Date: 2026-01-01
X-API-Migration-Guide: https://docs.allurelms.com/api/migration/v1-to-v2

Communication Channels

API Headers: Automated deprecation warnings
Email: Direct notification to API key owners
Dashboard: Deprecation warnings in admin portal
Documentation: Updated docs with migration guides
Changelog: All deprecations documented

Breaking Changes

Definition

A breaking change is any modification that requires clients to update their integration:

Breaking Changes:

❌ Removing an endpoint
❌ Removing a required field from request
❌ Removing a field from response
❌ Changing field data types
❌ Changing authentication method
❌ Changing error response format
❌ Renaming fields
❌ Changing URL paths
❌ Changing HTTP methods

Non-Breaking Changes:

✅ Adding new endpoints
✅ Adding optional request parameters
✅ Adding new fields to responses
✅ Adding new error codes
✅ Performance improvements
✅ Bug fixes
✅ Documentation updates

Breaking Change Policy

All breaking changes require:

New major version (v1 → v2)
12-month support for previous version
Migration guide with code examples
6-month advance notice before deprecation
Automated migration tools when possible

Migration Guide

Version Compatibility Matrix

Client Version	API v1	API v2 (Future)
SDK v1.x	✅ Supported	⚠️ Partial
SDK v2.x	✅ Supported	✅ Supported

Migrating from v1 to v2 (Future)

When v2 is released, follow these steps:

Review changelog: Understand all changes
Update SDK: Upgrade to latest SDK version
Test in staging: Validate all integrations
Update URLs: Change /api/v1/ to /api/v2/
Deploy: Roll out to production incrementally

Backward Compatibility Tools

Compatibility Layer:

// Future: Compatibility wrapper for v1 clients
import { V1toV2Adapter } from '@allure/scorm-api-adapter';

const adapter = new V1toV2Adapter({
  apiUrl: 'https://connect.allurelms.com/api/v2',
  apiKey: 'your-api-key',
});

// Use v1 interface, calls v2 API
const packages = await adapter.v1.packages.list();

Current API Features

v1 Endpoints

Core:

GET /api/health - Health check
GET /api/v1/packages - List packages
POST /api/v1/packages - Upload package
GET /api/v1/packages/{id} - Get package
DELETE /api/v1/packages/{id} - Delete package
GET /api/v1/sessions - List sessions
GET /api/v1/sessions/{id} - Get session
PUT /api/v1/sessions/{id} - Update session

Dispatches:

GET /api/v1/dispatches - List dispatches
POST /api/v1/dispatches - Create dispatch
DELETE /api/v1/dispatches/{id} - Revoke dispatch

xAPI (New in v1.5):

POST /api/v1/xapi/statements - Store xAPI statements
GET /api/v1/xapi/statements - Query xAPI statements
GET /api/v1/xapi/statements/{id} - Get xAPI statement
GET /api/v1/xapi/analytics/actors - Actor performance
GET /api/v1/xapi/analytics/activities - Activity performance

Version History

v1.5 (2025-11-11)

✨ Added xAPI telemetry platform
✨ Added analytics endpoints
🐛 Fixed rate limiting edge cases
📚 Updated OpenAPI specification

v1.4 (2025-11-09)

✨ Added SCORM dispatch service
✨ Added multi-tenancy
🔒 Enhanced security with RLS policies

v1.3 (2025-11-08)

✨ Added quota management
✨ Added rate limiting
⚡ Database optimization

v1.2 (2025-11-07)

✨ Added package versioning
✨ Added multipart upload support

v1.1 (2025-10-17)

✨ Added API key authentication
🔒 Enhanced security patterns

v1.0 (2025-10-16)

🎉 Initial release
SCORM 1.2 and 2004 support
Package management
Session tracking

Client Upgrade Checklist

When a new version is released, clients should:

Review the changelog for breaking changes
Check the deprecation notices
Read the migration guide
Update SDK to compatible version
Test in development environment
Test in staging environment
Monitor for deprecation headers
Plan production deployment
Execute gradual rollout
Monitor error rates and performance
Remove old version dependencies

API Stability Levels

Stable (Current: v1)

✅ Production-ready
✅ Backward compatible changes only
✅ Long-term support guaranteed
✅ Comprehensive documentation

Beta (Future Features)

⚠️ Preview features
⚠️ May change without notice
⚠️ Not recommended for production
⚠️ Limited support

Deprecated

❌ Scheduled for removal
❌ No new features
❌ Security updates only
❌ Migrate immediately

Semantic Versioning for SDKs

While the API uses major versioning (v1, v2), client SDKs follow semantic versioning:

MAJOR.MINOR.PATCH
  ↓     ↓     ↓
  2  .  1  .  3

MAJOR: Breaking changes
MINOR: New features (backward compatible)
PATCH: Bug fixes

Example:

SDK 1.0.0: Supports API v1
SDK 1.5.0: Supports API v1 + xAPI features
SDK 2.0.0: Supports API v2 (future)

Best Practices for Clients

Version explicitly: Always include version in URLs
Monitor deprecations: Check response headers regularly
Handle errors gracefully: New error codes may be introduced
Use latest SDK: SDKs are updated for new features
Test upgrades: Validate in staging before production
Subscribe to updates: Monitor changelog and announcements
Plan migrations: Start early when deprecations announced

Exceptions

Emergency security fixes may be deployed without following the standard deprecation timeline. These will be:

Communicated via email immediately
Documented in emergency changelog
Applied to all supported versions
Rolled back if compatibility issues arise

Contact

For questions about API versioning:

Documentation: https://docs.allurelms.com/api
Support: engineering@allurelms.com
Changelog: https://github.com/AllureLMS/scorm-api/blob/master/CHANGELOG.md