Rest contracts for qaevents, qatopics and qasources endpoints

endpoints.md

@@ -41,6 +41,9 @@
 * [/api/workflow/pooltasks](pooltasks.md)
 * [/api/workflow/claimedtasks](claimedtasks.md)
 * [/api/tools/feedbacks](feedbacks.md)
+* [/api/integration/qasources](qasources.md)
+* [/api/integration/qatopics](qatopics.md)
+* [/api/integration/qaevents](qaevents.md)
 
 ## Endpoints Under Development/Discussion
 * [/api/authz/resourcepolicies](resourcepolicies.md)

qaevents.md

@@ -0,0 +1,116 @@
+## Main Endpoint
+**GET /api/integration/qaevents**
+
+_Unsupported._ The suggestions can be retrieved only by source and target or via direct link, see the single entry and search method below. 
+
+## GET Single suggestion
+** GET /api/integration/qaevents/<:qaevent-id>
+
+Return a single suggestion:
+
+```json
+{
+  "id":"123e4567-e89b-12d3-a456-426614174000",
+  "originalId": "oai:www.openstarts.units.it:10077/21486",
+  "title":"Index nominum et rerum",
+  "trust":"0.375",
+  "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: "qaevent"
+}
+```
+
+Attributes
+* the *id* attribute is the event primary key
+* the *originalId* attribute is the oai identifier of 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 suggestion
+* 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/SUBJECT/ACM: fills the `message.value` with the actual keywords, the subject classification is defined by the last part of the topic (ACM, JEL, DDC, etc.)
+    * ENRICH/MISSING/PROJECT: fills `acronym`, `code`, `funder`, `fundingProgram`, `jurisdiction` and `title`
+
+Exposed links:
+* topic: link to the topic to which the event belong to
+* target: link to the item that represent the targe to whom the suggestion apply
+* related: link to a second item that is involved in the qa events (i.e. the project item)
+
+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 qaevents by a given topic
+**/api/integration/qaevents/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/qaevents/<:qaevent-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/qaevents/<:qaevent-id>/related?item=<:item-uri>
+
+Return codes:
+* 201 Created - if the operation succeed
+* 400 Bad Request - if the qa event doesn't allow a related item (i.e. it is not related to a */PROJECT topic)
+* 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
+
+### To remove a related item to the qa event
+DELETE /api/integration/qaevents/<:qaevent-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)
+* 400 Bad Request - if the qa event doesn't allow a related item (i.e. it is not related to a */PROJECT topic)
+* 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
+
+### To replace a related item
+Replacing a related item will require deleting the related association and creating a new association hereafter

qasources.md

@@ -0,0 +1,50 @@
+## Main Endpoint
+**GET /api/integration/qasources**
+
+Provide access to the Quality Assurance sources. It returns the list of the Quality Assurance sources.
+
+```json
+[
+
+  {
+    id: "openaire",
+    type: "qasource",
+    totalEvents: "33"
+  },
+  {
+    id: "another-source",
+    type: "qasource",
+    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 suggestions 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/qasources/<:qasource-id>**
+​
+Provide detailed information about a specific Quality Assurance source. The JSON response document is as follow
+​
+```json
+{
+  id: "openaire",
+  type: "qasource",
+  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

qatopics.md

@@ -0,0 +1,74 @@
+## Main Endpoint
+**GET /api/integration/qatopics**
+
+Provide access to the Quality Assurance Broker topics. It returns the list of the Quality Assurance Broker topics.
+
+```json
+[
+
+  {
+    id: "ENRICH!MORE!PID",
+    type: "qatopic",
+    name: "ENRICH/MORE/PID",
+    lastEvent: "2020/10/09 10:11 UTC",
+    totalSuggestions: "33"
+  },
+  {
+    id: "ENRICH!MISSING!ABSTRACT",
+    type: "qatopic",
+    name: "ENRICH/MISSING/ABSTRACT",
+    lastEvent: "2020/10/09 10:11 UTC",
+    totalSuggestions: "21"
+  },
+  ...
+]
+```
+Attributes:
+* name: 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 suggestions provided by Quality Assurance Broker for this topic
+* id: is the identifier to use in GET Single 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/qatopics/<:qatopic-id>**
+​
+Provide detailed information about a specific Quality Assurance Broker topic. The JSON response document is as follow
+​
+```json
+{
+  id: "ENRICH!MORE!PID",
+  type: "qatopic",
+  name: "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 qatopics by a given source
+**/api/core/entitytypes/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.