I can't answer specifically with java and the restlet framework. But in general, a mistake I have seen over and over again is developers thinking version of so

I can't answer specifically with java and the restlet framework. But in general, a mistake I have seen over and over again is developers thinking version of software. When you are building an API you are versioning the communication contract, not the software. You may completely change the implementation but as long as the contract doesn't change it is fine, this also means you can add optional fields to an existing contract without breaking the contract. Also, this is why you should spend a lot of time on the payload/communication contract. So given that, the two common ways are 1, adding the version to the URI like you mentioned, which works fine and is used by some very popular services. Option 2 is to have the version be either part of the request body or request header, and if it isn't specified use the latest version. Each option has pros/cons. Just as 1 example, in Option 1 you can have a front end service like nginx route to different end points based on the version om the URI. Thus making load balancing or handling special clients pretty easy. In Option 2 you could still do this but it would take either inspection of the header or another layer to inspect the payload, which isn't as efficient.