RESTful Web Service - JAX-RS Annotations

Annotation	Package Detail/Import statement
@GET	import javax.ws.rs.GET;
@Produces	import javax.ws.rs.Produces;
@Path	import javax.ws.rs.Path;
@PathParam	import javax.ws.rs.PathParam;
@QueryParam	import javax.ws.rs.QueryParam;
@POST	import javax.ws.rs.POST;
@Consumes	import javax.ws.rs.Consumes;
@FormParam	import javax.ws.rs.FormParam;
@PUT	import javax.ws.rs.PUT;
@DELETE	import javax.ws.rs.DELETE;

REST follows one-to-one mapping between create, read, update, and delete (CRUD) operations and HTTP methods.

• To create a resource on the server, use POST.
• To retrieve a resource, use GET.
• To change the state of a resource or to update it, use PUT.
• To remove or delete a resource, use DELETE.

@GET

Annotate your Get request methods with @GET.

1 2 3 4

@GET public String getHTML() {   ... }

@Produces

@Produces annotation specifies the type of output this method (or web service) will produce.

1 2 3 4 5

@GET @Produces("application/xml") public Contact getXML() {   ... }

1 2 3 4 5

@GET @Produces("application/json") public Contact getJSON() {   ... }

@Path

@Path annotation specify the URL path on which this method will be invoked.

1 2 3 4 5 6

@GET @Produces("application/xml") @Path("xml/{firstName}") public Contact getXML() {   ... }

@PathParam

We can bind REST-style URL parameters to method arguments using @PathParam annotation as shown below.

1 2 3 4 5 6 7

@GET @Produces("application/xml") @Path("xml/{firstName}") public Contact getXML(@PathParam("firstName") String firstName) {   Contact contact = contactService.findByFirstName(firstName);   return contact; }

1 2 3 4 5 6 7

@GET @Produces("application/json") @Path("json/{firstName}") public Contact getJSON(@PathParam("firstName") String firstName) {   Contact contact = contactService.findByFirstName(firstName);   return contact; }

@QueryParam

Request parameters in query string can be accessed using @QueryParam annotation as shown below.

1 2 3 4 5 6 7

@GET @Produces("application/json") @Path("json/companyList") public CompanyList getJSON(@QueryParam("start") int start, @QueryParam("limit") int limit) {   CompanyList list = new CompanyList(companyService.listCompanies(start, limit));   return list; }

The example above returns a list of companies (with server side pagination) which can be displayed with rich clients implemented using Ext-js or jQuery. You can read more more about setting up ExtJS grid panel with remote sorting and pagination using Hibernate.

@POST

Annotate POST request methods with @POST.

1 2 3 4 5 6

@POST @Consumes("application/json") @Produces("application/json") public RestResponse<Contact> create(Contact contact) { ... }

@Consumes

The @Consumes annotation is used to specify the MIME media types a REST resource can consume.

1 2 3 4 5 6 7

@PUT @Consumes("application/json") @Produces("application/json") @Path("{contactId}") public RestResponse<Contact> update(Contact contact) { ... }

@FormParam

The REST resources will usually consume XML/JSON for the complete Entity Bean. Sometimes, you may want to read parameters sent in POST requests directly and you can do that using @FormParam annotation. GET Request query parameters can be accessed using @QueryParam annotation.

1 2 3 4 5

@POST public String save(@FormParam("firstName") String firstName,     @FormParam("lastName") String lastName) {       ...   }

@PUT

Annotate PUT request methods with @PUT.

1 2 3 4 5 6 7

@PUT @Consumes("application/json") @Produces("application/json") @Path("{contactId}") public RestResponse<Contact> update(Contact contact) { ... }

@DELETE

Annotate DELETE request methods with @DELETE.

1 2 3 4 5 6

@DELETE @Produces("application/json") @Path("{contactId}") public RestResponse<Contact> delete(@PathParam("contactId") int contactId) { ... }

References

1. Jersey JAX-RS Annotations: https://wikis.oracle.com/display/Jersey/Overview+of+JAX-RS+1.0+Features