-
Notifications
You must be signed in to change notification settings - Fork 50
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
Merge pull request #192 from 4Science/CST-5249_suggestion
Openaire suggestions (publication claim) rest contracts
- Loading branch information
Showing
4 changed files
with
409 additions
and
0 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,194 @@ | ||
| # 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/openaire:gf3d657-9d6d-4a87-b905-fef0f8cae26:24694772 | ||
| ```json | ||
| { | ||
| "id": "reciter:gf3d657-9d6d-4a87-b905-fef0f8cae26:24694772", | ||
| "display": "publication one", | ||
| "source": "reciter", | ||
| "score": "62.7", | ||
| "externalSourceUri": "https://demo.dspace.org/server/api/integration/reciterSourcesEntry/pubmed/entryValues/24694772", | ||
| "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" | ||
| }, | ||
| "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": [ | ||
| { | ||
| "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://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-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 /api/integration/suggestions/search/findByTargetAndSource?sort=trust,DESC&target=bbb7feb2-7099-44cd-a896-1d47305a6a44&source=openaire | ||
|
|
||
| ```json | ||
| { | ||
| "_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" | ||
| }, | ||
| "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" : "<p>Presentation at Open Repository 2021</p>", | ||
| "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" | ||
| }, | ||
| "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?sort=trust,DESC&target=bbb7feb2-7099-44cd-a896-1d47305a6a44&source=openaire" | ||
| } | ||
| }, | ||
| "page" : { | ||
| "size" : 20, | ||
| "totalElements" : 10, | ||
| "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) |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,39 @@ | ||
| # 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": { | ||
| "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: | ||
|
|
||
|
|
||
| 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) |
Oops, something went wrong.