RESTful approach for updating resource and creating associated objects

Question

I'm designing a REST-style API for a service that provides analysis of clinical data. The API allows a user to create a Patient resource. This resource provides input data to the server-side analysis.

Creation of a Patient is neither safe nor idempotent (the server assigns an ID) so POST is used, POST Patients

The Patient resource can be large, so it has sub-resources, e.g. Medications, that can be updated. Updating Medications is idempotent as the entire set of med's will be replaced, so PUT is used.

Clinical analysis is triggered by requesting POST /Patients/{patientId}/analysisResults . Alternatively, a user can request that analysis results are returned in the response of the POST /Patients request; this saves an additional HTTP round-trip.

My problem is this; users want results of the analysis included in the response to an update (PUT) to Patient/Medications - understandable as they don't want to make a second request to retrieve the results. Thus PUT Patient/Medications would be idempotent with regards to the Patient resource but not in terms of all resources as a new analysisResults sub-resource will be created. Should I:

• a) Enable this with a PUT.
• b) Enable this with a POST.
• c) Insist that a separate call is required to create new analysisResults even though this will increase the overall response times for the end-user?

Answer 1

Option C if you wish to remain RESTful.

Options A and B will most likely weaken the properties that REST is designed to give you, caching is the one that comes directly to mind.

If this is HTML based, the response will include a link to the analysisReport resource to allow the user to drive the application to somewhere useful.