-
Notifications
You must be signed in to change notification settings - Fork 50
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
Openaire suggestions (publication claim) rest contracts #192
Merged
Merged
Changes from 5 commits
Commits
Show all changes
6 commits
Select commit
Hold shift + click to select a range
6ade120
[CST-5249] Added suggestions rest contracts
LucaGiamminonni a728beb
Merge branch 'CST-5249_suggestion' of https://github.com/4Science/Res…
frabacche 351c6d8
Merge branch 'main' of github.com:4Science/Rest7Contract into CST-524…
frabacche c189f70
CST-5249_suggestion alignment to the backend implementation
frabacche 88eeb94
CST-5249_suggestion alignment with backend implementations and real e…
frabacche c63bf54
fix suggestions GET response example
frabacche File filter
Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
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,222 @@ | ||
| # 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": { | ||
| "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://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.
Oops, something went wrong.
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Same as other comment. We should change this list to only include AuthorNamesScorer and DateScorer.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
see reply.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
As I noted in my later reply, I think we need to keep the list of "evidences" realistic, otherwise developers will be confused if they cannot find these in DSpace.
I'm OK with providing one example of a custom evidence. But, currently this REST Contract PR has a list of 9 evidences all of which do not exist in DSpace. I propose we update this to say something like:
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
@frabacche : Could you update the list of evidences in this section of
suggestions.mdthe same way that you updated them below? This section still has the list of invalid "evidences"For example: