3

I am a new comer in terms of web services. I am tasked to convert an existing software component to a web service. I did some research and I decided to use JAX-RS. I am having a difficulty to decide when to use @QueryParam and when to use @Consume because they seems to be able to achieve the same goal.

For example, let say I have a method named read() and it takes a book as an argument.

public class AReader { public void read(Book book){...} }
public class Book { public String author; public String name; }

When translating this using JAX-RS annotation, I could either

  • Use @POST and @QueryParam to accept the author and name parameter or
  • Use @POST and @Consumes to consume a text representation of Book in XML or JSON format in the body.

My question is what is the common usage for @QueryParam and @Consume. Is this just a personal preference or there is a common practice?

I found a lot information about usage of @PathParam and @QueryParam but not @QueryParam and @Consumes.

Thanks in advance...

beyonddc
  • 1,246
  • 3
  • 13
  • 26
  • Do you mean @Consumes? – Vidya Oct 07 '13 at 04:16
  • Depends on what client interface you want to provide. Query parameters are "easier" for browsers (if you want to stick with HTML forms), raw JSON or XML is simpler for other tools. – Thilo Oct 07 '13 at 04:18
  • Vidya, indeed, I meant @Consumes. It's a typo. Thank you, I corrected my post. – beyonddc Oct 07 '13 at 04:19

3 Answers3

4

Query parameters are ideally best suited for representing aspects of requests that have nothing to do with a resource representation.

For example, if you are designing a RESTful web service, and if you're creating a new Book via a POST request, then the body of the request should ideally contain the resource representation in the desired media type - application/json, text/xml, application/x-www-form-urlencoded etc. Providing the resource representation via query parameters would not be on the lines of how HTTP-based REST APIs are designed. Additionally, query parameters can be omitted and thus the provided resource representation is incomplete, which would be against the design principles that require complete resource representations to be provided in POST and PUT operations.

Query paremeters would be more suitable for GET requests. Say you want a paginated collection of requests, then you would accept requests like /books?start=0&pagesize=10 to obtain the first 10 books.

Vineet Reynolds
  • 76,006
  • 17
  • 150
  • 174
1

You are right when you say you can use @QueryParam and @Consumes to achieve a common goal, but be aware that the semantics of those annotations are very different.

In your case, since you are interested in just two values, both approaches are equivalents in my opinion. If you were working with more complex objects (i.e. POJO with several attributes), I would suggest you let JAX-RS implementations take care of object marshalling/unmarshalling annotating the methods with @Consumes and/or @Produces.

This sample code:

@GET
@Path("/books")
public void books(@PathParam("title") String title, @PathParam("author") String author, @PathParam("ISBN") String isbn, @PathParam("category") String category, @PathParam("price") String price) {
  Book book = new Book(title, author, isbn, category, price);
  ...
}

could be reduced to

@POST
@Path("/books")
@Consumes(MediaType.APPLICATION_XML)
public void books(Book newBook) {
  Book book = newBook;
  ...
}

Additionally, REST architecture brings a new semantics to HTTP verbs and codes. According to its guidelines, you are not supposed to use @POST with @PathParam or even @GET to modify a resource. Please, refer to this link for a brief explanation but feel free to explore it in more details (you can start here).

Community
  • 1
  • 1
Trein
  • 3,658
  • 27
  • 36
0

In JAX-RS, you can use @QueryParam annotation to inject URI query parameter into Java method. for example,

/users/query?url=nini.com In above URI pattern, query parameter is “url=nini.com“, and you can get the url value with @QueryParam("url").

======

""http://docs.oracle.com/cd/E19776-01/820-4867/ggqqr/ ""

nini
  • 1
  • 1
  • 2