Add support for a DSpace internal quality assurance source

correctiontypes.md

@@ -0,0 +1,132 @@
+# Correction Type Endpoints
+[Back to the list of all defined endpoints](endpoints.md)
+
+This endpoint contains the various types of corrections that authorized DSpace Users can suggest via the Quality Assurance Framework. The DSpace Users Corrections are indeed one of the possible [Quality Assurence Source](qualityassurancesources.md). 
+
+## Main Endpoint
+**/api/config/correctiontypes**
+
+```json
+{
+  "_embedded": {
+      "correctiontypes": [
+        {
+          "id" : "request-withdrawn",
+          "topic" : "WITHDRAWN",
+          "creationForm" : "provideReason",
+          "type" : "correctiontype",
+          "_links" : {
+            "self" : {
+              "href" : "http://localhost/api/config/correctiontypes/request-withdrawn"
+            }
+          }
+        },
+        {
+          "id" : "request-reinstate",
+          "topic" : "REINSTATE",
+          "creationForm" : "provideReason",
+          "type" : "correctiontype",
+          "_links" : {
+            "self" : {
+              "href" : "http://localhost/api/config/correctiontypes/request-reinstate"
+            }
+          }
+        }
+    ]
+  },
+  "_links": {
+    "self": {
+      "href": "https://api7.dspace.org/server/api/config/correctiontypes"
+    }
+  },
+  "page": {
+    "size": 20,
+    "totalElements": 2,
+    "totalPages": 1,
+    "number": 0
+  }
+```
+List all the available correction types in the system. The correction types are defined via the spring file `config/spring/api/correction-types.xml`
+
+A sample can be found at https://demo.dspace.org/server/#/server/api/config/correctiontypes
+
+Attributes
+* the *id* attribute is the correction type primary key
+* the *topic* attribute is the id of the [quality assurance topic](qualityassurancetopics.md) that would be created from such correction type
+* the *creationForm* attribute is used to specify the type of inputs eventually requested to create a [quality assurance event](qualityassuranceevents.md) from this correction type. If null no input is needed. The *provideReason* sample expect a textual description to be provided to create the quality assurance event.
+
+Return codes:
+* 200 OK - if the operation succeed
+* 401 Unauthorized - if you are not authenticated
+
+## Single Correction Type
+**/api/config/correctiontypes/<:id>**
+
+```json
+{
+  "id" : "request-withdrawn",
+  "topic" : "/REQUEST/WITHDRAWN",
+  "creationForm" : "requestWithdrawn",
+  "type" : "correctiontype",
+  "_links" : {
+    "self" : {
+      "href" : "http://localhost/api/config/correctiontypes/request-withdrawn"
+    }
+  }
+}
+```
+
+Status codes:
+* 200 OK - if the operation succeed
+* 401 Unauthorized - if you are not authenticated
+* 404 Not found - if no correction type exists with such id
+
+## Search methods
+### findByItem
+**/api/config/correctiontypes/search/findByItem?uuid=<:itemUUID>**
+
+This search method will return only the correction types that can be used by the current user on the specified item. So it would provide a subset of the correction types filtering out both correction types that make no sense for the specified item than correction types that are not allowed to the current user.
+Out of box a 
+
+Parameters:
+* The `uuid` uuid of the item
+
+A sample search would be `/server/api/config/correctiontypes/search/findByItem?uuid=f1ba2a86-2f67-4e36-b572-c7956cb0fa32'
+
+Assuming that the sample `config/spring/api/correction-types.xml` data model has been loaded, it would respond with
+
+```json
+{
+  "_embedded" : {
+    "correctiontypes" : [ 
+      {
+        "id" : "request-withdrawn",
+        "topic" : "/REQUEST/WITHDRAWN",
+        "creationForm" : "requestWithdrawn",
+        "type" : "correctiontype",
+        "_links" : {
+          "self" : {
+            "href" : "http://localhost/api/config/correctiontypes/request-withdrawn"
+          }
+        }
+    ]
+  },
+  "_links" : {
+    "self" : {
+      "href" : "http://localhost/api/config/correctiontypes/search/findByItem?uuid=3825e2b4-8791-4bf6-b1ea-a56d74c5a54f"
+    }
+  },
+  "page" : {
+    "size" : 20,
+    "totalElements" : 1,
+    "totalPages" : 1,
+    "number" : 0
+  }
+}
+```
+
+Return codes:
+* 200 OK - if the operation succeed
+* 400 Bad Request - if the uuid parameter is missing or is not an UUID
+* 401 Unauthorized - if you are not authenticated or if there are insufficient permissions on provided item
+* 422 Unprocessable Entity - if the Item of provided uuid not found

qualityassuranceevents.md

@@ -53,7 +53,7 @@ Attributes
 
 Exposed links:
 * topic: link to the topic to which the event belong to (see [qualityassurancetopics](qualityassurancetopics.md))
-* target: link to the item that represent the targe to whom the quality assurance event apply
+* target: link to the item that represent the target to whom the quality assurance event apply
 * related: link to an optional second item that is involved in the qa events (i.e. the project item for OpenAIRE ENRICH/MISSING/PROJECT event)
 
 Status codes:
@@ -62,6 +62,51 @@ Status codes:
 * 403 Forbidden - if you are not logged as an administrator
 * 404 Not found - if no qa event exists with such id 
 
+# POST
+### To create a new quality assurance event
+
+**POST /api/integration/qualityassuranceevents**
+
+Only events for the [Quality Assurance Source](qualityassurancesources.md) named DSpace User Corrections can be created. A new quality assurance event can be created by specifying the correctionType, the target item and an optional related item as parameters.
+The message of the quality assurance event will be provided as body of the json request.
+
+The supported parameters are:
+* correctionType: the id of the [correction type](correctiontypes.md) used to generate the quality assurance event
+* target: the uuid of the item that will be the target of the quality assurance event
+* related: (optional) the uuid of an additional item involved in the quality assurance event. Included for future extension
+
+A sample CURL command would be:
+```
+curl -i -X POST 'https://demo.dspace.org/server/#/server/api/integration/qualityassuranceevents?correctionType=request-withdrawn&target=c71c4b56-ff05-4c7f-a45f-757e2e29ced7' /
+-H 'Authorization: Bearer eyJhbGciO…' -H "Content-Type:text/json" /
+--data '{reason: "The reason for the request provided by the user"}'
+```
+
+Return codes:
+* 201 Created - if the operation succeed
+* 400 Bad Request - if the target parameter or the correctionType parameters are missing
+* 401 Unauthorized - if you are not authenticated
+* 403 Forbidden - if you are not logged in with sufficient permissions
+* 422 Unprocessable Entity - if The given correctionType in the request is not valid, the given items in the request were not valid items or the provided correctionType is not allowed for the target item, the related item is unexpected or invalid for the specified correctionType. 
+
+# DELETE
+### To delete a quality assurance event previously created
+
+**DELETE /api/integration/qualityassuranceevents/<:qualityassuranceevent-id>**
+
+Only events for the [Quality Assurance Source](qualityassurancesources.md) named DSpace User Corrections can be deleted.
+
+A sample CURL command would be:
+```
+curl -i -X DELETE 'https://demo.dspace.org/server/#/server/api/integration/qualityassuranceevents/c71c4b56-ff05-4c7f-a45f-757e2e29ced7' -H 'Authorization: Bearer eyJhbGciO…'
+```
+
+Return codes:
+* 204 No content - if the operation succeed
+* 401 Unauthorized - if you are not authenticated
+* 403 Forbidden - if you are not logged in with sufficient permissions. Only the user that has originally created the request can delete it
+* 404 Not found - if the quality assurance event doesn't exist (or was already deleted)
+
 ## Search methods
 ### Get qualityassuranceevents by a given topic
 **GET /api/integration/qualityassuranceevents/search/findByTopic?topic=:target-key[&size=10&page=0]**
@@ -78,6 +123,22 @@ Return codes:
 
 Provide paginated list of the qa events available.
 
+### Get qualityassuranceevents created by the current user
+**GET /api/integration/qualityassuranceevents/search/findByCurrentUser?target=<:item-uuid>[&size=10&page=0]**
+
+It returns the list of qa events created from the current user
+
+The supported parameters are:
+* target: mandatory. The uuid of the item target of the returned quality assurance events
+* page, size [see pagination](README.md#Pagination)
+
+Return codes:
+* 200 OK - if the operation succeed
+* 400 Bad Request - if the target parameter is missing or is not a UUID
+* 422 Unprocessable Entity - it the target parameter doesn't resolve to a valid item
+
+Provide paginated list of the qa events for the specified target item created by the current user. An empty page is returned for unauthenticated users
+
 ## PATCH 
 ### To record a decision 
 PATCH /api/integration/qualityassuranceevents/<:qualityassuranceevent-id>