From 6ade12085e99fb86547b00909cd15c89e4f6e07f Mon Sep 17 00:00:00 2001 From: Luca Giamminonni Date: Wed, 4 May 2022 15:13:49 +0200 Subject: [PATCH 1/4] [CST-5249] Added suggestions rest contracts --- endpoints.md | 3 + suggestions.md | 228 +++++++++++++++++++++++++++++++++++++++++++ suggestionsources.md | 42 ++++++++ suggestiontargets.md | 196 +++++++++++++++++++++++++++++++++++++ 4 files changed, 469 insertions(+) create mode 100644 suggestions.md create mode 100644 suggestionsources.md create mode 100644 suggestiontargets.md diff --git a/endpoints.md b/endpoints.md index f22a6344..a5829d86 100644 --- a/endpoints.md +++ b/endpoints.md @@ -37,6 +37,9 @@ * [/api/workflow/pooltasks](pooltasks.md) * [/api/workflow/claimedtasks](claimedtasks.md) * [/api/tools/feedbacks](feedbacks.md) +* [/api/integration/suggestions](suggestions.md) +* [/api/integration/suggestionsources](suggestionsources.md) +* [/api/integration/suggestiontargets](suggestiontargets.md) ## Endpoints Under Development/Discussion * [/api/authz/resourcepolicies](resourcepolicies.md) diff --git a/suggestions.md b/suggestions.md new file mode 100644 index 00000000..4f8c4e43 --- /dev/null +++ b/suggestions.md @@ -0,0 +1,228 @@ +# Suggestions Endpoints +[Back to the list of all defined endpoints](endpoints.md) + +## Main Endpoint +**/api/integration/suggestions** + +_Unsupported._ The suggestions can be retrieved only by source and target or via direct link, see the single entry and search method below. + +### single entry +**GET api/integration/suggestions/<:suggestion-id>** + +It returns the data from one suggestion. The suggestion-id is a String generated by the source, as it must be unique for source, target and identified object to be imported it is usually represented by a combination of such elements + +sample for a suggestion /api/integration/suggestions/reciter:gf3d657-9d6d-4a87-b905-fef0f8cae26:24694772 +```json +{ + "id": "reciter:gf3d657-9d6d-4a87-b905-fef0f8cae26:24694772", + "display": "publication one", + "source": "reciter", + "score": "62.7", + "external-source-uri": "https://dspace7.4science.cloud/server/api/integration/reciterSourcesEntry/pubmed/entryValues/24694772", + "evidences": { + "acceptedRejectedEvidence": { + "score": "2.7", + "notes": "some notes, eventually empty or null" + }, + "authorNameEvidence": { + "score": "0", + "notes": "some notes, eventually empty or null" + }, + "journalCategoryEvidence": { + "score": "6", + "notes": "some notes, eventually empty or null" + }, + "affiliationEvidence": { + "score": "23.7", + "notes": "some notes, eventually empty or null" + }, + "relationshipEvidence": { + "score": "9", + "notes": "some notes, eventually empty or null" + }, + "educationYearEvidence": { + "score": "3.6", + "notes": "some notes, eventually empty or null" + }, + "personTypeEvidence": { + "score": "4", + "notes": "some notes, eventually empty or null" + }, + "articleCountEvidence": { + "score": "6.7", + "notes": "some notes, eventually empty or null" + }, + "averageClusteringEvidence": { + "score": "7", + "notes": "some notes, eventually empty or null" + } + }, + "metadata": { + "dc.identifier.uri": [ + { + "value": "https://publication/0000-0003-3681-2038", + "language": null, + "authority": null, + "confidence": -1, + "place": -1 + } + ], + "dc.title" : [ + { + "value" : "publication one", + "language" : null, + "authority" : null, + "confidence" : -1 + } + ], + "dc.date.issued" : [ + { + "value" : "2010-11-03", + "language" : null, + "authority" : null, + "confidence" : -1 + } + ] + }, + "type": "suggestion", + "_links": { + "target": { + "href": "https://dspace7.4science.cloud/server/api/core/items/gf3d657-9d6d-4a87-b905-fef0f8cae26" + }, + "self": { + "href": "https://dspace7.4science.cloud/server/api/integration/suggestions/reciter:gf3d657-9d6d-4a87-b905-fef0f8cae26:24694772" + } + } +} +``` + +## Search methods +### Get suggestions by a given target +**/api/integration/suggestions/search/findByTargetAndSource?target=:target-uuid&source=:source-key[&size=10&page=0]** + +It returns the list of suggestions and corresponding evidence from a specific source for the requested individual/target + +The supported parameters are: +* page, size [see pagination](README.md#Pagination). Data can be sorted by trust desc (default) or asc. Please note that the sort parameter must use the word trust instead than score for the sorting as score have a reserved meaning +* target: mandatory, the uuid associated with your target profile +* source: mandatory, the key of the source that you want to query for suggestion + +Return codes: +* 200 OK - if the operation succeed +* 400 Bad Request - if the uuid parameter is missing or invalid + +sample for a search /server/api/integration/suggestions/search/findByTargetAndSource?target=gf3d657-9d6d-4a87-b905-fef0f8cae26c&source=reciter +```json +{ + "_embedded": { + "reciterSourceEntries": [ +{ + "id": "24694772", + "display": "publication one", + "source": "reciter", + "external-source-uri": "https://dspace7.4science.cloud/server/api/integration/reciterSourcesEntry/pubmed/entryValues/24694772", + "evidences": { + "acceptedRejectedEvidence": { + "score": "2.7", + "notes": "some notes, eventually empty or null" + }, + "authorNameEvidence": { + "score": "0", + "notes": "some notes, eventually empty or null" + }, + "journalCategoryEvidence": { + "score": "6", + "notes": "some notes, eventually empty or null" + }, + "affiliationEvidence": { + "score": "xxx", + "notes": "some notes, eventually empty or null" + }, + "relationshipEvidence": { + "score": "9", + "notes": "some notes, eventually empty or null" + }, + "educationYearEvidence": { + "score": "3.6", + "notes": "some notes, eventually empty or null" + }, + "personTypeEvidence": { + "score": "4", + "notes": "some notes, eventually empty or null" + }, + "articleCountEvidence": { + "score": "6.7", + "notes": "some notes, eventually empty or null" + }, + "averageClusteringEvidence": { + "score": "7", + "notes": "some notes, eventually empty or null" + } + }, + "metadata": { + "dc.identifier.uri": [ + { + "value": "https://publication/0000-0003-3681-2038", + "language": null, + "authority": null, + "confidence": -1, + "place": -1 + } + ], + "dc.title" : [ + { + "value" : "publication one", + "language" : null, + "authority" : null, + "confidence" : -1 + } + ], + "dc.date.issued" : [ + { + "value" : "2010-11-03", + "language" : null, + "authority" : null, + "confidence" : -1 + } + ] + }, + "type": "suggestion", + "_links": { + "target": { + "href": "https://dspace7.4science.cloud/server/api/core/items/gf3d657-9d6d-4a87-b905-fef0f8cae26" + }, + "self": { + "href": "https://dspace7.4science.cloud/server/api/integration/suggestions/reciter:gf3d657-9d6d-4a87-b905-fef0f8cae26c:24694772" + } + } + } + ] + }, + "_links": { + "self": { + "href": "https://dspace7.4science.cloud/server/api/integration/suggestions/search/findByTargetAndSource?target=gf3d657-9d6d-4a87-b905-fef0f8cae26c&source=reciter" + } + }, + "page": { + "size": 20, + "totalElements": 1, + "totalPages": 1, + "number": 0 + } +} +``` + +## Import suggestion + +See the [WorkspaceItem endpoint](workspaceitems.md#Multipart-POST-Method) for details on how to import a suggestion + +## Discard suggestion +**DELETE api/integration/suggestions/<:suggestion-id>** + +This discard the given suggestion. The endpoint is restricted to owners of the suggestion target and administrators + +Status codes: +* 204 No content - if the operation succeed +* 401 Unauthorized - if you are not authenticated +* 403 Forbidden - if you are not logged in with sufficient permissions +* 404 Not found - if the suggestion doesn't exist (or was already discarded) diff --git a/suggestionsources.md b/suggestionsources.md new file mode 100644 index 00000000..06696ca5 --- /dev/null +++ b/suggestionsources.md @@ -0,0 +1,42 @@ +# Suggestion Sources Endpoints +[Back to the list of all defined endpoints](endpoints.md) + +## Main Endpoint +**/api/integration/suggestionsources** + +It returns a paginated list of suggestion sources. All the sources are returned regardless to the existence or less of suggestions. This endpoint is reserved to administrators + +### single entry +**GET api/integration/suggestionsources/<:source-key>** + +It returns the data from a specific source. This endpoint is reserved to administrators + +sample for a source /api/integration/suggestionsources/reciter +```json +{ + "id": "reciter", + "total": 2, + "type": "suggestionsource", + "_links": { + "suggestiontargets": { + "href": "https://dspace7.4science.cloud/server/api/integration/suggestiontargets/search/findBySource?source=reciter" + }, + "self": { + "href": "https://dspace7.4science.cloud/server/api/integration/suggestionsources/reciter" + } + } +} +``` + +Attributes +* the *id* attribute is the key that identify the source +* the *total* attribute is the number of target with suggestions. It can be 0 if there are no target with suggestions + +Exposed links: +* suggestiontargets: link to the suggestion targets entries + +Status 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 +* 404 Not found - if the source doesn't exist or is not active in the system (when 403 doesn't apply) diff --git a/suggestiontargets.md b/suggestiontargets.md new file mode 100644 index 00000000..9ddd6984 --- /dev/null +++ b/suggestiontargets.md @@ -0,0 +1,196 @@ +# Suggestion Targets Endpoints +[Back to the list of all defined endpoints](endpoints.md) + +## Main Endpoint +**/api/integration/suggestiontargets** + +_Unsupported._ The suggestion targets can be retrieved only by source or by target, see the search methods below. + +### single entry +**GET api/integration/suggestiontargets/** + +It returns the data from one target. This endpoint is accessible to the owner of the target profile and to the administrators + +sample for a suggestion /api/integration/suggestiontargets/scopus:nhy567-9d6d-ty67-b905-fef0f8cae26 +```json +{ + "id": "scopus:nhy567-9d6d-ty67-b905-fef0f8cae26", + "display": "Digilio, Giuseppe", + "source": "scopus", + "total": 3, + "type": "suggestiontarget", + "_links": { + "target": { + "href": "https://dspace7.4science.cloud/server/api/core/items/nhy567-9d6d-ty67-b905-fef0f8cae26" + }, + "suggestions": { + "href": "https://dspace7.4science.cloud/server/api/integration/suggestions/search/findByTargetAndSource?target=nhy567-9d6d-ty67-b905-fef0f8cae26" + }, + "self": { + "href": "https://dspace7.4science.cloud/server/api/integration/suggestiontargets/scopus:nhy567-9d6d-ty67-b905-fef0f8cae26" + } + } +} +``` + +Attributes +* the *display* attribute is the preferred name of the linked Person +* the *source* attribute is the key that identifies the source of the suggestion +* the *total* attribbute is the number of related suggestions. Must be greater than 0 + +Exposed links: +* target: link to the items that represent the person to whom the suggestions are proposed +* suggestions: link to the suggestions entries + +Status 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 +* 404 Not found - if there are no suggestions for the requested profile (when 403 doesn't apply) + + +### Search methods +#### findBySource +**/api/integration/suggestiontargets/search/findBySource?source=<:source>** + +The supported parameters are: +* page, size [see pagination](README.md#Pagination) +* source: mandatory, the key that identify the source to query + +It returns the list of targets with their suggestion count for the specified source. Only targets that have at least one suggestion are returned. This endpoint is reserved to administrators + +Example: +```json +{ + "_embedded": { + "suggestiontargets": [ + { + "id": "reciter:gf3d657-9d6d-4a87-b905-fef0f8cae26", + "display": "Bollini, Andrea", + "source": "reciter", + "total": 31, + "type": "suggestiontarget", + "_links": { + "target": { + "href": "https://dspace7.4science.cloud/server/api/core/items/gf3d657-9d6d-4a87-b905-fef0f8cae26" + }, + "suggestions": { + "href": "https://dspace7.4science.cloud/server/api/integration/suggestions/search/findByTargetAndSource?target=gf3d657-9d6d-4a87-b905-fef0f8cae26c&source=reciter" + }, + "self": { + "href": "https://dspace7.4science.cloud/server/api/integration/suggestiontargets/reciter:gf3d657-9d6d-4a87-b905-fef0f8cae26" + } + } + }, + { + "id": "reciter:nhy567-9d6d-ty67-b905-fef0f8cae26", + "display": "Digilio, Giuseppe", + "source": "reciter", + "total": 12, + "type": "suggestiontarget", + "_links": { + "target": { + "href": "https://dspace7.4science.cloud/server/api/core/items/nhy567-9d6d-ty67-b905-fef0f8cae26" + }, + "suggestions": { + "href": "https://dspace7.4science.cloud/server/api/integration/suggestions/search/findByTargetAndSource?target=nhy567-9d6d-ty67-b905-fef0f8cae26&source=reciter" + }, + "self": { + "href": "https://dspace7.4science.cloud/server/api/integration/suggestiontargets/reciter:nhy567-9d6d-ty67-b905-fef0f8cae26" + } + } + } + ] + }, + "_links": { + "self": { + "href": "https://dspace7.4science.cloud/server/api/integration/suggestiontargets/search/findBySource?source=reciter" + } + }, + "page": { + "size": 20, + "totalElements": 2, + "totalPages": 1, + "number": 0 + } +} +``` + +Status codes: +* 200 Ok - if the operation succeed +* 400 Bad Request - if the source parameter is missing +* 401 Unauthorized - if you are not authenticated +* 403 Forbidden - if you are not logged in as an administrator + +#### findByTarget +**/api/integration/suggestiontargets/search/findByTarget?target=<:target-uuid>** + +The supported parameters are: +* page, size [see pagination](README.md#Pagination) +* target: mandatory, the uuid that identify the target profile + +It returns the list of targets with their suggestion count for the specified profile. Only suggestion targets that have at least one suggestion are returned. This endpoint is reserved to administrators and the owner of the target profile + +Example: +```json +{ + "_embedded": { + "suggestiontargets": [ + { + "id": "reciter:gf3d657-9d6d-4a87-b905-fef0f8cae26", + "display": "Bollini, Andrea", + "source": "reciter", + "total": 31, + "type": "suggestiontarget", + "_links": { + "target": { + "href": "https://dspace7.4science.cloud/server/api/core/items/gf3d657-9d6d-4a87-b905-fef0f8cae26" + }, + "suggestions": { + "href": "https://dspace7.4science.cloud/server/api/integration/suggestions/search/findByTargetAndSource?target=gf3d657-9d6d-4a87-b905-fef0f8cae26c&source=reciter" + }, + "self": { + "href": "https://dspace7.4science.cloud/server/api/integration/suggestiontargets/reciter:gf3d657-9d6d-4a87-b905-fef0f8cae26" + } + } + }, + { + "id": "scopus:gf3d657-9d6d-4a87-b905-fef0f8cae26", + "display": "Bollini, Andrea", + "source": "scopus", + "total": 11, + "type": "suggestiontarget", + "_links": { + "target": { + "href": "https://dspace7.4science.cloud/server/api/core/items/gf3d657-9d6d-4a87-b905-fef0f8cae26" + }, + "suggestions": { + "href": "https://dspace7.4science.cloud/server/api/integration/suggestions/search/findByTargetAndSource?target=gf3d657-9d6d-4a87-b905-fef0f8cae26&source=scopus" + }, + "self": { + "href": "https://dspace7.4science.cloud/server/api/integration/suggestiontargets/scopus:gf3d657-9d6d-4a87-b905-fef0f8cae26" + } + } + } + ] + }, + "_links": { + "self": { + "href": "https://dspace7.4science.cloud/server/api/integration/suggestiontargets/search/findByTarget?target=gf3d657-9d6d-4a87-b905-fef0f8cae26" + } + }, + "page": { + "size": 20, + "totalElements": 2, + "totalPages": 1, + "number": 0 + } +} +``` + +Status codes: +* 200 Ok - if the operation succeed +* 204 No Content - if no suggestion targets are available for the specified profile +* 400 Bad Request - if the target parameter is missing or invalid +* 401 Unauthorized - if you are not authenticated +* 403 Forbidden - if you are not logged in with sufficient permissions From c189f70cbedc8932e019a83a007a8eebe2fb18d2 Mon Sep 17 00:00:00 2001 From: frabacche Date: Thu, 15 Feb 2024 15:19:14 +0100 Subject: [PATCH 2/4] CST-5249_suggestion alignment to the backend implementation --- suggestions.md | 16 ++++++++-------- suggestionsources.md | 5 +---- suggestiontargets.md | 36 ++++++++++++++++++------------------ 3 files changed, 27 insertions(+), 30 deletions(-) diff --git a/suggestions.md b/suggestions.md index 4f8c4e43..becefbd1 100644 --- a/suggestions.md +++ b/suggestions.md @@ -18,7 +18,7 @@ sample for a suggestion /api/integration/suggestions/reciter:gf3d657-9d6d-4a87-b "display": "publication one", "source": "reciter", "score": "62.7", - "external-source-uri": "https://dspace7.4science.cloud/server/api/integration/reciterSourcesEntry/pubmed/entryValues/24694772", + "externalSourceUri": "https://demo.dspace.org/server/api/integration/reciterSourcesEntry/pubmed/entryValues/24694772", "evidences": { "acceptedRejectedEvidence": { "score": "2.7", @@ -87,10 +87,10 @@ sample for a suggestion /api/integration/suggestions/reciter:gf3d657-9d6d-4a87-b "type": "suggestion", "_links": { "target": { - "href": "https://dspace7.4science.cloud/server/api/core/items/gf3d657-9d6d-4a87-b905-fef0f8cae26" + "href": "https://demo.dspace.org/server/api/core/items/gf3d657-9d6d-4a87-b905-fef0f8cae26" }, "self": { - "href": "https://dspace7.4science.cloud/server/api/integration/suggestions/reciter:gf3d657-9d6d-4a87-b905-fef0f8cae26:24694772" + "href": "https://demo.dspace.org/server/api/integration/suggestions/reciter:gf3d657-9d6d-4a87-b905-fef0f8cae26:24694772" } } } @@ -115,12 +115,12 @@ sample for a search /server/api/integration/suggestions/search/findByTargetAndSo ```json { "_embedded": { - "reciterSourceEntries": [ + "suggestions": [ { "id": "24694772", "display": "publication one", "source": "reciter", - "external-source-uri": "https://dspace7.4science.cloud/server/api/integration/reciterSourcesEntry/pubmed/entryValues/24694772", + "externalSourceUri": "https://demo.dspace.org/server/api/integration/reciterSourcesEntry/pubmed/entryValues/24694772", "evidences": { "acceptedRejectedEvidence": { "score": "2.7", @@ -189,10 +189,10 @@ sample for a search /server/api/integration/suggestions/search/findByTargetAndSo "type": "suggestion", "_links": { "target": { - "href": "https://dspace7.4science.cloud/server/api/core/items/gf3d657-9d6d-4a87-b905-fef0f8cae26" + "href": "https://demo.dspace.org/server/api/core/items/gf3d657-9d6d-4a87-b905-fef0f8cae26" }, "self": { - "href": "https://dspace7.4science.cloud/server/api/integration/suggestions/reciter:gf3d657-9d6d-4a87-b905-fef0f8cae26c:24694772" + "href": "https://demo.dspace.org/server/api/integration/suggestions/reciter:gf3d657-9d6d-4a87-b905-fef0f8cae26c:24694772" } } } @@ -200,7 +200,7 @@ sample for a search /server/api/integration/suggestions/search/findByTargetAndSo }, "_links": { "self": { - "href": "https://dspace7.4science.cloud/server/api/integration/suggestions/search/findByTargetAndSource?target=gf3d657-9d6d-4a87-b905-fef0f8cae26c&source=reciter" + "href": "https://demo.dspace.org/server/api/integration/suggestions/search/findByTargetAndSource?target=gf3d657-9d6d-4a87-b905-fef0f8cae26c&source=reciter" } }, "page": { diff --git a/suggestionsources.md b/suggestionsources.md index 06696ca5..66191975 100644 --- a/suggestionsources.md +++ b/suggestionsources.md @@ -18,9 +18,6 @@ sample for a source /api/integration/suggestionsources/reciter "total": 2, "type": "suggestionsource", "_links": { - "suggestiontargets": { - "href": "https://dspace7.4science.cloud/server/api/integration/suggestiontargets/search/findBySource?source=reciter" - }, "self": { "href": "https://dspace7.4science.cloud/server/api/integration/suggestionsources/reciter" } @@ -33,7 +30,7 @@ Attributes * the *total* attribute is the number of target with suggestions. It can be 0 if there are no target with suggestions Exposed links: -* suggestiontargets: link to the suggestion targets entries + Status codes: * 200 Ok - if the operation succeed diff --git a/suggestiontargets.md b/suggestiontargets.md index 9ddd6984..451367ac 100644 --- a/suggestiontargets.md +++ b/suggestiontargets.md @@ -4,7 +4,7 @@ ## Main Endpoint **/api/integration/suggestiontargets** -_Unsupported._ The suggestion targets can be retrieved only by source or by target, see the search methods below. +_Unsupported._ The suggestion targets can be retrieved only by target and/or by source, see the search methods below. ### single entry **GET api/integration/suggestiontargets/** @@ -21,13 +21,13 @@ sample for a suggestion /api/integration/suggestiontargets/scopus:nhy567-9d6d-ty "type": "suggestiontarget", "_links": { "target": { - "href": "https://dspace7.4science.cloud/server/api/core/items/nhy567-9d6d-ty67-b905-fef0f8cae26" + "href": "https://demo.dspace.org/server/api/core/items/nhy567-9d6d-ty67-b905-fef0f8cae26" }, "suggestions": { - "href": "https://dspace7.4science.cloud/server/api/integration/suggestions/search/findByTargetAndSource?target=nhy567-9d6d-ty67-b905-fef0f8cae26" + "href": "https://demo.dspace.org/server/api/integration/suggestions/search/findByTargetAndSource?target=nhy567-9d6d-ty67-b905-fef0f8cae26" }, "self": { - "href": "https://dspace7.4science.cloud/server/api/integration/suggestiontargets/scopus:nhy567-9d6d-ty67-b905-fef0f8cae26" + "href": "https://demo.dspace.org/server/api/integration/suggestiontargets/scopus:nhy567-9d6d-ty67-b905-fef0f8cae26" } } } @@ -72,13 +72,13 @@ Example: "type": "suggestiontarget", "_links": { "target": { - "href": "https://dspace7.4science.cloud/server/api/core/items/gf3d657-9d6d-4a87-b905-fef0f8cae26" + "href": "https://demo.dspace.org/server/api/core/items/gf3d657-9d6d-4a87-b905-fef0f8cae26" }, "suggestions": { - "href": "https://dspace7.4science.cloud/server/api/integration/suggestions/search/findByTargetAndSource?target=gf3d657-9d6d-4a87-b905-fef0f8cae26c&source=reciter" + "href": "https://demo.dspace.org/server/api/integration/suggestions/search/findByTargetAndSource?target=gf3d657-9d6d-4a87-b905-fef0f8cae26c&source=reciter" }, "self": { - "href": "https://dspace7.4science.cloud/server/api/integration/suggestiontargets/reciter:gf3d657-9d6d-4a87-b905-fef0f8cae26" + "href": "https://demo.dspace.org/server/api/integration/suggestiontargets/reciter:gf3d657-9d6d-4a87-b905-fef0f8cae26" } } }, @@ -90,13 +90,13 @@ Example: "type": "suggestiontarget", "_links": { "target": { - "href": "https://dspace7.4science.cloud/server/api/core/items/nhy567-9d6d-ty67-b905-fef0f8cae26" + "href": "https://demo.dspace.org/server/api/core/items/nhy567-9d6d-ty67-b905-fef0f8cae26" }, "suggestions": { - "href": "https://dspace7.4science.cloud/server/api/integration/suggestions/search/findByTargetAndSource?target=nhy567-9d6d-ty67-b905-fef0f8cae26&source=reciter" + "href": "https://demo.dspace.org/server/api/integration/suggestions/search/findByTargetAndSource?target=nhy567-9d6d-ty67-b905-fef0f8cae26&source=reciter" }, "self": { - "href": "https://dspace7.4science.cloud/server/api/integration/suggestiontargets/reciter:nhy567-9d6d-ty67-b905-fef0f8cae26" + "href": "https://demo.dspace.org/server/api/integration/suggestiontargets/reciter:nhy567-9d6d-ty67-b905-fef0f8cae26" } } } @@ -104,7 +104,7 @@ Example: }, "_links": { "self": { - "href": "https://dspace7.4science.cloud/server/api/integration/suggestiontargets/search/findBySource?source=reciter" + "href": "https://demo.dspace.org/server/api/integration/suggestiontargets/search/findBySource?source=reciter" } }, "page": { @@ -144,13 +144,13 @@ Example: "type": "suggestiontarget", "_links": { "target": { - "href": "https://dspace7.4science.cloud/server/api/core/items/gf3d657-9d6d-4a87-b905-fef0f8cae26" + "href": "https://demo.dspace.org/server/api/core/items/gf3d657-9d6d-4a87-b905-fef0f8cae26" }, "suggestions": { - "href": "https://dspace7.4science.cloud/server/api/integration/suggestions/search/findByTargetAndSource?target=gf3d657-9d6d-4a87-b905-fef0f8cae26c&source=reciter" + "href": "https://demo.dspace.org/server/api/integration/suggestions/search/findByTargetAndSource?target=gf3d657-9d6d-4a87-b905-fef0f8cae26c&source=reciter" }, "self": { - "href": "https://dspace7.4science.cloud/server/api/integration/suggestiontargets/reciter:gf3d657-9d6d-4a87-b905-fef0f8cae26" + "href": "https://demo.dspace.org/server/api/integration/suggestiontargets/reciter:gf3d657-9d6d-4a87-b905-fef0f8cae26" } } }, @@ -162,13 +162,13 @@ Example: "type": "suggestiontarget", "_links": { "target": { - "href": "https://dspace7.4science.cloud/server/api/core/items/gf3d657-9d6d-4a87-b905-fef0f8cae26" + "href": "https://demo.dspace.org/server/api/core/items/gf3d657-9d6d-4a87-b905-fef0f8cae26" }, "suggestions": { - "href": "https://dspace7.4science.cloud/server/api/integration/suggestions/search/findByTargetAndSource?target=gf3d657-9d6d-4a87-b905-fef0f8cae26&source=scopus" + "href": "https://demo.dspace.org/server/api/integration/suggestions/search/findByTargetAndSource?target=gf3d657-9d6d-4a87-b905-fef0f8cae26&source=scopus" }, "self": { - "href": "https://dspace7.4science.cloud/server/api/integration/suggestiontargets/scopus:gf3d657-9d6d-4a87-b905-fef0f8cae26" + "href": "https://demo.dspace.org/server/api/integration/suggestiontargets/scopus:gf3d657-9d6d-4a87-b905-fef0f8cae26" } } } @@ -176,7 +176,7 @@ Example: }, "_links": { "self": { - "href": "https://dspace7.4science.cloud/server/api/integration/suggestiontargets/search/findByTarget?target=gf3d657-9d6d-4a87-b905-fef0f8cae26" + "href": "https://demo.dspace.org/server/api/integration/suggestiontargets/search/findByTarget?target=gf3d657-9d6d-4a87-b905-fef0f8cae26" } }, "page": { From 88eeb945f41fb8f91c3368c39877fda800c2b934 Mon Sep 17 00:00:00 2001 From: frabacche Date: Fri, 16 Feb 2024 10:00:37 +0100 Subject: [PATCH 3/4] CST-5249_suggestion alignment with backend implementations and real examples --- suggestions.md | 172 +++++++++++++++++++++---------------------- suggestiontargets.md | 101 ++++++++++--------------- 2 files changed, 121 insertions(+), 152 deletions(-) diff --git a/suggestions.md b/suggestions.md index becefbd1..9945ca2a 100644 --- a/suggestions.md +++ b/suggestions.md @@ -11,7 +11,7 @@ _Unsupported._ The suggestions can be retrieved only by source and target or via It returns the data from one suggestion. The suggestion-id is a String generated by the source, as it must be unique for source, target and identified object to be imported it is usually represented by a combination of such elements -sample for a suggestion /api/integration/suggestions/reciter:gf3d657-9d6d-4a87-b905-fef0f8cae26:24694772 +sample for a suggestion /api/integration/suggestions/openaire:gf3d657-9d6d-4a87-b905-fef0f8cae26:24694772 ```json { "id": "reciter:gf3d657-9d6d-4a87-b905-fef0f8cae26:24694772", @@ -111,103 +111,97 @@ Return codes: * 200 OK - if the operation succeed * 400 Bad Request - if the uuid parameter is missing or invalid -sample for a search /server/api/integration/suggestions/search/findByTargetAndSource?target=gf3d657-9d6d-4a87-b905-fef0f8cae26c&source=reciter +sample for a search /api/integration/suggestions/search/findByTargetAndSource?sort=trust,DESC&target=bbb7feb2-7099-44cd-a896-1d47305a6a44&source=openaire + ```json { - "_embedded": { - "suggestions": [ -{ - "id": "24694772", - "display": "publication one", - "source": "reciter", - "externalSourceUri": "https://demo.dspace.org/server/api/integration/reciterSourcesEntry/pubmed/entryValues/24694772", - "evidences": { - "acceptedRejectedEvidence": { - "score": "2.7", - "notes": "some notes, eventually empty or null" - }, - "authorNameEvidence": { - "score": "0", - "notes": "some notes, eventually empty or null" - }, - "journalCategoryEvidence": { - "score": "6", - "notes": "some notes, eventually empty or null" - }, - "affiliationEvidence": { - "score": "xxx", - "notes": "some notes, eventually empty or null" - }, - "relationshipEvidence": { - "score": "9", - "notes": "some notes, eventually empty or null" - }, - "educationYearEvidence": { - "score": "3.6", - "notes": "some notes, eventually empty or null" - }, - "personTypeEvidence": { - "score": "4", - "notes": "some notes, eventually empty or null" - }, - "articleCountEvidence": { - "score": "6.7", - "notes": "some notes, eventually empty or null" - }, - "averageClusteringEvidence": { - "score": "7", - "notes": "some notes, eventually empty or null" - } + "_embedded" : { + "suggestions" : [ { + "id" : "openaire:bbb7feb2-7099-44cd-a896-1d47305a6a44:doi_________::29c72e9c2c3b4a0d730ece3ddbdec059", + "display" : "Enhanced Submission & Workflow", + "source" : "openaire", + "externalSourceUri" : "https://demo.dspace.org/server/api/integration/externalsources/openaire/entryValues/doi_________::29c72e9c2c3b4a0d730ece3ddbdec059", + "score" : "100.00", + "evidences" : { + "AuthorNamesScorer" : { + "score" : "100.00", + "notes" : "The author Andrea Bollini at position 2 in the authors list matches the name Andrea Bollini in the researcher profile" }, - "metadata": { - "dc.identifier.uri": [ - { - "value": "https://publication/0000-0003-3681-2038", - "language": null, - "authority": null, - "confidence": -1, - "place": -1 - } - ], - "dc.title" : [ - { - "value" : "publication one", - "language" : null, - "authority" : null, - "confidence" : -1 - } - ], - "dc.date.issued" : [ - { - "value" : "2010-11-03", - "language" : null, - "authority" : null, - "confidence" : -1 - } - ] + "DateScorer" : { + "score" : "0.00", + "notes" : "No assumption was possible about the publication year range. Please consider to set a min/max date in the profile, specify the birthday or education achievements" + } + }, + "metadata" : { + "dc.contributor.author" : [ { + "value" : "Giuseppe Digilio", + "language" : null, + "authority" : null, + "confidence" : -1, + "place" : -1 + }, { + "value" : "Andrea Bollini", + "language" : null, + "authority" : null, + "confidence" : -1, + "place" : -1 + }, { + "value" : "Claudio Cortese", + "language" : null, + "authority" : null, + "confidence" : -1, + "place" : -1 + } ], + "dc.date.issued" : [ { + "value" : "2021-06-10", + "language" : null, + "authority" : null, + "confidence" : -1, + "place" : -1 + } ], + "dc.description.abstract" : [ { + "value" : "

