RESTful URI's, Creating a new noun/uri or add a queryparameter

Question

I have a Person class with a one to many relationship to Employment. A Person in the CRM can have multiple Employments (historic data).

My current REST URI for this class looks like this:

http://domain/persons GET [collection]
http://domain/persons/{id} GET [resource]
http://domain/persons/{id}/employments GET [collection]

To get the CURRENT active employment (so the employment where the endDate is NULL) should I create a URI or should this be done using a QueryParam?

Basically should I do this:

http://domain/persons/{id}/employments/current GET [resource]

or

http://domain/persons/{id}/employments?current GET [collection with query param filter]

I'm thinking the second one (with the queryparam) because as far as I understand REST a resource should be identified with a non changable URI. Since the current employment position can change it should be done with a QueryParam.

What are your suggestions?

Answer 1

The "current" employment can be identified with a "non-changeable" url: it's always at employments/current. It is allowed to point to a different employment object just as the download link for the "current" version of a library can point at different actual files as the library is updated while retaining the same URI. I would use /employments/current. /employments?current isn't correct as the resource has changed (from a collection of employments to a single employment) but the URI path has not.

Answer 2

If you code looks something like this or more complicated

 import javax.ws.rs.GET;
 import javax.ws.rs.Path;
 import javax.ws.rs.QueryParam;
 import javax.ws.rs.core.Response;
 @Path("/domain/persons")
 public class UserRestService {

@GET
@Path("{id}/employments/current")
public Response getPersonById(@QueryParam("id") int id) {

   return Response.status(200).entity("getPseronById is called, id : " + id).build();

} 
}

All this means is that your first assumption is correct

Use domain/persons/{id}/employments/current