Designing the bridge between REST layer to service layer

Question

I am working on a project and would like to expose some REST services. The technologies used are RestEasy, EJB and JPA/Hibernate. I have structured my app so that there is a clear delimitation between the service layer and model layer. A typical service that retrieves data from the database have a signature like this: getWhateverList(idForWhichTheListWillBeRetrieved, start) - so pretty basic.

What I'm having a hard time wrapping my head around is how to bring together the stiffness of the service layer with the flexibility of the REST layer. Say for example that I would like a typical GET method producing a JSON array support operations like:

• filtering - use a query param to get, for example items that have a property of type date greater/lower than the param that I provide
• sorting - REST API should support asc or desc
• limiting the fields that are returned from the GET operation

How would one go about designing this?

Answer 1

• filtering - use a query param to get, for example items that have a property of type date greater/lower than the param that I provide

For that you need a query language. You can use any existing query language as long as you describe it with metadata in your links. So your clients and server can have a common contract which is described by that metadata. For example GET /users?q="statement using a standard query language".

You can describe simple queries using URI templates. For example GET /users?firstName={firstName}

• sorting - rest api should support asc or desc

You can use the same links described above with additional query params. For example GET /users?sortBy="name"&direction="asc".

• limiting the fields that are returned from the GET operation

You can use the same links described above with additional query params. For example GET /users?fields="firstName,secondName,age".

note: According to the uniform interface / HATEOAS constraint you have to send links to your clients. According to the uniform interface / self-descriptive messages constraint, these links have to contain meta-data (for example link relation) about what they are. So the clients can check that meta-data and chose the proper link to reach their goal.