Merge pull request #181 from 4Science/CST-5249

Rest contracts for qaevents, qatopics and qasources endpoints

endpoints.md

@@ -42,6 +42,9 @@
 * [/api/workflow/pooltasks](pooltasks.md)
 * [/api/workflow/claimedtasks](claimedtasks.md)
 * [/api/tools/feedbacks](feedbacks.md)
+* [/api/integration/qualityassurancesources](qualityassurancesources.md)
+* [/api/integration/qualityassurancetopics](qualityassurancetopics.md)
+* [/api/integration/qualityassuranceevents](qualityassuranceevents.md)
 * [/api/authz/resourcepolicies](resourcepolicies.md)
 * [/api/config/bulkaccessconditionoptions](bulkaccessconditionoptions.md)
 * [/api/authz/authorizations](authorizations.md)

qualityassuranceevents.md

@@ -0,0 +1,125 @@
+# Quality Assurance Events endpoint
+The Quality Assurance feature aims to improve existing data in the repository using feedback that 
+Quality Assurance sources (as OpenAIRE) made available, such as missing or additional metadata (abstract, subjects, PIDs, projects).
+
+These endpoints provide access to the quality assurance events so that they can be reviewed and managed by the repository manager.
+
+## GET All quality assurance events
+**GET /api/integration/qualityassuranceevents**
+
+_Unsupported._ The quality assurance events can be retrieved only by source and target or via direct link, see the single entry and search method below. 
+
+## GET Single quality assurance event
+**GET /api/integration/qualityassuranceevents/<:qualityassuranceevent-id>**
+
+Return a single quality assurance event:
+
+```json
+{
+  "id":"123e4567-e89b-12d3-a456-426614174000",
+  "originalId": "oai:www.openstarts.units.it:10077/21486",
+  "title":"Index nominum et rerum",
+  "trust":"0.375",
+  "topic":"ENRICH/MISSING/ABSTRACT",
+  "eventDate": "2020/10/09 10:11 UTC",
+  "status": "PENDING",
+  "message" : {
+    "type":"doi",
+    "value":"10.18848/1447-9494/cgp/v15i09/45934",
+    "abstracts":"Abstract Complex functionality of the ...",
+    "acronym":"EPSILON",
+    "code":"277749",
+    "funder":"EC",
+    "fundingProgram":"FP7",
+    "jurisdiction":"EU",
+    "title":"Elliptic Pdes and Symmetry of Interfaces and Layers for Odd Nonlinearities"
+  },
+  "type": "qualityassuranceevent"
+}
+```
+
+Attributes
+* the *id* attribute is the event primary key
+* the *originalId* attribute is the identifier used by the event's source for the target publication
+* the *title* attribute is the title of the publication as provided by the correction's source
+* the *trust* attribute is the level of accuracy of the quality assurance event (values from 0.00 to 1.00)
+* the *topic* attribute is the name of the topic of the event
+* the *status* attribute is one of (ACCEPTED, REJECTED, DISCARDED, PENDING)
+* the *eventDate* attribute is the timestamp of the event reception
+* the *message* attribute is a json object which structure depends on the source and on the topic of the event. When the "topic" type is
+    * ENRICH/MISSING/PID and ENRICH/MORE/PID: fills `message.type` with the type of persistent identifier (doi, pmid, etc.) and `message.value` with the corresponding value
+    * ENRICH/MISSING/ABSTRACT: fills `message.abstract`
+    * ENRICH/MISSING/PROJECT and ENRICH/MORE/PROJECT: fills `acronym`, `code`, `funder`, `fundingProgram`, `jurisdiction` and `title`
+
+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
+* 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:
+* 200 Ok - if the operation succeed
+* 401 Unauthorized - if you are not authenticated
+* 403 Forbidden - if you are not logged as an administrator
+* 404 Not found - if no qa event exists with such id 
+
+## Search methods
+### Get qualityassuranceevents by a given topic
+**GET /api/integration/qualityassuranceevents/search/findByTopic?topic=:target-key[&size=10&page=0]**
+
+It returns the list of qa events from a specific topic
+
+The supported parameters are:
+* page, size [see pagination](README.md#Pagination)
+* topic: mandatory, the key associated with the requested topic
+
+Return codes:
+* 200 OK - if the operation succeed
+* 400 Bad Request - if the topic parameter is missing or invalid
+
+Provide paginated list of the qa events available.
+
+## PATCH 
+### To record a decision 
+PATCH /api/integration/qualityassuranceevents/<:qualityassuranceevent-id>
+
+This method allow users to Accept, Reject or Discard a qa event. The PATCH body must follow the JSON PATCH specification
+
+```json
+[
+  {
+    "op": "replace",
+    "path": "/status",
+    "value": "ACCEPTED|REJECTED|DISCARDED|PENDING"
+  }
+]
+```
+
+As response, the modified qa event will be returned.
+
+## POST
+### To associated a related item to the qa event
+**POST /api/integration/qualityassuranceevents/<:qualityassuranceevent-id>/related?item=<:item-uuid>**
+
+This endpoint allows you to associate an associated item with the event, if the type of event supports it.
+
+Return codes:
+* 201 Created - if the operation succeed
+* 401 Unauthorized - if you are not authenticated
+* 403 Forbidden - if you are not logged as an administrator
+* 404 Not found - if no qa event exists with such id
+* 422 Unprocessable entity - if the qa event doesn't allow a related item (for example it is an openaire event not related to a */PROJECT topic)
+
+### To remove a related item to the qa event
+**DELETE /api/integration/qualityassuranceevents/<:qualityassuranceevent-id>/related**
+
+Only the association between the qa event and the related item id deleted. The related item stays untouched
+
+Return codes:
+* 204 No content - if the delete succeeded (including the case of no-op if the qa event didn't contain a related item)
+* 401 Unauthorized - if you are not authenticated
+* 403 Forbidden - if you are not logged as an administrator
+* 404 Not found - if no qa event exists with such id
+* 422 Unprocessable entity - if the qa event doesn't allow a related item (i.e. it is not related to a */PROJECT topic)
+
+### To replace a related item
+Replacing a related item will require deleting the related association and creating a new association hereafter

qualityassurancesources.md

@@ -0,0 +1,50 @@
+## Main Endpoint
+**GET /api/integration/qualityassurancesources**
+
+Provide access to the Quality Assurance sources. It returns the list of the Quality Assurance sources.
+
+```json
+[
+
+  {
+    id: "openaire",
+    type: "qualityassurancesource",
+    totalEvents: "33"
+  },
+  {
+    id: "another-source",
+    type: "qualityassurancesource",
+    lastEvent: "2020/10/09 10:11 UTC",
+    totalEvents: "21"
+  },
+  ...
+]
+```
+Attributes:
+* lastEvent: the date of the last update from the specific Quality Assurance source
+* totalEvents: the total number of quality assurance events provided by the Quality Assurance source
+* id: is the identifier to use in GET Single Source
+
+Return codes:
+* 200 OK - if the operation succeed
+* 401 Unauthorized - if you are not authenticated
+* 403 Forbidden - if you are not logged in with sufficient permissions, only system administrators can access
+
+## GET Single Source
+**GET /api/integration/qualityassurancesources/<:qualityassurancesource-id>**
+​
+Provide detailed information about a specific Quality Assurance source. The JSON response document is as follow
+​
+```json
+{
+  id: "openaire",
+  type: "qualityassurancesource",
+  totalEvents: "33"
+}
+ ```
+​
+Return codes:
+* 200 OK - if the operation succeed
+* 401 Unauthorized - if you are not authenticated
+* 403 Forbidden - if you are not logged in with sufficient permissions, only system administrators can access
+* 404 Not found - if the source doesn't exist

qualityassurancetopics.md

@@ -0,0 +1,68 @@
+## Main Endpoint
+Provide access to the Quality Assurance topics. A topic represents a specific type of event (such as a missing abstract can be).
+
+**GET /api/integration/qualityassurancetopics**
+It returns the list of the Quality Assurance Broker topics.
+
+```json
+[
+
+  {
+    key: "ENRICH!MORE!PID",
+    lastEvent: "2020/10/09 10:11 UTC",
+    totalEvents: "33"
+  },
+  {
+    key: "ENRICH!MISSING!ABSTRACT",
+    lastEvent: "2020/10/09 10:11 UTC",
+    totalEvents: "21"
+  },
+  ...
+]
+```
+Attributes:
+* key: the name of the topic to display on the frontend user interface
+* lastEvent: the date of the last update from Quality Assurance Broker
+* totalEvents: the total number of quality assurance events provided by Quality Assurance Broker for this topic
+
+Return codes:
+* 200 OK - if the operation succeed
+* 401 Unauthorized - if you are not authenticated
+* 403 Forbidden - if you are not logged in with sufficient permissions, only system administrators can access
+
+## GET Single Topic
+**GET /api/integration/qualityassurancetopics/<:qualityassurancetopic-id>**
+​
+Provide detailed information about a specific Quality Assurance Broker topic. The JSON response document is as follow
+​
+```json
+  {
+    key: "ENRICH!MORE!PID",
+    lastEvent: "2020/10/09 10:11 UTC",
+    totalEvents: "33"
+  }
+```
+
+Return codes:
+* 200 OK - if the operation succeed
+* 401 Unauthorized - if you are not authenticated
+* 403 Forbidden - if you are not logged in with sufficient permissions, only system administrators can access
+* 404 Not found - if the topic doesn't exist
+
+## Search methods
+### Get qualityassurancetopics by a given source
+**/api/integration/qualityassurancetopics/search/bySource**
+
+It returns the list of qa topics from a specific source
+
+The supported parameters are:
+* page, size [see pagination](README.md#Pagination)
+* source: mandatory, the name associated with a specific source
+
+Return codes:
+* 200 OK - if the operation succeed
+* 400 Bad Request - if the topic parameter is missing or invalid
+* 401 Unauthorized - if you are not authenticated
+* 403 Forbidden - if you are not logged in with sufficient permissions, only system administrators can access
+
+Provide paginated list of the qa topics available.