How to map URLs to different methods based on the presence of query parameters (JAXB)

Question

I'm writing ReST services using JAXB/Jersey. I would like to do different server-side processing and return a different response based on whether or not the URL has query parameters. Example:

http://domain.com/Person

would map to a page documenting the available "Person" services, while

http://domain.com/Person?search="someName"

would return the results of a lookup on people.

I currently have a convention that users can get usage/documentation for each category of services by requesting the base URL (i.e., http://domain.com/Person, http://domain.com/Facility). Also, documentation is returned in XML, JSON, HTML, or plain text, depending on the Content-Type header.

Question 1: Is this a good design for a ReST service?
Question 2: How can I map URLs to different responses based on whether the URL has query parameters?

Answer 1

1. I don't think it's a good design. Assuming the URL points a resource, I don't think that resources should differ only by query parameters. You can use a different content-type or to append the url. E.g. http://domain.com/Person and http://domain.com/Person/search

2. No. JAX-RS doesn't allow such differentiation. The differentiation is based on url itself (without query string) and on producing/consuming content-type.

Answer 2

As an alternative, I would consider:

http://domain.com/service/People - Service Description

http://domain.com/People - List All People

http://domain.com/People?search=someName - List All People based on search criteria

http://domain.com/People/1234 - List a Specific Person

Logically, the resources being presented are now more consistent. Meaning, if your search could return multiple people, the resource at /People is still a list of people.

The resource represented by /People is not a service description, but rather the actual people. Hence why I would pull it into a different URL.