What is the best way to support API versioning in this package?

[zacharyhansen]

I am wondering about how other have thought about incorporating versioning of API's in ORPC? Its an amazing tool and the OPEN API tooling is first class but providing a API usually means you will want to support versioning at some point if 3rd parties are consuming the API.

[dosubot[bot]]

ORPC doesn't have built-in, prescriptive API versioning, but it gives you all the extension points you need to implement it cleanly. The most common approach is to structure your routers/contracts by version (for example, v1Router, v2Router), and mount them under versioned route prefixes like /api/v1 or /api/v2 in your handler setup. This way, each version can evolve independently and you can deprecate or sunset old versions as needed.

When generating your OpenAPI spec, you can set the version in the info.version field—this is supported directly in the OpenAPI tooling, so each versioned API can have its own spec and docs. See this example of setting the version in the OpenAPI generator config and using route prefixes for versioning:
example code
OpenAPI versioning in config

If you need more advanced versioning (like header-based or media-type versioning), you can use plugins or custom adapters—ORPC's plugin system is designed for this kind of extensibility. The key is to keep each version's contract and handler isolated, and use the OpenAPI tooling to generate distinct specs for each version. This approach is flexible and aligns with how ORPC is designed to be extended.

To reply, just mention @dosu.

---

^{How did I do? Good | Irrelevant | Incorrect | Verbose | Hallucination | Report 🐛 | Other}    

[unnoq]

My recommendation is each version has its own router/contract and handler, and use different prefix to route them /api/v1 /api/v2

[zacharyhansen]

thanks for the info!