Chapter 3. Using @Path and @GET, @POST, etc.
@Path("/library") public class Library { @GET @Path("/books") public String getBooks() {...} @GET @Path("/book/{isbn}") public String getBook(@PathParam("isbn") String id) { // search my database and get a string representation and return it } @PUT @Path("/book/{isbn}") public void addBook(@PathParam("isbn") String id, @QueryParam("name") String name) {...} @DELETE @Path("/book/{id}") public void removeBook(@PathParam("id") String id {...} }
If you have the RESTEasy Servlet configured and reachable at a root path of
http://myhost.com/services
, the requests would be handled by the Library
class:
- GET http://myhost.com/services/library/books
- GET http://myhost.com/services/library/book/333
- PUT http://myhost.com/services/library/book/333
- DELETE http://myhost.com/services/library/book/333
The
@javax.ws.rs.Path
annotation must exist on either the class or a resource method, or both. If it exists on both the class and method, the relative path to the resource method is a concatenation of the class and method.
The
@javax.ws.rs package
contains annotations for each HTTP method. @GET
, @POST
, @PUT
, @DELETE
, and @HEAD
. Place these annotations on public methods that you want to map to the annotation's HTTP method. If a @Path
annotation exists on the class, you do not need to annotate the method you wish to map with @Path
. Multiple HTTP methods can be used, as long as they can be distinguished from other methods.
When a method is annotated with
@Path
without a HTTP method being applied, the annotated method is referred to as a JAXRSResourceLocator
.
3.1. @Path and regular expression mappings
The
@Path
annotation is not limited to simple path expressions. You can also insert regular expressions into the value of @Path
. For example:
@Path("/resources) public class MyResource { @GET @Path("{var:.*}/stuff") public String get() {...} }
The following GETs will route to the
getResource()
method:
GET /resources/stuff GET /resources/foo/stuff GET /resources/on/and/on/stuff
The format of the expression is:
"{" variable-name [ ":" regular-expression ] "}"
Here,
regular-expression
is optional. Where this is not provided, the expression defaults to a wildcard matching of one particular segment, like so:
"([]*)"
For example:
@Path("/resources/{var}/stuff")
will match these:
GET /resources/foo/stuff GET /resources/bar/stuff
but will not match:
GET /resources/a/bunch/of/stuff