Skip to content

Commit 7906b33

Browse files
tdonohuetdonohue
authored
Merge pull request #192 from 4Science/CST-5249_suggestion
Openaire suggestions (publication claim) rest contracts
2 parents e304c05 + c63bf54 commit 7906b33

File tree

4 files changed

+409
-0
lines changed

4 files changed

+409
-0
lines changed

‎endpoints.md

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -45,6 +45,11 @@
4545
* [/api/integration/qualityassurancesources](qualityassurancesources.md)
4646
* [/api/integration/qualityassurancetopics](qualityassurancetopics.md)
4747
* [/api/integration/qualityassuranceevents](qualityassuranceevents.md)
48+
* [/api/integration/suggestions](suggestions.md)
49+
* [/api/integration/suggestionsources](suggestionsources.md)
50+
* [/api/integration/suggestiontargets](suggestiontargets.md)
51+
52+
## Endpoints Under Development/Discussion
4853
* [/api/authz/resourcepolicies](resourcepolicies.md)
4954
* [/api/config/bulkaccessconditionoptions](bulkaccessconditionoptions.md)
5055
* [/api/authz/authorizations](authorizations.md)

‎suggestions.md

Lines changed: 194 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,194 @@
1+
# Suggestions Endpoints
2+
[Back to the list of all defined endpoints](endpoints.md)
3+
4+
## Main Endpoint
5+
**/api/integration/suggestions**
6+
7+
_Unsupported._ The suggestions can be retrieved only by source and target or via direct link, see the single entry and search method below.
8+
9+
### single entry
10+
**GET api/integration/suggestions/<:suggestion-id>**
11+
12+
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
13+
14+
sample for a suggestion /api/integration/suggestions/openaire:gf3d657-9d6d-4a87-b905-fef0f8cae26:24694772
15+
```json
16+
{
17+
"id": "reciter:gf3d657-9d6d-4a87-b905-fef0f8cae26:24694772",
18+
"display": "publication one",
19+
"source": "reciter",
20+
"score": "62.7",
21+
"externalSourceUri": "https://demo.dspace.org/server/api/integration/reciterSourcesEntry/pubmed/entryValues/24694772",
22+
"evidences": {
23+
"AuthorNamesScorer" : {
24+
"score" : "100.00",
25+
"notes" : "The author Andrea Bollini at position 2 in the authors list matches the name Andrea Bollini in the researcher profile"
26+
},
27+
"DateScorer" : {
28+
"score" : "0.00",
29+
"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"
30+
}
31+
},
32+
"metadata": {
33+
"dc.identifier.uri": [
34+
{
35+
"value": "https://publication/0000-0003-3681-2038",
36+
"language": null,
37+
"authority": null,
38+
"confidence": -1,
39+
"place": -1
40+
}
41+
],
42+
"dc.title" : [
43+
{
44+
"value" : "publication one",
45+
"language" : null,
46+
"authority" : null,
47+
"confidence" : -1
48+
}
49+
],
50+
"dc.date.issued" : [
51+
{
52+
"value" : "2010-11-03",
53+
"language" : null,
54+
"authority" : null,
55+
"confidence" : -1
56+
}
57+
]
58+
},
59+
"type": "suggestion",
60+
"_links": {
61+
"target": {
62+
"href": "https://demo.dspace.org/server/api/core/items/gf3d657-9d6d-4a87-b905-fef0f8cae26"
63+
},
64+
"self": {
65+
"href": "https://demo.dspace.org/server/api/integration/suggestions/reciter:gf3d657-9d6d-4a87-b905-fef0f8cae26:24694772"
66+
}
67+
}
68+
}
69+
```
70+
71+
## Search methods
72+
### Get suggestions by a given target
73+
**/api/integration/suggestions/search/findByTargetAndSource?target=:target-uuid&source=:source-key[&size=10&page=0]**
74+
75+
It returns the list of suggestions and corresponding evidence from a specific source for the requested individual/target
76+
77+
The supported parameters are:
78+
* 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
79+
* target: mandatory, the uuid associated with your target profile
80+
* source: mandatory, the key of the source that you want to query for suggestion
81+
82+
Return codes:
83+
* 200 OK - if the operation succeed
84+
* 400 Bad Request - if the uuid parameter is missing or invalid
85+
86+
sample for a search /api/integration/suggestions/search/findByTargetAndSource?sort=trust,DESC&target=bbb7feb2-7099-44cd-a896-1d47305a6a44&source=openaire
87+
88+
```json
89+
{
90+
"_embedded" : {
91+
"suggestions" : [ {
92+
"id" : "openaire:bbb7feb2-7099-44cd-a896-1d47305a6a44:doi_________::29c72e9c2c3b4a0d730ece3ddbdec059",
93+
"display" : "Enhanced Submission & Workflow",
94+
"source" : "openaire",
95+
"externalSourceUri" : "https://demo.dspace.org/server/api/integration/externalsources/openaire/entryValues/doi_________::29c72e9c2c3b4a0d730ece3ddbdec059",
96+
"score" : "100.00",
97+
"evidences" : {
98+
"AuthorNamesScorer" : {
99+
"score" : "100.00",
100+
"notes" : "The author Andrea Bollini at position 2 in the authors list matches the name Andrea Bollini in the researcher profile"
101+
},
102+
"DateScorer" : {
103+
"score" : "0.00",
104+
"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"
105+
}
106+
},
107+
"metadata" : {
108+
"dc.contributor.author" : [ {
109+
"value" : "Giuseppe Digilio",
110+
"language" : null,
111+
"authority" : null,
112+
"confidence" : -1,
113+
"place" : -1
114+
}, {
115+
"value" : "Andrea Bollini",
116+
"language" : null,
117+
"authority" : null,
118+
"confidence" : -1,
119+
"place" : -1
120+
}, {
121+
"value" : "Claudio Cortese",
122+
"language" : null,
123+
"authority" : null,
124+
"confidence" : -1,
125+
"place" : -1
126+
} ],
127+
"dc.date.issued" : [ {
128+
"value" : "2021-06-10",
129+
"language" : null,
130+
"authority" : null,
131+
"confidence" : -1,
132+
"place" : -1
133+
} ],
134+
"dc.description.abstract" : [ {
135+
"value" : "<p>Presentation at Open Repository 2021</p>",
136+
"language" : null,
137+
"authority" : null,
138+
"confidence" : -1,
139+
"place" : -1
140+
} ],
141+
"dc.source" : [ {
142+
"value" : "ZENODO",
143+
"language" : null,
144+
"authority" : null,
145+
"confidence" : -1,
146+
"place" : -1
147+
} ],
148+
"dc.title" : [ {
149+
"value" : "Enhanced Submission & Workflow",
150+
"language" : null,
151+
"authority" : null,
152+
"confidence" : -1,
153+
"place" : -1
154+
} ]
155+
},
156+
"type" : "suggestion",
157+
"_links" : {
158+
"target" : {
159+
"href" : "https://demo.dspace.org/server/api/integration/suggestions/openaire:bbb7feb2-7099-44cd-a896-1d47305a6a44:doi_________::29c72e9c2c3b4a0d730ece3ddbdec059/target"
160+
},
161+
"self" : {
162+
"href" : "https://demo.dspace.org/server/api/integration/suggestions/openaire:bbb7feb2-7099-44cd-a896-1d47305a6a44:doi_________::29c72e9c2c3b4a0d730ece3ddbdec059"
163+
}
164+
}
165+
}]
166+
},
167+
"_links" : {
168+
"self" : {
169+
"href" : "https://demo.dspace.org/server/api/integration/suggestions/search/findByTargetAndSource?sort=trust,DESC&target=bbb7feb2-7099-44cd-a896-1d47305a6a44&source=openaire"
170+
}
171+
},
172+
"page" : {
173+
"size" : 20,
174+
"totalElements" : 10,
175+
"totalPages" : 1,
176+
"number" : 0
177+
}
178+
}
179+
```
180+
181+
## Import suggestion
182+
183+
See the [WorkspaceItem endpoint](workspaceitems.md#Multipart-POST-Method) for details on how to import a suggestion
184+
185+
## Discard suggestion
186+
**DELETE api/integration/suggestions/<:suggestion-id>**
187+
188+
This discard the given suggestion. The endpoint is restricted to owners of the suggestion target and administrators
189+
190+
Status codes:
191+
* 204 No content - if the operation succeed
192+
* 401 Unauthorized - if you are not authenticated
193+
* 403 Forbidden - if you are not logged in with sufficient permissions
194+
* 404 Not found - if the suggestion doesn't exist (or was already discarded)

‎suggestionsources.md

Lines changed: 39 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,39 @@
1+
# Suggestion Sources Endpoints
2+
[Back to the list of all defined endpoints](endpoints.md)
3+
4+
## Main Endpoint
5+
**/api/integration/suggestionsources**
6+
7+
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
8+
9+
### single entry
10+
**GET api/integration/suggestionsources/<:source-key>**
11+
12+
It returns the data from a specific source. This endpoint is reserved to administrators
13+
14+
sample for a source /api/integration/suggestionsources/reciter
15+
```json
16+
{
17+
"id": "reciter",
18+
"total": 2,
19+
"type": "suggestionsource",
20+
"_links": {
21+
"self": {
22+
"href": "https://dspace7.4science.cloud/server/api/integration/suggestionsources/reciter"
23+
}
24+
}
25+
}
26+
```
27+
28+
Attributes
29+
* the *id* attribute is the key that identify the source
30+
* the *total* attribute is the number of target with suggestions. It can be 0 if there are no target with suggestions
31+
32+
Exposed links:
33+
34+
35+
Status codes:
36+
* 200 Ok - if the operation succeed
37+
* 401 Unauthorized - if you are not authenticated
38+
* 403 Forbidden - if you are not logged in with sufficient permissions
39+
* 404 Not found - if the source doesn't exist or is not active in the system (when 403 doesn't apply)

0 commit comments

Comments
 (0)