From 9f630b7af9e731f037f1b6f6da711a20ab02d0ee Mon Sep 17 00:00:00 2001 From: Luca Giamminonni Date: Mon, 21 Feb 2022 16:33:05 +0100 Subject: [PATCH 1/7] [CST-5249] Rest contracts for nbevents, nbtopics and nvsources endpoints --- nbevents.md | 116 +++++++++++++++++++++++++++++++++++++++++++++++++++ nbsources.md | 50 ++++++++++++++++++++++ nbtopics.md | 74 ++++++++++++++++++++++++++++++++ 3 files changed, 240 insertions(+) create mode 100644 nbevents.md create mode 100644 nbsources.md create mode 100644 nbtopics.md diff --git a/nbevents.md b/nbevents.md new file mode 100644 index 00000000..c4722d52 --- /dev/null +++ b/nbevents.md @@ -0,0 +1,116 @@ +## Main Endpoint +**GET /api/integration/nbevents** + +_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/nbevents/<:nbevent-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: "nbevent" +} +``` + +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 nb 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 nb event exists with such id + +## Search methods +### Get nbevents by a given topic +**/api/integration/nbevents/search/findByTopic?topic=:target-key[&size=10&page=0]** + +It returns the list of nb 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 nb events available. + +## PATCH +### To record a decision +PATCH /api/integration/nbevents/<:nbevent-id> + +This method allow users to Accept, Reject or Discard a nb event. The PATCH body must follow the JSON PATCH specification + +```json +[ + { + "op": "replace", + "path": "/status", + "value": "ACCEPTED|REJECTED|DISCARDED|PENDING" + } +] +``` + +As response, the modified nb event will be returned. + +## POST +### To associated a related item to the nb event +POST /api/integration/nbevents/<:nbevent-id>/related?item=<:item-uri> + +Return codes: +* 201 Created - if the operation succeed +* 400 Bad Request - if the nb 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 nb event exists with such id + +### To remove a related item to the nb event +DELETE /api/integration/nbevents/<:nbevent-id>/related + +Only the association between the nb 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 nb event didn't contain a related item) +* 400 Bad Request - if the nb 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 nb 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 diff --git a/nbsources.md b/nbsources.md new file mode 100644 index 00000000..72ba5186 --- /dev/null +++ b/nbsources.md @@ -0,0 +1,50 @@ +## Main Endpoint +**GET /api/integration/nbsources** + +Provide access to the Notification sources. It returns the list of the Notification sources. + +```json +[ + + { + id: "openaire", + type: "nbsource", + totalEvents: "33" + }, + { + id: "another-source", + type: "nbsource", + lastEvent: "2020/10/09 10:11 UTC", + totalEvents: "21" + }, + ... +] +``` +Attributes: +* lastEvent: the date of the last update from the specific Notification source +* totalEvents: the total number of suggestions provided by the Notification 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/nbsources/<:nbsource-id>** +​ +Provide detailed information about a specific Notification source. The JSON response document is as follow +​ +```json +{ + id: "openaire", + type: "nbsource", + 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 \ No newline at end of file diff --git a/nbtopics.md b/nbtopics.md new file mode 100644 index 00000000..faf60836 --- /dev/null +++ b/nbtopics.md @@ -0,0 +1,74 @@ +## Main Endpoint +**GET /api/integration/nbtopics** + +Provide access to the Notification Broker topics. It returns the list of the Notification Broker topics. + +```json +[ + + { + id: "ENRICH!MORE!PID", + type: "nbtopic", + name: "ENRICH/MORE/PID", + lastEvent: "2020/10/09 10:11 UTC", + totalSuggestions: "33" + }, + { + id: "ENRICH!MISSING!ABSTRACT", + type: "nbtopic", + 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 Notification Broker +* totalEvents: the total number of suggestions provided by Notification 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/nbtopics/<:nbtopic-id>** +​ +Provide detailed information about a specific Notification Broker topic. The JSON response document is as follow +​ +```json +{ + id: "ENRICH!MORE!PID", + type: "nbtopic", + 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 nbtopics by a given source +**/api/core/entitytypes/search/bySource** + +It returns the list of nb 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 nb topics available. \ No newline at end of file From b7c393f0087f9372f5604233ef6272682044767a Mon Sep 17 00:00:00 2001 From: Luca Giamminonni Date: Mon, 4 Jul 2022 17:01:40 +0200 Subject: [PATCH 2/7] [CST-5249] Renamed NB with QA --- endpoints.md | 3 +++ nbevents.md => qaevents.md | 44 ++++++++++++++++++------------------ nbsources.md => qasources.md | 20 ++++++++-------- nbtopics.md => qatopics.md | 24 ++++++++++---------- 4 files changed, 47 insertions(+), 44 deletions(-) rename nbevents.md => qaevents.md (74%) rename nbsources.md => qasources.md (56%) rename nbtopics.md => qatopics.md (69%) diff --git a/endpoints.md b/endpoints.md index 41982300..46ff1f93 100644 --- a/endpoints.md +++ b/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) diff --git a/nbevents.md b/qaevents.md similarity index 74% rename from nbevents.md rename to qaevents.md index c4722d52..784b4453 100644 --- a/nbevents.md +++ b/qaevents.md @@ -1,10 +1,10 @@ ## Main Endpoint -**GET /api/integration/nbevents** +**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/nbevents/<:nbevent-id> +** GET /api/integration/qaevents/<:qaevent-id> Return a single suggestion: @@ -27,7 +27,7 @@ Return a single suggestion: "jurisdiction":"EU", "title":"Elliptic Pdes and Symmetry of Interfaces and Layers for Odd Nonlinearities" }, - type: "nbevent" + type: "qaevent" } ``` @@ -47,19 +47,19 @@ Attributes 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 nb events (i.e. the project item) +* 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 nb event exists with such id +* 404 Not found - if no qa event exists with such id ## Search methods -### Get nbevents by a given topic -**/api/integration/nbevents/search/findByTopic?topic=:target-key[&size=10&page=0]** +### Get qaevents by a given topic +**/api/integration/qaevents/search/findByTopic?topic=:target-key[&size=10&page=0]** -It returns the list of nb events from a specific topic +It returns the list of qa events from a specific topic The supported parameters are: * page, size [see pagination](README.md#Pagination) @@ -69,13 +69,13 @@ Return codes: * 200 OK - if the operation succeed * 400 Bad Request - if the topic parameter is missing or invalid -Provide paginated list of the nb events available. +Provide paginated list of the qa events available. ## PATCH ### To record a decision -PATCH /api/integration/nbevents/<:nbevent-id> +PATCH /api/integration/qaevents/<:qaevent-id> -This method allow users to Accept, Reject or Discard a nb event. The PATCH body must follow the JSON PATCH specification +This method allow users to Accept, Reject or Discard a qa event. The PATCH body must follow the JSON PATCH specification ```json [ @@ -87,30 +87,30 @@ This method allow users to Accept, Reject or Discard a nb event. The PATCH body ] ``` -As response, the modified nb event will be returned. +As response, the modified qa event will be returned. ## POST -### To associated a related item to the nb event -POST /api/integration/nbevents/<:nbevent-id>/related?item=<:item-uri> +### 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 nb event doesn't allow a related item (i.e. it is not related to a */PROJECT topic) +* 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 nb event exists with such id +* 404 Not found - if no qa event exists with such id -### To remove a related item to the nb event -DELETE /api/integration/nbevents/<:nbevent-id>/related +### To remove a related item to the qa event +DELETE /api/integration/qaevents/<:qaevent-id>/related -Only the association between the nb event and the related item id deleted. The related item stays untouched +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 nb event didn't contain a related item) -* 400 Bad Request - if the nb event doesn't allow a related item (i.e. it is not related to a */PROJECT topic) +* 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 nb event exists with such id +* 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 diff --git a/nbsources.md b/qasources.md similarity index 56% rename from nbsources.md rename to qasources.md index 72ba5186..5308ad65 100644 --- a/nbsources.md +++ b/qasources.md @@ -1,19 +1,19 @@ ## Main Endpoint -**GET /api/integration/nbsources** +**GET /api/integration/qasources** -Provide access to the Notification sources. It returns the list of the Notification sources. +Provide access to the Quality Assurance sources. It returns the list of the Quality Assurance sources. ```json [ { id: "openaire", - type: "nbsource", + type: "qasource", totalEvents: "33" }, { id: "another-source", - type: "nbsource", + type: "qasource", lastEvent: "2020/10/09 10:11 UTC", totalEvents: "21" }, @@ -21,8 +21,8 @@ Provide access to the Notification sources. It returns the list of the Notificat ] ``` Attributes: -* lastEvent: the date of the last update from the specific Notification source -* totalEvents: the total number of suggestions provided by the Notification source +* 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: @@ -31,14 +31,14 @@ Return codes: * 403 Forbidden - if you are not logged in with sufficient permissions, only system administrators can access ## GET Single Source -**GET /api/integration/nbsources/<:nbsource-id>** +**GET /api/integration/qasources/<:qasource-id>** ​ -Provide detailed information about a specific Notification source. The JSON response document is as follow +Provide detailed information about a specific Quality Assurance source. The JSON response document is as follow ​ ```json { id: "openaire", - type: "nbsource", + type: "qasource", totalEvents: "33" } ``` @@ -47,4 +47,4 @@ 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 \ No newline at end of file +* 404 Not found - if the source doesn't exist diff --git a/nbtopics.md b/qatopics.md similarity index 69% rename from nbtopics.md rename to qatopics.md index faf60836..381ec0e4 100644 --- a/nbtopics.md +++ b/qatopics.md @@ -1,21 +1,21 @@ ## Main Endpoint -**GET /api/integration/nbtopics** +**GET /api/integration/qatopics** -Provide access to the Notification Broker topics. It returns the list of the Notification Broker topics. +Provide access to the Quality Assurance Broker topics. It returns the list of the Quality Assurance Broker topics. ```json [ { id: "ENRICH!MORE!PID", - type: "nbtopic", + type: "qatopic", name: "ENRICH/MORE/PID", lastEvent: "2020/10/09 10:11 UTC", totalSuggestions: "33" }, { id: "ENRICH!MISSING!ABSTRACT", - type: "nbtopic", + type: "qatopic", name: "ENRICH/MISSING/ABSTRACT", lastEvent: "2020/10/09 10:11 UTC", totalSuggestions: "21" @@ -25,8 +25,8 @@ Provide access to the Notification Broker topics. It returns the list of the Not ``` Attributes: * name: the name of the topic to display on the frontend user interface -* lastEvent: the date of the last update from Notification Broker -* totalEvents: the total number of suggestions provided by Notification Broker for this topic +* 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: @@ -35,14 +35,14 @@ Return codes: * 403 Forbidden - if you are not logged in with sufficient permissions, only system administrators can access ## GET Single Topic -**GET /api/integration/nbtopics/<:nbtopic-id>** +**GET /api/integration/qatopics/<:qatopic-id>** ​ -Provide detailed information about a specific Notification Broker topic. The JSON response document is as follow +Provide detailed information about a specific Quality Assurance Broker topic. The JSON response document is as follow ​ ```json { id: "ENRICH!MORE!PID", - type: "nbtopic", + type: "qatopic", name: "ENRICH/MORE/PID", lastEvent: "2020/10/09 10:11 UTC", totalEvents: 33 @@ -56,10 +56,10 @@ Return codes: * 404 Not found - if the topic doesn't exist ## Search methods -### Get nbtopics by a given source +### Get qatopics by a given source **/api/core/entitytypes/search/bySource** -It returns the list of nb topics from a specific source +It returns the list of qa topics from a specific source The supported parameters are: * page, size [see pagination](README.md#Pagination) @@ -71,4 +71,4 @@ 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 nb topics available. \ No newline at end of file +Provide paginated list of the qa topics available. From 8760a10f0d4f131ed321d53962988a9e08afb24f Mon Sep 17 00:00:00 2001 From: Luca Giamminonni Date: Fri, 8 Jul 2022 17:29:40 +0200 Subject: [PATCH 3/7] [CST-5249] Fixed qaevent related item contract --- qaevents.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/qaevents.md b/qaevents.md index 784b4453..d623b8ce 100644 --- a/qaevents.md +++ b/qaevents.md @@ -91,14 +91,14 @@ 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> +POST /api/integration/qaevents/<:qaevent-id>/related?item=<:item-uuid> 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 +* 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/qaevents/<:qaevent-id>/related @@ -107,10 +107,10 @@ Only the association between the qa event and the related item id deleted. The r 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 +* 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 From bb703a113bdd6ec8bbac5b7fbd87fe23fed7368f Mon Sep 17 00:00:00 2001 From: Luca Giamminonni Date: Fri, 8 Jul 2022 17:37:43 +0200 Subject: [PATCH 4/7] [CST-5249] Fixed typo --- qatopics.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/qatopics.md b/qatopics.md index 381ec0e4..cf35f5b4 100644 --- a/qatopics.md +++ b/qatopics.md @@ -57,7 +57,7 @@ Return codes: ## Search methods ### Get qatopics by a given source -**/api/core/entitytypes/search/bySource** +**/api/integration/qatopics/search/bySource** It returns the list of qa topics from a specific source From e41adc8ed4375977c305827eb1b9a6c108cd3e52 Mon Sep 17 00:00:00 2001 From: Luca Giamminonni Date: Wed, 31 Aug 2022 13:08:29 +0200 Subject: [PATCH 5/7] [CST-5249] Improved Quality Assurance contracts --- qaevents.md | 34 +++++++++++++++++++++------------- qasources.md | 2 +- qatopics.md | 7 ++++--- 3 files changed, 26 insertions(+), 17 deletions(-) diff --git a/qaevents.md b/qaevents.md index d623b8ce..5544d9fb 100644 --- a/qaevents.md +++ b/qaevents.md @@ -1,12 +1,18 @@ -## Main Endpoint +# 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/qaevents** -_Unsupported._ The suggestions can be retrieved only by source and target or via direct link, see the single entry and search method below. +_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 suggestion -** GET /api/integration/qaevents/<:qaevent-id> +## GET Single quality assurance event +**GET /api/integration/qaevents/<:qaevent-id>** -Return a single suggestion: +Return a single quality assurance event: ```json { @@ -33,9 +39,9 @@ Return a single suggestion: Attributes * the *id* attribute is the event primary key -* the *originalId* attribute is the oai identifier of the target publication +* 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 suggestion +* 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 @@ -45,9 +51,9 @@ Attributes * 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) +* topic: link to the topic to which the event belong to (see [qatopics](qatopics.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 @@ -57,7 +63,7 @@ Status codes: ## Search methods ### Get qaevents by a given topic -**/api/integration/qaevents/search/findByTopic?topic=:target-key[&size=10&page=0]** +**GET /api/integration/qaevents/search/findByTopic?topic=:target-key[&size=10&page=0]** It returns the list of qa events from a specific topic @@ -91,7 +97,9 @@ 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-uuid> +**POST /api/integration/qaevents/<:qaevent-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 @@ -101,7 +109,7 @@ Return codes: * 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/qaevents/<:qaevent-id>/related +**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 diff --git a/qasources.md b/qasources.md index 5308ad65..ae95e5ee 100644 --- a/qasources.md +++ b/qasources.md @@ -22,7 +22,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 suggestions provided by the 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: diff --git a/qatopics.md b/qatopics.md index cf35f5b4..13fa92ff 100644 --- a/qatopics.md +++ b/qatopics.md @@ -1,7 +1,8 @@ ## Main Endpoint -**GET /api/integration/qatopics** +Provide access to the Quality Assurance topics. A topic represents a specific type of event (such as a missing abstract can be). -Provide access to the Quality Assurance Broker topics. It returns the list of the Quality Assurance Broker topics. +**GET /api/integration/qatopics** +It returns the list of the Quality Assurance Broker topics. ```json [ @@ -26,7 +27,7 @@ Provide access to the Quality Assurance Broker topics. It returns the list of th 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 +* 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 Return codes: From 8e885efe676afa3c41857618cf87d33470f11ae9 Mon Sep 17 00:00:00 2001 From: Luca Giamminonni Date: Wed, 9 Nov 2022 11:07:54 +0100 Subject: [PATCH 6/7] [CST-5249] Renamed qa endpoints --- endpoints.md | 6 +++--- qaevents.md => qualityassuranceevents.md | 18 +++++++++--------- qasources.md => qualityassurancesources.md | 10 +++++----- qatopics.md => qualityassurancetopics.md | 14 +++++++------- 4 files changed, 24 insertions(+), 24 deletions(-) rename qaevents.md => qualityassuranceevents.md (87%) rename qasources.md => qualityassurancesources.md (83%) rename qatopics.md => qualityassurancetopics.md (86%) diff --git a/endpoints.md b/endpoints.md index 46ff1f93..4ccd5014 100644 --- a/endpoints.md +++ b/endpoints.md @@ -41,9 +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) +* [/api/integration/qualityassurancesources](qualityassurancesources.md) +* [/api/integration/qualityassurancetopics](qualityassurancetopics.md) +* [/api/integration/qualityassuranceevents](qualityassuranceevents.md) ## Endpoints Under Development/Discussion * [/api/authz/resourcepolicies](resourcepolicies.md) diff --git a/qaevents.md b/qualityassuranceevents.md similarity index 87% rename from qaevents.md rename to qualityassuranceevents.md index 5544d9fb..b73e67a0 100644 --- a/qaevents.md +++ b/qualityassuranceevents.md @@ -5,12 +5,12 @@ Quality Assurance sources (as OpenAIRE) made available, such as missing or addit 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/qaevents** +**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/qaevents/<:qaevent-id>** +**GET /api/integration/qualityassuranceevents/<:qualityassuranceevent-id>** Return a single quality assurance event: @@ -33,7 +33,7 @@ Return a single quality assurance event: "jurisdiction":"EU", "title":"Elliptic Pdes and Symmetry of Interfaces and Layers for Odd Nonlinearities" }, - type: "qaevent" + "type": "qualityassuranceevent" } ``` @@ -51,7 +51,7 @@ Attributes * 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 [qatopics](qatopics.md)) +* 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) @@ -62,8 +62,8 @@ Status codes: * 404 Not found - if no qa event exists with such id ## Search methods -### Get qaevents by a given topic -**GET /api/integration/qaevents/search/findByTopic?topic=:target-key[&size=10&page=0]** +### 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 @@ -79,7 +79,7 @@ Provide paginated list of the qa events available. ## PATCH ### To record a decision -PATCH /api/integration/qaevents/<:qaevent-id> +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 @@ -97,7 +97,7 @@ 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-uuid>** +**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. @@ -109,7 +109,7 @@ Return codes: * 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/qaevents/<:qaevent-id>/related** +**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 diff --git a/qasources.md b/qualityassurancesources.md similarity index 83% rename from qasources.md rename to qualityassurancesources.md index ae95e5ee..a5f88d6c 100644 --- a/qasources.md +++ b/qualityassurancesources.md @@ -1,5 +1,5 @@ ## Main Endpoint -**GET /api/integration/qasources** +**GET /api/integration/qualityassurancesources** Provide access to the Quality Assurance sources. It returns the list of the Quality Assurance sources. @@ -8,12 +8,12 @@ Provide access to the Quality Assurance sources. It returns the list of the Qual { id: "openaire", - type: "qasource", + type: "qualityassurancesource", totalEvents: "33" }, { id: "another-source", - type: "qasource", + type: "qualityassurancesource", lastEvent: "2020/10/09 10:11 UTC", totalEvents: "21" }, @@ -31,14 +31,14 @@ Return codes: * 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>** +**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: "qasource", + type: "qualityassurancesource", totalEvents: "33" } ``` diff --git a/qatopics.md b/qualityassurancetopics.md similarity index 86% rename from qatopics.md rename to qualityassurancetopics.md index 13fa92ff..aec80ce5 100644 --- a/qatopics.md +++ b/qualityassurancetopics.md @@ -1,7 +1,7 @@ ## 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/qatopics** +**GET /api/integration/qualityassurancetopics** It returns the list of the Quality Assurance Broker topics. ```json @@ -9,14 +9,14 @@ It returns the list of the Quality Assurance Broker topics. { id: "ENRICH!MORE!PID", - type: "qatopic", + type: "qualityassurancetopic", name: "ENRICH/MORE/PID", lastEvent: "2020/10/09 10:11 UTC", totalSuggestions: "33" }, { id: "ENRICH!MISSING!ABSTRACT", - type: "qatopic", + type: "qualityassurancetopic", name: "ENRICH/MISSING/ABSTRACT", lastEvent: "2020/10/09 10:11 UTC", totalSuggestions: "21" @@ -36,14 +36,14 @@ Return codes: * 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>** +**GET /api/integration/qualityassurancetopics/<:qualityassurancetopic-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", + type: "qualityassurancetopic", name: "ENRICH/MORE/PID", lastEvent: "2020/10/09 10:11 UTC", totalEvents: 33 @@ -57,8 +57,8 @@ Return codes: * 404 Not found - if the topic doesn't exist ## Search methods -### Get qatopics by a given source -**/api/integration/qatopics/search/bySource** +### Get qualityassurancetopics by a given source +**/api/integration/qualityassurancetopics/search/bySource** It returns the list of qa topics from a specific source From aaa23668e7b9c602909e5054554dc654ed4a11ae Mon Sep 17 00:00:00 2001 From: frabacche Date: Mon, 18 Dec 2023 10:46:37 +0100 Subject: [PATCH 7/7] CST-5249 contract update according to backend latest implementations --- qualityassuranceevents.md | 5 +++-- qualityassurancetopics.md | 31 ++++++++++++------------------- 2 files changed, 15 insertions(+), 21 deletions(-) diff --git a/qualityassuranceevents.md b/qualityassuranceevents.md index b73e67a0..b81c185d 100644 --- a/qualityassuranceevents.md +++ b/qualityassuranceevents.md @@ -20,6 +20,7 @@ Return a single quality assurance event: "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" : { @@ -42,13 +43,13 @@ Attributes * 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/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` + * 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)) diff --git a/qualityassurancetopics.md b/qualityassurancetopics.md index aec80ce5..f3020d41 100644 --- a/qualityassurancetopics.md +++ b/qualityassurancetopics.md @@ -8,27 +8,22 @@ It returns the list of the Quality Assurance Broker topics. [ { - id: "ENRICH!MORE!PID", - type: "qualityassurancetopic", - name: "ENRICH/MORE/PID", + key: "ENRICH!MORE!PID", lastEvent: "2020/10/09 10:11 UTC", - totalSuggestions: "33" + totalEvents: "33" }, { - id: "ENRICH!MISSING!ABSTRACT", - type: "qualityassurancetopic", - name: "ENRICH/MISSING/ABSTRACT", + key: "ENRICH!MISSING!ABSTRACT", lastEvent: "2020/10/09 10:11 UTC", - totalSuggestions: "21" + totalEvents: "21" }, ... ] ``` Attributes: -* name: the name of the topic to display on the frontend user interface +* 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 -* id: is the identifier to use in GET Single Topic Return codes: * 200 OK - if the operation succeed @@ -41,15 +36,13 @@ Return codes: Provide detailed information about a specific Quality Assurance Broker topic. The JSON response document is as follow ​ ```json -{ - id: "ENRICH!MORE!PID", - type: "qualityassurancetopic", - name: "ENRICH/MORE/PID", - lastEvent: "2020/10/09 10:11 UTC", - totalEvents: 33 -} - ``` -​ + { + 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