Presentation at Open Repository 2021

", + "language" : null, + "authority" : null, + "confidence" : -1, + "place" : -1 + } ], + "dc.source" : [ { + "value" : "ZENODO", + "language" : null, + "authority" : null, + "confidence" : -1, + "place" : -1 + } ], + "dc.title" : [ { + "value" : "Enhanced Submission & Workflow", + "language" : null, + "authority" : null, + "confidence" : -1, + "place" : -1 + } ] + }, + "type" : "suggestion", + "_links" : { + "target" : { + "href" : "https://demo.dspace.org/server/api/integration/suggestions/openaire:bbb7feb2-7099-44cd-a896-1d47305a6a44:doi_________::29c72e9c2c3b4a0d730ece3ddbdec059/target" }, - "type": "suggestion", - "_links": { - "target": { - "href": "https://demo.dspace.org/server/api/core/items/gf3d657-9d6d-4a87-b905-fef0f8cae26" - }, - "self": { - "href": "https://demo.dspace.org/server/api/integration/suggestions/reciter:gf3d657-9d6d-4a87-b905-fef0f8cae26c:24694772" - } + "self" : { + "href" : "https://demo.dspace.org/server/api/integration/suggestions/openaire:bbb7feb2-7099-44cd-a896-1d47305a6a44:doi_________::29c72e9c2c3b4a0d730ece3ddbdec059" } } - ] + }] }, - "_links": { - "self": { - "href": "https://demo.dspace.org/server/api/integration/suggestions/search/findByTargetAndSource?target=gf3d657-9d6d-4a87-b905-fef0f8cae26c&source=reciter" + "_links" : { + "self" : { + "href" : "https://demo.dspace.org/server/api/integration/suggestions/search/findByTargetAndSource?sort=trust,DESC&target=bbb7feb2-7099-44cd-a896-1d47305a6a44&source=openaire" } }, - "page": { - "size": 20, - "totalElements": 1, - "totalPages": 1, - "number": 0 + "page" : { + "size" : 20, + "totalElements" : 10, + "totalPages" : 1, + "number" : 0 } } ``` diff --git a/suggestiontargets.md b/suggestiontargets.md index 451367ac..626fb324 100644 --- a/suggestiontargets.md +++ b/suggestiontargets.md @@ -11,25 +11,23 @@ _Unsupported._ The suggestion targets can be retrieved only by target and/or by It returns the data from one target. This endpoint is accessible to the owner of the target profile and to the administrators -sample for a suggestion /api/integration/suggestiontargets/scopus:nhy567-9d6d-ty67-b905-fef0f8cae26 +sample for a suggestion /api/integration/suggestiontargets/openaire%3Abbb7feb2-7099-44cd-a896-1d47305a6a44 + ```json { - "id": "scopus:nhy567-9d6d-ty67-b905-fef0f8cae26", - "display": "Digilio, Giuseppe", - "source": "scopus", - "total": 3, - "type": "suggestiontarget", - "_links": { - "target": { - "href": "https://demo.dspace.org/server/api/core/items/nhy567-9d6d-ty67-b905-fef0f8cae26" - }, - "suggestions": { - "href": "https://demo.dspace.org/server/api/integration/suggestions/search/findByTargetAndSource?target=nhy567-9d6d-ty67-b905-fef0f8cae26" - }, - "self": { - "href": "https://demo.dspace.org/server/api/integration/suggestiontargets/scopus:nhy567-9d6d-ty67-b905-fef0f8cae26" - } + "id" : "openaire:bbb7feb2-7099-44cd-a896-1d47305a6a44", + "display" : "Andrea Bollini", + "source" : "openaire", + "total" : 10, + "type" : "suggestiontarget", + "_links" : { + "target" : { + "href" : "http://localhost:8080/server/api/integration/suggestiontargets/openaire:bbb7feb2-7099-44cd-a896-1d47305a6a44/target" + }, + "self" : { + "href" : "http://localhost:8080/server/api/integration/suggestiontargets/openaire:bbb7feb2-7099-44cd-a896-1d47305a6a44" } + } } ``` @@ -40,7 +38,6 @@ Attributes Exposed links: * target: link to the items that represent the person to whom the suggestions are proposed -* suggestions: link to the suggestions entries Status codes: * 200 Ok - if the operation succeed @@ -59,59 +56,37 @@ The supported parameters are: It returns the list of targets with their suggestion count for the specified source. Only targets that have at least one suggestion are returned. This endpoint is reserved to administrators -Example: +Sample of a resposne for /api/integration/suggestiontargets/search/findBySource?page=0&size=10&sort=display,ASC&source=openaire + ```json { - "_embedded": { - "suggestiontargets": [ - { - "id": "reciter:gf3d657-9d6d-4a87-b905-fef0f8cae26", - "display": "Bollini, Andrea", - "source": "reciter", - "total": 31, - "type": "suggestiontarget", - "_links": { - "target": { - "href": "https://demo.dspace.org/server/api/core/items/gf3d657-9d6d-4a87-b905-fef0f8cae26" - }, - "suggestions": { - "href": "https://demo.dspace.org/server/api/integration/suggestions/search/findByTargetAndSource?target=gf3d657-9d6d-4a87-b905-fef0f8cae26c&source=reciter" - }, - "self": { - "href": "https://demo.dspace.org/server/api/integration/suggestiontargets/reciter:gf3d657-9d6d-4a87-b905-fef0f8cae26" - } - } - }, - { - "id": "reciter:nhy567-9d6d-ty67-b905-fef0f8cae26", - "display": "Digilio, Giuseppe", - "source": "reciter", - "total": 12, - "type": "suggestiontarget", - "_links": { - "target": { - "href": "https://demo.dspace.org/server/api/core/items/nhy567-9d6d-ty67-b905-fef0f8cae26" - }, - "suggestions": { - "href": "https://demo.dspace.org/server/api/integration/suggestions/search/findByTargetAndSource?target=nhy567-9d6d-ty67-b905-fef0f8cae26&source=reciter" - }, - "self": { - "href": "https://demo.dspace.org/server/api/integration/suggestiontargets/reciter:nhy567-9d6d-ty67-b905-fef0f8cae26" - } + "_embedded" : { + "suggestiontargets" : [ { + "id" : "openaire:bbb7feb2-7099-44cd-a896-1d47305a6a44", + "display" : "Andrea Bollini", + "source" : "openaire", + "total" : 10, + "type" : "suggestiontarget", + "_links" : { + "target" : { + "href" : "http://localhost:8080/server/api/integration/suggestiontargets/openaire:bbb7feb2-7099-44cd-a896-1d47305a6a44/target" + }, + "self" : { + "href" : "http://localhost:8080/server/api/integration/suggestiontargets/openaire:bbb7feb2-7099-44cd-a896-1d47305a6a44" } } - ] + } ] }, - "_links": { - "self": { - "href": "https://demo.dspace.org/server/api/integration/suggestiontargets/search/findBySource?source=reciter" + "_links" : { + "self" : { + "href" : "http://localhost:8080/server/api/integration/suggestiontargets/search/findBySource?page=0&size=10&sort=display,ASC&source=openaire" } }, - "page": { - "size": 20, - "totalElements": 2, - "totalPages": 1, - "number": 0 + "page" : { + "size" : 10, + "totalElements" : 1, + "totalPages" : 1, + "number" : 0 } } ``` From c63bf54fc58c9801befb242582f04a14e4d9bc66 Mon Sep 17 00:00:00 2001 From: frabacche Date: Mon, 19 Feb 2024 09:28:03 +0100 Subject: [PATCH 4/4] fix suggestions GET response example --- suggestions.md | 44 ++++++++------------------------------------ 1 file changed, 8 insertions(+), 36 deletions(-) diff --git a/suggestions.md b/suggestions.md index 9945ca2a..0dd28f63 100644 --- a/suggestions.md +++ b/suggestions.md @@ -20,42 +20,14 @@ sample for a suggestion /api/integration/suggestions/openaire:gf3d657-9d6d-4a87- "score": "62.7", "externalSourceUri": "https://demo.dspace.org/server/api/integration/reciterSourcesEntry/pubmed/entryValues/24694772", "evidences": { - "acceptedRejectedEvidence": { - "score": "2.7", - "notes": "some notes, eventually empty or null" - }, - "authorNameEvidence": { - "score": "0", - "notes": "some notes, eventually empty or null" - }, - "journalCategoryEvidence": { - "score": "6", - "notes": "some notes, eventually empty or null" - }, - "affiliationEvidence": { - "score": "23.7", - "notes": "some notes, eventually empty or null" - }, - "relationshipEvidence": { - "score": "9", - "notes": "some notes, eventually empty or null" - }, - "educationYearEvidence": { - "score": "3.6", - "notes": "some notes, eventually empty or null" - }, - "personTypeEvidence": { - "score": "4", - "notes": "some notes, eventually empty or null" - }, - "articleCountEvidence": { - "score": "6.7", - "notes": "some notes, eventually empty or null" - }, - "averageClusteringEvidence": { - "score": "7", - "notes": "some notes, eventually empty or null" - } + "AuthorNamesScorer" : { + "score" : "100.00", + "notes" : "The author Andrea Bollini at position 2 in the authors list matches the name Andrea Bollini in the researcher profile" + }, + "DateScorer" : { + "score" : "0.00", + "notes" : "No assumption was possible about the publication year range. Please consider to set a min/max date in the profile, specify the birthday or education achievements" + } }, "metadata": { "dc.identifier.uri": [