Client Versioning
Client version headers let one REST resource return different responses depending on which version of a client is calling, so you can make breaking interface changes without breaking older clients.
When to use it
Use client versions when you must change an operation's response in a way older clients cannot handle, and you cannot make every client upgrade at once. You keep one method per version range on the same path, and the framework picks the method whose range contains the version in the request header.
Example
import org.apache.juneau.rest.server.*;
import org.apache.juneau.rest.server.servlet.*;
@Rest(clientVersionHeader="Client-Version")
public class MyResource extends BasicRestServlet {
// Called if Client-Version is at least 2.0.
// This also matches 2.0.1.
@RestGet(path="/foobar", clientVersion="2.0")
public String method1() {
return "version 2.0 or later";
}
// Called if Client-Version is at least 1.1 but less than 2.0.
@RestGet(path="/foobar", clientVersion="[1.1,2.0)")
public String method2() {
return "version 1.1 up to 2.0";
}
// Called if Client-Version is less than 1.1.
@RestGet(path="/foobar", clientVersion="[0,1.1)")
public String method3() {
return "versions before 1.1";
}
}
Options
| Setting | Meaning |
|---|---|
@Rest(clientVersionHeader) | The name of the request header that carries the client version. |
@RestOp(clientVersion) | The version range the method accepts: "1.0" is at least 1.0, "[0,1.0)" is below 1.0, and "[0,1.0]" is up to and including 1.0. |