How CasaOS Handles API Routing with Multiple Versions (v1, v2, v3)

CasaOS implements versioned HTTP APIs using the Echo web framework by isolating each major version in dedicated Go packages (route/v1, route/v2) and mounting them under distinct URL prefixes, while allowing newer paths like /v3 to reuse existing v2 handlers through constants like V3FilePath.

The IceWhaleTech/CasaOS open-source project manages its evolving REST API surface by adopting a clear versioning strategy that separates routing logic across multiple directory structures. This architecture enables backward compatibility for existing clients while providing a clean migration path for new features. Understanding this routing pattern is essential for developers contributing to CasaOS or building integrations against its versioned endpoints.

Versioned Router Architecture in CasaOS

CasaOS organizes its API versioning through the Echo web framework, creating isolated routing groups for each major version. The system leverages Go package separation to maintain clean boundaries between v1, v2, and v3 endpoint implementations.

Main Entry Point and Global Echo Instance

The main.go file serves as the application bootstrap, initializing a global Echo instance that acts as the root router. Rather than defining endpoints directly, main.go delegates to version-specific initializers that return configured sub-routers. Each initializer registers its routes under a distinct prefix such as /v1, /v2, or /v3, ensuring clear API version isolation from the start.

Dedicated Version Packages

Each API version resides in its own package within the route/ directory. The route/v1.go and route/v2.go files export functions like NewCasaOS() that construct *echo.Group instances containing all endpoints for that specific version. These functions group related routes—such as system information, file operations, and cloud storage—while applying common middleware including JWT authentication and request logging.

For example, route/v2.go organizes v2-specific handlers and exposes them under the /v2 prefix, keeping the route definitions separate from the core business logic located in the service/ directory.

Cross-Version Handler Reuse and Compatibility

CasaOS optimizes its routing strategy by allowing newer API versions to reuse existing handlers when functionality remains unchanged, avoiding code duplication while maintaining distinct public paths.

The V3 File Path Constant

In route/v2.go, the constant V3FilePath = "/v3/file" demonstrates how CasaOS implements a v3 endpoint without creating a separate v3 package. This path constant maps /v3/file requests to the existing v2 file handlers defined in route/v2/file.go. The v2 router registers handlers under both /v2/file and /v3/file, providing a seamless upgrade path for file operations while the underlying logic remains in the v2 package.

Service Layer Abstraction

The actual business logic execution resides in the service/ directory, completely decoupled from HTTP routing concerns. Files like route/v2/health.go and route/v2/file.go act as thin HTTP adapters that validate requests, call service methods, and format responses. This separation allows multiple API versions to invoke the same service functions while presenting different REST contracts.

Practical Routing Examples

The following examples demonstrate how CasaOS exposes endpoints across versions:

// Accessing system version information via v1
GET /v1/sys/version/check

// Checking health status via v2
GET /v2/health

The file upload endpoint illustrates the cross-version pattern where v3 delegates to v2:

// Uploading files through the v2 endpoint
POST /v2/file/upload

// Uploading files through the v3 alias (handled by v2)
POST /v3/file/upload

Summary

• CasaOS uses the Echo framework to create isolated routing groups for each API version (/v1, /v2, /v3).
• The main.go entry point initializes a global Echo instance and mounts version-specific routers exported by route/v1.go and route/v2.go.
• Each version package exposes a constructor function (such as NewCasaOS()) that returns an *echo.Group configured with appropriate middleware.
• The constant V3FilePath in route/v2.go enables /v3/file endpoints to reuse handlers from the v2 package without code duplication.
• Business logic remains in the service/ directory, allowing multiple API versions to share implementation while maintaining distinct REST interfaces.

Frequently Asked Questions

How does CasaOS register multiple API versions without conflicts?

CasaOS registers each version under distinct URL prefixes in main.go. The application creates separate Echo groups for /v1, /v2, and /v3, with each group initialized by its corresponding package in the route/ directory. This prevents route collisions while allowing simultaneous operation of all API versions.

Why does CasaOS implement v3 file endpoints in the v2 package?

The V3FilePath constant in route/v2.go allows CasaOS to expose /v3/file endpoints while reusing the mature, tested file handlers from v2. This approach avoids duplicating complex file upload and download logic, ensuring consistency across API versions while still presenting a v3 interface to clients.

Where does CasaOS define middleware for versioned routes?

Middleware configuration occurs within each version's initialization function in route/v1.go and route/v2.go. Before returning the Echo group, these functions attach authentication, logging, and validation middleware that applies to all routes in that version group, keeping security concerns co-located with route definitions.

Can developers add a v4 API following the existing pattern?

Yes. Developers can create a new route/v4.go file following the established pattern of exporting a constructor function that returns an *echo.Group. After registering this group under /v4 in main.go and implementing the corresponding service layer in service/, the new version integrates seamlessly with CasaOS's existing routing architecture.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}