RESTful URLs tend to have the primary identifier of a resource as part of the URL:
/api/user/12345
Sending a GET request to this URL would return the current state of the User
and a PUT would be used to update the User.
When I was introduced to this concept in ~2010 it just kind of made sense as
this was similar to how you would design a class
API:
getUser(12345);
updateUser(12345, userCriteria);
The id of the User is
primary and a prominent part of the method signature and never part of a Map or
"input criteria" that may be passed in. Having it front and center sent a clear message to the
API consumer that this id is important and the call will fail without it.
The project I'm working on currently uses a custom framework that does not support REST.
A decision was made long ago that
the framework would use RPC
and it did not support things like
path variables or request method dispatching.
You could do it by parsing the path yourself or branching logic based on REQUEST_METHOD
but this was frowned upon and generally resulted in passive aggressive PR comments.
I made peace with this as not-a-battle-I-want-to-fight and worked around it with
APIs like /api/getUser?userId=12345 and /api/updateUser?userId=12435.
I'm working on refactoring some legacy code that does a lot of manual-request-mapping and handles authentication in the same place as the application logic. The purpose of the refactoring is to move to a newer framework module that can automatically deserialize request parameters into Objects and move the auth check up to a separate layer. Currently the code looks like this:
class TicketController extends BaseFrameworkController{
@Inject
private TicketService ticketService;
public Model getTicket(HttpServletRequest request){
Set<Role> userRoles = getRolesFromSession(request);
Ticket ticket = ticketService.find(request.getParameter("ticketId"));
if (!userCanAccessProject(roles, ticket.getProject()) {
return new Model().withStatus(403).withMessage("Insufficient roles to view ticket");
}
return translateToModel(ticket);
}
public Model updateTicket(HttpServletRequest request){
Set<Role> userRoles = getRolesFromSession(request);
Ticket ticket = ticketService.find(request.getParameter("ticketId"));
if (!userCanAccessProject(roles, ticket.getProject()) {
return new Model().withStatus(403).withMessage("Insufficient roles to view ticket");
}
return translateToModel(
ticketService.update(
request.getParameter("ticketId"),
parseLabelsFromRequest(request),
request.getParameter("status")
)
);
}
getTicket() is called via a GET request with a query string and
updateTicket() is called via POST with parameters sent as form-urlencoded.
The nice thing is that the request doesn't care about GET vs POST in this situation and
request.getParameter("ticketId") can be handled in the same way making it easy
to pull that auth logic out to another component, which the framework provides hooks for:
addRoute("/api/ticket/getTicket", TicketController.class)
.withAuthCheck(ticketParamProjectAuthChecker);
addRoute("/api/ticket/updateTicket", TicketController.class)
.withAuthCheck(ticketParamProjectAuthChecker);
And my AuthChecker looks like:
class TicketParamProjectAuthChecker extends AuthChecker {
@Override
public boolean check(HttpServletRequest request) {
Set<Role> userRoles = getRolesFromSession(request);
Ticket ticket = ticketService.find(request.getParameter("ticketId"));
return userCanAccessProject(roles, ticket.getProject());
}
}
There's now an additional service call to retrieve the ticket for each of these requests
but it is well worth the tradeoff of getting the auth logic out of the controller.
If performance ever becomes an issue we can easily introduce a caching layer within
TicketService.
With the auth logic pulled out I make my move to introduce request mapping:
class TicketController extends BaseFrameworkController{
@Inject
private TicketService ticketService;
public Ticket getTicket(@MapRequest TicketRequest ticketRequest){
return ticketService.find(ticketRequest.ticketId());
}
public Ticket updateTicket(@MapRequest TicketUpdateRequest ticketRequest){
return ticketService.update(
ticketRequest.ticketId(),
ticketRequest.labels(),
ticketRequest.status()
);
}
Much cleaner, but here's the challenge: The TicketUpdateRequest is
parsed from the REQUEST_BODY. This means I'll have to have a separate AuthChecker to parse
the request body, deserialize it to a TicketUpdateRequest and then get the ticketId:
class TicketRequestBodyProjectAuthChecker extends AuthChecker {
@Override
public boolean check(HttpServletRequest request) {
Set<Role> userRoles = getRolesFromSession(request);
String requestBody;
try {
requestBody = request.getReader().lines().collect(joining());
} catch (IOException e) {
throw new RuntimeException(e);
}
TicketUpdateRequest ticketRequest = deserialize(requestBody, TicketUpdateRequest.class);
Ticket ticket = ticketService.find(ticketRequest.ticketId());
return userCanAccessProject(roles, ticket.getProject());
}
}
That means the auth logic now lives in 2 places as well as the deserialization logic. The former I can work around with a factory or common component. The latter I don't have much recourse on (the logic that handles this in the framework is inaccessible to framework consumers). Not the end of the world but it is now more code I'll have to support as part of the project.
If the URLs followed the REST standard and were both /api/ticket/:ticketId
the same authorization check would have been sufficient to pull the id from the PATH and authorize it.
Having identifiers in the URL imparts other advantages like caching and API discoverability but
it's an interesting experience to be hit squarely in the face with a concrete consequence.
The astute reader may observe:
If sending the update request via request body was causing a problem, why not just send it as form-urlencoded? That way both auth checks can check for the parameter in the same way and Bob's your uncle. You've already abandoned REST as a matter of policy so who cares how the data is passed?
The issue is actually this bit: ticketRequest.labels(). Behind the scenes a complex list
of objects are being deserialized. This is trivial when parsing JSON as part of the request body but
more complicated when parsing the form-urlencoded data.
That's what was going on in the parseLabelsFromRequest()
method above, it was manually parsing:
labelName=blue&labelType=normal&labelName=green&labelType=priority
into a List<Label>.
While a generalized serialization solution is not impossible it is a route I decided not to go down in a juice-ain't-worth-the-squeeze
way, especially because it would require approval from the framework team.
While HTTP doesn't forbid this, the framework does.