DS-3851 initial proposal for the workflow endpoints

[abollini]

This is a starting point proposal for the contract of the workflow endpoints in the new REST API.
The implementation of a workflow state machine actions is widely debated question and there are lot of discussion about the best way to implement them in a RESTful way or criticism about which implementation is not really RESTful.
This is a good summary of the different possible approaches
http://www.kennethlange.com/posts/Modeling-Workflows-in-REST-APIs.html

these are also useful resource to listen different opinions, pro and contros
https://restful-api-design.readthedocs.io/en/latest/methods.html#actions
interagent/http-api-design#58
https://www.gvj-web.com/blog/custom-actions-your-rest-api

At the end my preferred approach is in the middle between the approach "2. Transition Links" and "3. Transition Subresource" of the above summary.

We have explicit tasks resources that help us to drive the state change. We can POST on such resources and DELETE tasks. At the start I was uncertain about the use of POST but it should be noted that POST doesn't allow the client to expect to be able to make a subsequent GET request on the same resource to retrieve the data that was sent, so it is the right http verb compared to PUT.

On the proposed contract I don't like the way that "command" are executed on the existent workflow action. For instance we have an action state name "editaction" in the dspace xml workflow that can receive two commands: approve or reject. There is no standard way to know which commands are allowed for which action state. I plan to fix that later introducing subresources so that on a specific tasks the client known which are the available commands i.e.

• /api/claimedtasks/1/approve
• /api/claimedtasks/1/reject

Anyway, I have preferred to share the current contract that we are implementing to provide initial workflow capabilities in DSpace 7 to start the discussion.

[abollini]

Required improvements tracked as #22
merge was agreed on 1st march (https://wiki.duraspace.org/display/DSPACE/2018-03-01+DSpace+7+Working+Group+Meeting+notes?src=contextnavpagetreemode ) but never done