Merged in CST-12467 (pull request DSpace#45)

CST-12467 refactor qatopic to always refer to a qasource
4Science · Nov 3, 2023 · 15e407c · 15e407c
2 parents b653401 + e5ea4cf
commit 15e407c
Show file tree

Hide file tree

Showing 3 changed files with 76 additions and 33 deletions.
diff --git a/qualityassuranceevents.md b/qualityassuranceevents.md
@@ -44,15 +44,15 @@ Attributes
 * the *trust* attribute is the level of accuracy of the quality assurance event (values from 0.00 to 1.00)
 * 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
+* the *message* attribute is a json object which structure depends on the source and on the topic of the event. When the source is "openaire" and 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 (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:
@@ -63,18 +63,17 @@ Status codes:
 
 ## Search methods
 ### Get qualityassuranceevents by a given topic
-**GET /api/integration/qualityassuranceevents/search/findByTopic?topic=:topic-key[&target=:item-uuid&size=10&page=0]**
+**GET /api/integration/qualityassuranceevents/search/findByTopic?topic=:topic-key[&size=10&page=0]**
 
 It returns the list of qa events from a specific topic, eventually filtered by the target they refer to
 
 The supported parameters are:
 * page, size [see pagination](README.md#Pagination)
-* topic: mandatory, the key associated with the requested topic
-* target: optional, the uuid of the target item to restrict the qa events
+* topic: mandatory, the key associated with the requested topic. Please note that the topic could contain the uuid of a specific target item to restrict the qa events. See the note about the [qa topic id](qualityassurancetopics.md#get-single-topic)
 
 Return codes:
 * 200 OK - if the operation succeed
-* 400 Bad Request - if the topic parameter is missing or invalid
+* 400 Bad Request - if the topic parameter is missing
 
 Provide paginated list of the qa events available.
 

diff --git a/qualityassurancesources.md b/qualityassurancesources.md
@@ -23,7 +23,7 @@ Provide access to the Quality Assurance sources. It returns the list of the Qual
 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
+* id: is the identifier to use in GET Single Source. It can be composed of a source alias followed by colon : and the target uuid when the qa source data are focused on a specific item
 
 Return codes:
 * 200 OK - if the operation succeed
@@ -48,3 +48,42 @@ Return codes:
 * 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
+
+## Search methods
+### Get qualityassurancesources by a given target
+**/api/integration/qualityassurancesources/search/byTarget**
+
+It returns the list of qa sources that have events related to the specific target.
+
+```json
+...
+_embedded: {
+  qualityassurancesources:
+  [
+
+    {
+      id: "openaire:<target-uuid>",
+      type: "qualityassurancesource",
+      totalEvents: "3"
+    },
+    {
+      id: "coar-notify:<target-uuid>",
+      type: "qualityassurancesource",
+      totalEvents: "2"
+    },
+    ...
+  ]
+}
+```
+
+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
+
+
diff --git a/qualityassurancetopics.md b/qualityassurancetopics.md
@@ -2,33 +2,14 @@
 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.
+This method is not implemented as we haven't a use case that require to iterate over all the qa topics regardless of their source. Please use the search/bySource method instead.
 
-```json
-[
 
-  {
-    id: "ENRICH!MORE!PID",
-    type: "qualityassurancetopic",
-    name: "ENRICH/MORE/PID",
-    lastEvent: "2020/10/09 10:11 UTC",
-    totalSuggestions: "33"
-  },
-  {
-    id: "ENRICH!MISSING!ABSTRACT",
-    type: "qualityassurancetopic",
-    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 quality assurance events provided by Quality Assurance Broker for this topic
-* id: is the identifier to use in GET Single Topic
+* id: is the identifier to use in GET Single Topic. It is composed of the source, the topic name and optionally the target item uuid to which the data will be restricted
 
 Return codes:
 * 200 OK - if the operation succeed
@@ -42,7 +23,7 @@ Provide detailed information about a specific Quality Assurance Broker topic. Th
 
 ```json
 {
-  id: "ENRICH!MORE!PID",
+  id: "openaire:ENRICH!MORE!PID",
   type: "qualityassurancetopic",
   name: "ENRICH/MORE/PID",
   lastEvent: "2020/10/09 10:11 UTC",
@@ -60,7 +41,32 @@ Return codes:
 ### Get qualityassurancetopics by a given source
 **/api/integration/qualityassurancetopics/search/bySource**
 
-It returns the list of qa topics from a specific source
+It returns the list of qa topics from a specific source. Provide paginated list of the qa topics available.
+
+```json
+...
+_embedded: {
+  qualityassurancetopics:
+  [
+
+    {
+      id: "openaire:ENRICH!MORE!PID",
+      type: "qualityassurancetopic",
+      name: "ENRICH/MORE/PID",
+      lastEvent: "2020/10/09 10:11 UTC",
+      totalSuggestions: "33"
+    },
+    {
+      id: "openaire:ENRICH!MISSING!ABSTRACT",
+      type: "qualityassurancetopic",
+      name: "ENRICH/MISSING/ABSTRACT",
+      lastEvent: "2020/10/09 10:11 UTC",
+      totalSuggestions: "21"
+    },
+    ...
+  ]
+}
+```
 
 The supported parameters are:
 * page, size [see pagination](README.md#Pagination)
@@ -72,15 +78,14 @@ Return codes:
 * 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.
 
 ### Get qualityassurancetopics by a given target
-**GET /api/integration/qualityassurancetopics/search/byTarget?target=:item-uuid[&source=:source-id]**
+**GET /api/integration/qualityassurancetopics/search/byTarget?target=:item-uuid&source=:source-id**
 
 It returns the list of qa topics (from a specific source) to a specific targeted item.
 
 Return codes:
 * 200 OK - if the operation succeed
-* 400 Bad Request - if the target parameter is missing or invalid
+* 400 Bad Request - if the target or the source parameters are missing or invalid (the target is not an uuid)
 * 401 Unauthorized - if you are not authenticated
 * 403 Forbidden - if you are not logged in with sufficient permissions, only system administrators can access