REST Design for different actions - web-services

Question

Say we have a entity called Timesheet. For simplicity, let's assume the Timesheet entity has three properties (TimesheetID, Status and Hours).
We currently allows the owners of Timesheet objects to submit their Timesheets via this end point -
POST: /Users/{UserID}/Timesheets/{TimesheetID}
With {UserID} currently is the owner of the Timesheet object. With {TimesheetID} I can also trace back the owner of the Timesheet in the database.
OK, now here is the question -
Now we'd like to have their managers to be able to update the Timesheet objects of the employees to that report to them (such as approve/reject Timesheets by changing the Status, or override Hours).
However, there are different levels of Manager Permissions. Some managers are only allow to update Status and some of them are allowed to update both Status and Hours.
Should I reuse the existing end point for both regular user submissions and managers update (I prefer)? Or should I create a different end point for each of the "Manager Level"?
If I hope to reuse the existing end point for all user submissions and manager updates, how do I handle the errors such as if a manager is configured to only update the Status, but the TimeSheet object posted to the REST service has both Status and Hours changed. Should I respond with a 403 with a detailed error description to tell the Manager that you can't change the Hours property or update the Status and ignore Hours?

Answer 1

If you're following the HATEOAS constraint, then a GET on the Timesheet resource will provide the hypermedia controls (links and forms) that can currently be used to interact with it. While this can be done a number of ways, the one that provides the lowest form of coupling, will include in the form they valid parameters.
For your example, I would include two manager forms with the same endpoint /Users/{UserID}/Timesheets/{TimesheetID}. The first one would have a status as a required field, the second one would have status (status could be optional) and hours (hours would be required).
You could then either have the second form respond with 403 Forbidden if the submitter is not permitted to submit hours. Or alternatively, you could filter the forms included in the GET, so that only the forms the user is permitted to submit are shown.
Update
For example and GET on /Users/1234/Timesheets/24 might currently produce
<Timesheet>
<TimesheetID>24</TimesheetID>
<Status>Submitted</Status>
<Hours>40</Hours>
</Timesheet>
To apply the HATEOAS constraint, we need to add the hypermedia controls. We'll ignore the URLs for the moment, because they are implementation details. This might give us something like
<Timesheet>
<TimesheetID>24</TimesheetID>
<Status>Submitted</Status>
<Hours>40</Hours>
<link rel="self" href="{{selfUrl}}"/>
<form id="approve" action="{{approveUrl}}" method="PUT">
<Status cardinality="required">
<option value="Approve"/>
</Status>
</form>
<form id="reject" action="{{rejectUrl}}" method="PUT">
<Status cardinality="required">
<option value="Reject"/>
</Status>
</form>
<form id="update" action="{{updateUrl}}" method="PUT">
<Status cardinality="required">
<option value="Approve"/>
<option value="Reject"/>
</Status>
<Hours type="decimal" cardinality="required"/>
</form>
... there might be other forms too, like ...
<form id="cancel" action="{{cancelUrl}}" method="DELETE"/>
</Timesheet>
What the forms do (and how to recognise a form) are what get's documented in the media type. For instance:
The cancel form on a Timesheet resource will cancel the timesheet, updating it's status to "Cancelled". Once a Timesheet has been cancelled, it will no longer be possible to update approve or reject the timesheet.
Also in the media type you would document the properties of the resources. e.g.,
The Timesheet resource has a the following properties:
TimesheetID A unique identifier for the timesheet
Status The current status of the timesheet. Status may include
Submitted The timesheet has been submitted, but not approved
Approved The timesheet has been approved
Rejected The timesheet has been rejected
Cancelled The timesheet has been cancelled
Hours The number of hours (decimal) recorded for the timesheet
While this could be specified by a schema, this should be avoided as doing so can may it very difficult to extent the resources later on. For instance, you might decide to add a "WeekEnding" date property. Existing callers should not care about the new property, which is fine if they are just plucking out the data they are interested in. However, if you've specified the schema without thoughts of extension, then adding properties can cause validation errors in the callers when you add properties.
Now, in terms of who can do what we have a couple of options. One option is to just include all the controls and respond with 403 for any requests made that the caller is not authorised to invoke. Another option is to filter the controls, so they can only see the ones they can invoke. e.g. for the manager that can approve/reject, they might get the following response
<Timesheet>
<TimesheetID>24</TimesheetID>
<Status>Submitted</Status>
<Hours>40</Hours>
<link rel="self" href="{{selfUrl}}"/>
<form id="approve" action="{{approveUrl}}" method="PUT">
<Status cardinality="required">
<option value="Approve"/>
</Status>
</form>
<form id="reject" action="{{rejectUrl}}" method="PUT">
<Status cardinality="required">
<option value="Reject"/>
</Status>
</form>
</Timesheet>
Whereas a manager that can update the hours might get
<Timesheet>
<TimesheetID>24</TimesheetID>
<Status>Submitted</Status>
<Hours>40</Hours>
<link rel="self" href="{{selfUrl}}"/>
<form id="approve" action="{{approveUrl}}" method="PUT">
<Status cardinality="required">
<option value="Approve"/>
</Status>
</form>
<form id="reject" action="{{rejectUrl}}" method="PUT">
<Status cardinality="required">
<option value="Reject"/>
</Status>
</form>
<form id="update" action="{{updateUrl}}" method="PUT">
<Status cardinality="required">
<option value="Approve"/>
<option value="Reject"/>
</Status>
<Hours type="decimal" cardinality="required"/>
</form>
</Timesheet>
Alternatively, you can include all the forms for all the users, but add an indicator that they are not authorised to invoke it. e.g. for the manager that can't update hours:
<Timesheet>
<TimesheetID>24</TimesheetID>
<Status>Submitted</Status>
<Hours>40</Hours>
<link rel="self" href="{{selfUrl}}"/>
<form id="approve" action="{{approveUrl}}" method="PUT">
<Status cardinality="required">
<option value="Approve"/>
</Status>
</form>
<form id="reject" action="{{rejectUrl}}" method="PUT">
<Status cardinality="required">
<option value="Reject"/>
</Status>
</form>
<form id="update" action="{{updateUrl}}" method="PUT" authorised="false">
<Status cardinality="required">
<option value="Approve"/>
<option value="Reject"/>
</Status>
<Hours type="decimal" cardinality="required"/>
</form>
</Timesheet>
I prefer this later approach as you don't end up with support calls for your API, with developers complaining that a particular form doesn't exist. Either way (included or filtered), if the caller invokes a form they are not permitted to, you would still respond with 403.
A bit off topic, but for completeness, HATEOAS really comes to the fore because it communicates the valid set of hypermedia controls based on the current state of the resource. e.g., when a Timesheet has been cancelled, it's not longer valid to approve/reject or update it, so a GET on a cancelled Timesheet might return
<Timesheet>
<TimesheetID>24</TimesheetID>
<Status>Cancelled</Status>
<Hours>40</Hours>
<link rel="self" href="{{selfUrl}}"/>
</Timesheet>
This clearly communicates to the caller that no further actions are permitted on this particular Timesheet.
The other thing you'll have noticed is that we haven't actually specified any or the URLs yet. They might all be all the same (e.g. /Users/{UserID}/Timesheets/{TimesheetID}) or they might be different (e.g. selfUrl=/Users/{UserID}/Timesheets/{TimesheetID}, updateURL=/Users/{UserID}/Timesheets/{TimesheetID}/update, etc).
Ultimately the caller should not care as it will use whatever is in the form/link. This provides you with great flexibility as you can change these to suit your implementation needs. For instance, if you are using Command Query Responsibility Segregation (CQRS), it might make sense to send GET requests to //readonly.myserver.com/Users/{UserID}/Timesheets/{TimesheetID} and POST, PUT and DELETE requests to //readwrite.myserver.com/Users/{UserID}/Timesheets/{TimesheetID}.

Answer 2

Yes, go with 403 Forbidden. I matches the scenario you describe. RFC 7231 says:
The 403 (Forbidden) status code indicates that the server understood
the request but refuses to authorize it. A server that wishes to
make public why the request has been forbidden can describe that
reason in the response payload (if any).
As an alternative, the server could perform those actions the current user is allowed to and ignore everything else. If this is a good idea depends on your scenarion. I woul prefer to deny the whole request and return 403 Forbidden.

Answer 3

1) You use POST to create, so you can use PUT on the same endpoint to update the data (providing the new data in the content of the request). To limit/log who updates the data you can pass their user/manager ID as a query parameter, or inside the body
2) 403 Forbidden sound better so that it's more clear for the user(manager) what has happened instead of letting him think the data was updated correctly but it was only partially updated actually