diff --git a/endpoints.md b/endpoints.md index 1b62ad3a..899a875a 100644 --- a/endpoints.md +++ b/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) diff --git a/qualityassuranceevents.md b/qualityassuranceevents.md new file mode 100644 index 00000000..b81c185d --- /dev/null +++ b/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 diff --git a/qualityassurancesources.md b/qualityassurancesources.md new file mode 100644 index 00000000..a5f88d6c --- /dev/null +++ b/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 diff --git a/qualityassurancetopics.md b/qualityassurancetopics.md new file mode 100644 index 00000000..f3020d41 --- /dev/null +++ b/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.