Skip to content
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.

Sign up for GitHub

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

Jump to bottom

Entities support for external authority sources #74

Merged
merged 13 commits into from
Oct 15, 2019
Merged

Entities support for external authority sources #74

Show file tree
Hide file tree
Changes from 11 commits
Commits
Show all changes
13 commits
Select commit Hold shift + click to select a range
be0ea3b
support for external sources in authority control
benbosman Sep 2, 2019
4e9bfcc
Merge branch 'authority-control' into external-authority-sources
benbosman Sep 3, 2019
7e1867b
Merge remote-tracking branch 'atmire/authority-control' into external…
benbosman Sep 3, 2019
bd2e3d5
support for external sources in authority control
benbosman Sep 3, 2019
b133025
Merge branch 'authority-control' into external-authority-sources
benbosman Sep 3, 2019
43ae7d5
Merge branch 'master' into external-authority-sources
benbosman Sep 9, 2019
d88b8ca
fixing id
benbosman Sep 13, 2019
cb86c89
Update external-authority-sources.md
benbosman Sep 20, 2019
7f2c85c
External authority sources changes (#7)
KevinVdV Oct 4, 2019
ce74a83
Removing POST actions so the discussion about creating an entity and …
benbosman Oct 8, 2019
a71735e
wording change
benbosman Oct 15, 2019
fe7846e
moving the suggested changes to the contract to another PR
benbosman Oct 15, 2019
3b92f91
updating sample server name
benbosman Oct 15, 2019
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
49 changes: 34 additions & 15 deletions authorities.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -14,7 +14,6 @@ Example:
{
"id": "srsc",
"name": "srsc",
"scrollable": false,
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

this flag was intent to be used by authorities that allow scrolling of all values without providing a filter query. It is needed by the dropdown, the current implementation doesn't use this information but I still see a reason for it (it could detect misconfiguration when a dropdown is used with a not compatibile authority and maybe allow when working in suggest mode to automatically propose suggestion for scrollable authorities without user input when the input receive the focus)

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@abollini This flag is however not functional at all. It's never set to true, and the dropdowns are currently broken.
Since the feature is not documented, not functional, and has usability issues compared to DSpace 6, it's best to have it removed unless there's an intention to rectify this in the near future.

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@benbosman : I'm confused why this PR is still modifying the authorities REST Contract, as I thought the decision was to change this PR to only create the Read-Only external-sources endpoint.

"hierarchical": true,
"type": "authority",
"_links": {
Expand All @@ -32,7 +31,6 @@ Example:
{
"id": "common_types",
"name": "common_types",
"scrollable": false,
"hierarchical": false,
"type": "authority",
"_links": {
Expand All @@ -50,7 +48,6 @@ Example:
{
"id": "common_iso_languages",
"name": "common_iso_languages",
"scrollable": false,
"hierarchical": false,
"type": "authority",
"_links": {
Expand Down Expand Up @@ -89,7 +86,6 @@ Provide detailed information about a specific authority. The JSON response docum
{
"id": "srsc",
"name": "srsc",
"scrollable": false,
"hierarchical": true,
"type": "authority"
}
Expand Down Expand Up @@ -125,22 +121,37 @@ sample for an authority /server/api/integration/authorities/common_types/entries
"id": "Dataset",
"display": "Dataset",
"value": "Dataset",
"otherInformation": {},
"type": "authority"
"metadata": {},
"type": "authority",
"_links": {
"self": {
"href": "https://dspace7-internal.atmire.com/server/api/integration/authorities/common_types/entryValues/Dataset"
}
}
},
{
"id": "Image, 3-D",
"display": "Image, 3-D",
"value": "Image, 3-D",
"otherInformation": {},
"type": "authority"
"metadata": {},
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

metadata has a special meaning in dspace so this could be confusing. The idea here is that the authority can expose raw information not necessary "metadata" and to deal with them additional knowledge is usually required to the client.

An example of additional information that could result useful and is not a metadata are metrics value, number of items in the repository or in general number of publications for a researcher etc

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The information being included here exactly matches the definition of metadata. It can also be represented similar to item metadata since the information currently included here is e.g.:

  • An ORCID identifier
  • A description
  • A parent reference
    By ensuring this is also metadata, the UI can render the search results in a manner consistent with other lists

The information you're referencing here is not included in the authority functionality and don't seem to be relevant to include in an authority record.

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@benbosman : As above, I'm confused why this PR is still modifying the authorities REST Contract, as I thought the decision was to change this PR to only create the Read-Only external-sources endpoint. Maybe we should move this discussion to a separate PR to update the authorities endpoint based on current behavior?

"type": "authority",
"_links": {
"self": {
"href": "https://dspace7-internal.atmire.com/server/api/integration/authorities/common_types/entryValues/Image%2C%203-D"
}
}
},
{
"id": "Book",
"display": "Book",
"value": "Book",
"otherInformation": {},
"type": "authority"
"metadata": {},
"type": "authority",
"_links": {
"self": {
"href": "https://dspace7-internal.atmire.com/server/api/integration/authorities/common_types/entryValues/Book"
}
}
}
]
},
Expand Down Expand Up @@ -176,25 +187,33 @@ sample for a hierarchical authority (srsc): /server/api/integration/authorities
"id": "VR131402",
"display": "Research Subject Categories::SOCIAL SCIENCES::Social sciences::Social work::Family research",
"value": "Research Subject Categories::SOCIAL SCIENCES::Social sciences::Social work::Family research",
"otherInformation": {
"metadata": {
"parent": "SCB1314",
"note": "Familjeforskning"
},
"type": "authority",
"_links": {
"https://dspace7-internal.atmire.com/server/api/integration/authorities/srsc/entryValues/SCB1314": {
"href": "parent"
"self": {
"href": "https://dspace7-internal.atmire.com/server/api/integration/authorities/srsc/entryValues/VR131402"
},
"parent": {
"href": "https://dspace7-internal.atmire.com/server/api/integration/authorities/srsc/entryValues/SCB1314"
}
}
},
{
"id": "ResearchSubjectCategories",
"display": "Research Subject Categories",
"value": "Research Subject Categories",
"otherInformation": {
"metadata": {
"note": "Ämneskategorier för vetenskapliga publikationer"
},
"type": "authority"
"type": "authority",
"_links": {
"self": {
"href": "https://dspace7-internal.atmire.com/server/api/integration/authorities/srsc/entryValues/ResearchSubjectCategories"
}
}
}
]
},
Expand Down
275 changes: 275 additions & 0 deletions external-authority-sources.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,275 @@
# External sources Endpoints
[Back to the list of all defined endpoints](endpoints.md)

## Main Endpoint
**/api/integration/externalsources**
tdonohue marked this conversation as resolved.
Show resolved Hide resolved

Provide access to the configured external sources. It returns the list of existent external sources.

Example:
```json
{
"_embedded": {
"externalsources": [
{
"id": "orcid",
"name": "orcid",
"hierarchical": false,
"type": "externalsource",
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I think a "metadata" attribute should be available here. In case you need to describe in more detail each source.

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

From how I understand this based on the chat, this would be a single property. This may perhaps be better named "description" to reserve the term "metadata" for something where you have field names and values (e.g. https://github.com/DSpace/Rest7Contract/pull/74/files#diff-1f0dda62a7e6e5d84bb011254146955bR110)

It seems like a limited amount of work to have a configuration property for each source to describe it. Alternatively, this could be considered a UI aspect where internationalization labels are used to add detail per source (which would also ensure it can be displayed in the user's preferred language)

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

It seems like a limited amount of work to have a configuration property for each source to describe it. Alternatively, this could be considered a UI aspect where internationalization labels are used to add detail per source (which would also ensure it can be displayed in the user's preferred language)

But, considering we are supplying this source through REST API, that "description" should be implemented in all REST clients. But I'm ok with having it on the angular side.

"_links": {
"entries": {
"href": "https://dspace7-internal.atmire.com/server/api/integration/externalsources/orcid/entries"
},
"self": {
"href": "https://dspace7-internal.atmire.com/server/api/integration/externalsources/orcid"
}
}
},
{
"id": "ciencia",
"name": "ciencia",
"hierarchical": false,
"type": "externalsource",
"_links": {
"entries": {
"href": "https://dspace7-internal.atmire.com/server/api/integration/externalsources/ciencia/entries"
},
"self": {
"href": "https://dspace7-internal.atmire.com/server/api/integration/externalsources/ciencia"
}
}
},
{
"id": "my_staff_db",
"name": "my_staff_db",
"hierarchical": false,
"type": "externalsource",
"_links": {
"entries": {
"href": "https://dspace7-internal.atmire.com/server/api/integration/externalsources/my_staff_db/entries"
},
"self": {
"href": "https://dspace7-internal.atmire.com/server/api/integration/externalsources/my_staff_db"
}
}
}
]
},
"_links": {
"self": {
"href": "https://dspace7-internal.atmire.com/server/api/integration/externalsources"
}
},
"page": {
"size": 20,
"totalElements": 3,
"totalPages": 1,
"number": 0
}
}
```

## Single Authority
**/api/integration/externalsources/<:source-name>**

Provide detailed information about a specific external source. The JSON response document is as follow
```json
{
"id": "orcid",
"name": "orcid",
"hierarchical": false,
"type": "externalsource"
}
```

Exposed links:
* entries: the list of values managed by the external source

## Linked entities
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Just to clarify, these Entities differs from what we have being calling Entities (the Enhanced Items).

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This does indeed differ, most rest contracts contain a "Linked entities" section to detail the other REST endpoints linked from the main REST endpoint

### external source entries
**/api/integration/externalsources/<:source-name>/entries**

It returns the filtered entries managed by the externally, see below

The supported parameters are:
* page, size [see pagination](README.md#Pagination) if supported by the external source
* query: the terms, keywords or prefix to search: mandatory
* parent: the key of the parent authority when searching in a hierarchical authority
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

To clarify for others, this set of parameters (which allow for searching/filtering external sources) is one of the key differences with the /authorities endpoint. Internal Authorities require filtering by metadata field, while these external sources may have different needs/requirements (as they are all different APIs), so this set of supported parameters is likely to grow (and different external APIs may require different params)


It returns the entries in the external source matching the query

sample for an external source /server/api/integration/externalsources/orcid/entries?query=Smith&size=2
```json
{
"_embedded": {
"externalSourceEntries": [
{
"id": "0000-0002-4271-0436",
"display": "Smith, Dean",
"value": "Smith, Dean",
"metadata": {
"dc.identifier.orcid": [
tdonohue marked this conversation as resolved.
Show resolved Hide resolved
{
"value": "0000-0002-4271-0436",
"language": null,
"authority": null,
"confidence": -1,
"place": -1
}
],
"dc.identifier.uri": [
{
"value": "https://orcid.org/0000-0002-4271-0436",
"language": null,
"authority": null,
"confidence": -1,
"place": -1
}
],
"person.familyName": [
{
"value": "Smith",
"language": null,
"authority": null,
"confidence": -1,
"place": -1
}
],
"person.givenName": [
{
"value": "Dean",
"language": null,
"authority": null,
"confidence": -1,
"place": -1
}
]
},
"type": "externalSourceEntry",
"_links": {
"authority": {
"href": "https://dspace7-internal.atmire.com/server/api/integration/authorities/authors/entryValues/d4b5ca88-9d6d-4a87-b905-fef0f8cae26c"
},
"self": {
"href": "https://dspace7-internal.atmire.com/server/api/integration/externalsources/orcid/entryValues/0000-0002-4271-0436"
}
}
},
{
"id": "0000-0003-3681-2038",
"display": "Smith, Charles",
"value": "Smith, Charles",
"metadata": {
"dc.identifier.orcid": [
{
"value": "0000-0003-3681-2038",
"language": null,
"authority": null,
"confidence": -1,
"place": -1
}
],
"dc.identifier.uri": [
{
"value": "https://orcid.org/0000-0003-3681-2038",
"language": null,
"authority": null,
"confidence": -1,
"place": -1
}
],
"person.familyName": [
{
"value": "Smith",
"language": null,
"authority": null,
"confidence": -1,
"place": -1
}
],
"person.givenName": [
{
"value": "Charles",
"language": null,
"authority": null,
"confidence": -1,
"place": -1
}
]
},
"type": "externalSourceEntry",
"_links": {
"entity": {
"href": "https://dspace7-internal.atmire.com/server/api/core/item/6fd90bf5-b84f-47b3-aaec-a55bde3a2a5a"
},
"self": {
"href": "https://dspace7-internal.atmire.com/server/api/integration/externalsources/orcid/entryValues/0000-0003-3681-2038"
}
}
}
]
}
}
```

### single entry
**GET /api/integration/externalsources/<:source-name>/entryValues/<:entry-id>**

It returns the data from one entry in an external source

sample for an external source /api/integration/externalsources/orcid/entryValues/0000-0002-4271-0436
```json
{
"id": "0000-0002-4271-0436",
"display": "Smith, Dean",
"value": "Smith, Dean",
"type": "externalSourceEntry",
"externalSource": "orcid",
"metadata": {
"dc.identifier.orcid": [
{
"value": "0000-0002-4271-0436",
"language": null,
"authority": null,
"confidence": 0,
"place": -1
}
],
"dc.identifier.uri": [
{
"value": "https://orcid.org/0000-0002-4271-0436",
"language": null,
"authority": null,
"confidence": 0,
"place": -1
}
],
"person.familyName": [
{
"value": "Smith",
"language": null,
"authority": null,
"confidence": 0,
"place": -1
}
],
"person.givenName": [
{
"value": "Dean",
"language": null,
"authority": null,
"confidence": 0,
"place": -1
}
]
},
"_links": {
"entity": {
"href": "https://dspace7-internal.atmire.com/server/api/core/item/00167e74-c027-4984-8564-85c3fe513d45"
},
"self": {
"href": "https://dspace7-internal.atmire.com/server/api/integration/externalsources/orcid/entryValues/0000-0002-4271-0436"
}
}
}
```