Skip to main content

API Versioning

Overview​

Smart Academic Hub uses URI versioning for API management.

Versioning Strategy​

URI Versioning​

All API endpoints are prefixed with the version number:

/api/v1/academies
/api/v2/academies (future)

Current Version​

Version 1.1 (/api/v1/)

Version Management​

Controllers​

Controllers are organized by version:

app/Http/Controllers/Api/V1/
app/Http/Controllers/Api/V2/ (future)

Routes​

Routes are grouped by version:

Route::prefix('v1')->group(function () {
    // V1 routes
});

Backward Compatibility​

  • Maintain previous versions during transition periods
  • Deprecation notices in response headers
  • Documentation for migration paths

Breaking Changes​

Breaking changes require a new major version:

  • Removing endpoints
  • Changing response structure
  • Modifying required parameters

Non-Breaking Changes​

Can be added to existing versions:

  • Adding optional parameters
  • Adding new endpoints
  • Adding fields to responses

Deprecation Policy​

  1. Announce deprecation 6 months in advance
  2. Support old version for migration period
  3. Provide clear migration documentation
  4. Set deprecation headers

Best Practices​

  • Always specify version in API calls
  • Don't mix versions in single application
  • Plan version upgrades carefully
  • Test thoroughly before upgrading