RESTful Web Service - JAX-RS Annotations

Our Article Library

Part 3: RESTful Web Service - JAX-RS Annotations

This tutorial is part 3 of 5-part tutorial on JEE annotations. We recommend that you read Prerequisite section first, review the abstract and Example Application to understand the context. You can also jump to other parts by clicking on the links below.

Annotation Tutorial: Contents
JEE Annotations ( Abstract Example Application References ) Part 1: Spring Annotations Part 2: Hibernate - JPA Annotations Part 3: RESTful Web Service - JAX-RS Annotations Part 4: JAXB Annotations Part 5: Spring - jUnit Annotations

RESTful Web Service - JAX-RS Annotations - Contents:

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;

As stated earlier in Example Application, we are using Jersey for RESTful Web services and JAX-RS annotations.

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.

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

@Produces

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

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

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

@Path

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

  @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.

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

  @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.

  @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.

	@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.

	@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.

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

@PUT

Annotate PUT request methods with @PUT.

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

@DELETE

Annotate DELETE request methods with @DELETE.

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

References

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