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

> Discover how CasaOS manages multi-version API routing for v1, v2, and v3 using Echo framework by isolating versions in dedicated packages and leveraging handler reuse for efficiency. Learn the technical details.

- Repository: [IceWhale/CasaOS](https://github.com/IceWhaleTech/CasaOS)
- Tags: internals
- Published: 2026-06-28

---

**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`](https://github.com/IceWhaleTech/CasaOS/blob/main/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`](https://github.com/IceWhaleTech/CasaOS/blob/main/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`](https://github.com/IceWhaleTech/CasaOS/blob/main/route/v1.go) and [`route/v2.go`](https://github.com/IceWhaleTech/CasaOS/blob/main/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`](https://github.com/IceWhaleTech/CasaOS/blob/main/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`](https://github.com/IceWhaleTech/CasaOS/blob/main/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`](https://github.com/IceWhaleTech/CasaOS/blob/main/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`](https://github.com/IceWhaleTech/CasaOS/blob/main/route/v2/health.go) and [`route/v2/file.go`](https://github.com/IceWhaleTech/CasaOS/blob/main/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:

```go
// 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:

```go
// 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`](https://github.com/IceWhaleTech/CasaOS/blob/main/main.go) entry point initializes a global Echo instance and mounts version-specific routers exported by [`route/v1.go`](https://github.com/IceWhaleTech/CasaOS/blob/main/route/v1.go) and [`route/v2.go`](https://github.com/IceWhaleTech/CasaOS/blob/main/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`](https://github.com/IceWhaleTech/CasaOS/blob/main/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`](https://github.com/IceWhaleTech/CasaOS/blob/main/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`](https://github.com/IceWhaleTech/CasaOS/blob/main/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`](https://github.com/IceWhaleTech/CasaOS/blob/main/route/v1.go) and [`route/v2.go`](https://github.com/IceWhaleTech/CasaOS/blob/main/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`](https://github.com/IceWhaleTech/CasaOS/blob/main/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`](https://github.com/IceWhaleTech/CasaOS/blob/main/main.go) and implementing the corresponding service layer in `service/`, the new version integrates seamlessly with CasaOS's existing routing architecture.