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

Mapping collection #52

Merged
merged 12 commits into from Feb 14, 2019
Merged

Mapping collection #52

Changes from 7 commits
Commits
Show all changes
12 commits
Select commit Hold shift + click to select a range
46ea3b4
item mapping display
benbosman Aug 31, 2018
9193be5
mappingCollections
benbosman Sep 4, 2018
35d3171
Defining the mappingCollections as a parameter
benbosman Dec 14, 2018
cc6f6cc
Update items.md
benbosman Jan 3, 2019
f03cbac
Spring Data REST Relationships update
benbosman Feb 5, 2019
34bd941
Align all URLs with same base URL as elsewhere in contract
tdonohue Feb 6, 2019
6cd573f
Add PUT from #44 and other minor changes
tdonohue Feb 6, 2019
da83761
Applying feedback
tdonohue Feb 8, 2019
aa879c2
Updates per feedback
tdonohue Feb 13, 2019
cd80f16
Formatting cleanup
tdonohue Feb 13, 2019
a71310d
Add examples to README
tdonohue Feb 13, 2019
b0825b9
Note bulk delete not supported
tdonohue Feb 13, 2019
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Jump to
Jump to file
Failed to load files.
Diff view
Diff view
216 changes: 215 additions & 1 deletion items.md
View file
Open in desktop
Expand Up @@ -68,6 +68,7 @@ Provide detailed information about a specific item. The JSON response document i
Exposed links:
* bitstreams: list of bitstreams within the item
* owningCollection: the collection where the item belong to
* mappedCollections: the collections where the item is mapped to
* templateItemOf: the collection that have the item as template

## Creating an archived item
Expand Down Expand Up @@ -245,14 +246,227 @@ Status codes:
* 404 Not found - if the item doesn't exist
* 422 Unprocessable Entity - if the collection doesn't exist or the data cannot be resolved to a collection

### Mapped Collections
**GET /api/core/items/<:uuid>/mappedCollections**

Example:
```json
Copy link
Member

Choose a reason for hiding this comment

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

I have checked the documentation of other association endpoint and we don't include an example most of time as it is very verbose. The only one that I found is
https://github.com/DSpace/Rest7Contract/blob/master/collections.md#default-access-conditions

that said, if we want to keep the example we should move the mappedCollections inside a _embedded attribute

"mappedCollections":
[
{
"id": "16a4b65b-3b3f-4ef5-8058-ef6f5a653ef9",
"uuid": "16a4b65b-3b3f-4ef5-8058-ef6f5a653ef9",
"name": "Bachelor theses",
"handle": "123456789/5287",
"metadata": [
Copy link
Member

Choose a reason for hiding this comment

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

#39 has been merged so we should use the new syntax here as well

{
"key": "dc.description.abstract",
"value": "",
"language": null
},
{
"key": "dc.title",
"value": "Bachelor theses",
"language": null
}
],
"type": "collection",
"_links": {
"license": {
"href": "https://dspace7.4science.it/dspace-spring-rest/api/core/collections/16a4b65b-3b3f-4ef5-8058-ef6f5a653ef9/license"
},
"defaultAccessConditions": {
"href": "https://dspace7.4science.it/dspace-spring-rest/api/core/collections/16a4b65b-3b3f-4ef5-8058-ef6f5a653ef9/defaultAccessConditions"
},
"logo": {
"href": "https://dspace7.4science.it/dspace-spring-rest/api/core/collections/16a4b65b-3b3f-4ef5-8058-ef6f5a653ef9/logo"
},
"self": {
"href": "https://dspace7.4science.it/dspace-spring-rest/api/core/collections/16a4b65b-3b3f-4ef5-8058-ef6f5a653ef9"
}
},
"_embedded": {
"logo": null,
"defaultAccessConditions": {
"_embedded": {
"defaultAccessConditions": [
{
"id": 28054,
"name": null,
"groupUUID": "9e1794b8-45e0-4869-9c2c-36c4b25ce856",
"action": "DEFAULT_BITSTREAM_READ",
"type": "resourcePolicy",
"_links": {
"self": {
"href": "https://dspace7.4science.it/dspace-spring-rest/api/authz/resourcePolicies/28054"
}
}
}
]
},
"_links": {
"self": {
"href": "https://dspace7.4science.it/dspace-spring-rest/api/core/collections/16a4b65b-3b3f-4ef5-8058-ef6f5a653ef9/defaultAccessConditions"
}
},
"page": {
"number": 0,
"size": 1,
"totalPages": 1,
"totalElements": 1
}
}
}
},
{
"id": "320c0492-de1d-4646-9e69-193d36b366e9",
"uuid": "320c0492-de1d-4646-9e69-193d36b366e9",
"name": "Biology",
"handle": "123456789/5285",
"metadata": [
{
"key": "dc.description.abstract",
"value": "",
"language": null
},
{
"key": "dc.title",
"value": "Biology",
"language": null
}
],
"type": "collection",
"_links": {
"license": {
"href": "https://dspace7.4science.it/dspace-spring-rest/api/core/collections/320c0492-de1d-4646-9e69-193d36b366e9/license"
},
"exportToZip": {
"href": "https://dspace7.4science.it/dspace-spring-rest/api/core/collections/320c0492-de1d-4646-9e69-193d36b366e9/exportToZip"
},
"defaultAccessConditions": {
"href": "https://dspace7.4science.it/dspace-spring-rest/api/core/collections/320c0492-de1d-4646-9e69-193d36b366e9/defaultAccessConditions"
},
"logo": {
"href": "https://dspace7.4science.it/dspace-spring-rest/api/core/collections/320c0492-de1d-4646-9e69-193d36b366e9/logo"
},
"self": {
"href": "https://dspace7.4science.it/dspace-spring-rest/api/core/collections/320c0492-de1d-4646-9e69-193d36b366e9"
}
},
"_embedded": {
"logo": null,
"defaultAccessConditions": {
"_embedded": {
"defaultAccessConditions": [
{
"id": 28050,
"name": null,
"groupUUID": "9e1794b8-45e0-4869-9c2c-36c4b25ce856",
"action": "DEFAULT_BITSTREAM_READ",
"type": "resourcePolicy",
"_links": {
"self": {
"href": "https://dspace7.4science.it/dspace-spring-rest/api/authz/resourcePolicies/28050"
}
}
}
]
},
"_links": {
"self": {
"href": "https://dspace7.4science.it/dspace-spring-rest/api/core/collections/320c0492-de1d-4646-9e69-193d36b366e9/defaultAccessConditions"
}
},
"page": {
"number": 0,
"size": 1,
"totalPages": 1,
"totalElements": 1
}
}
}
}
]
}
```

It returns all the mapped collections the item is included in

On the item page, it should be referenced similar to:
```json
"mappedCollections": {
"href": "https://dspace7.4science.it/dspace-spring-rest/api/core/items/95e5d7d9-ef4e-4e35-86cc-07bfe2f0e355/mappedCollections"
}
```

**POST /api/core/items/<item:uuid>/mappedCollections**

A POST request will result in creating a new mapping between the item and collection.
If the collection exists and is neither the owning nor mapped collection for the item, the relation should be created.

```
curl -i -X POST https://dspace7.4science.it/dspace-spring-rest/api/core/items/1911e8a4-6939-490c-b58b-a5d70f8d91fb/mappedCollections
-H "Content-Type:text/uri-list" --data "https://dspace7.4science.it/dspace-spring-rest/api/core/collections/1c11f3f1-ba1f-4f36-908a-3f1ea9a557eb"
```

The collection(s) MUST be included in the body using the `text/uri-list` content type

Return codes:
* 204: if the update succeeded (including the case of no-op if the mapping was already as requested)
* 401 Forbidden - if you are not authenticated
* 403 Unauthorized - if you are not logged in with sufficient permissions
* 405: if the item is a template item
* 422: if the specified collection is not found or is the owningCollection of the item

**PUT /api/core/items/<item:uuid>/mappedCollections**
Copy link
Member

Choose a reason for hiding this comment

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

At the moment there's no use case for a PUT, so that's not planned to be implemented
To avoid any confusion, I assume it's best to leave it out here

Copy link
Member

Choose a reason for hiding this comment

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

I will like to have an uniform behavior across all our endpoints as much as possible. In the general section
https://github.com/DSpace/Rest7Contract#on-sub-path-of-a-single-resource-endpoint-associations
we state that PUT is supported, and I still convinced that this is the way to go. If we don't have plan/resources to do that for DSpace7 for this specific endpoint I will prefer to have here mentioned the "exception" (i.e. PUT ... (not supported yet))


A PUT request will replace the list collections where an item is mapped with the list provided in the request.

```
curl -i -X PUT https://dspace7.4science.it/dspace-spring-rest/api/core/items/1911e8a4-6939-490c-b58b-a5d70f8d91fb/mappedCollections
-H "Content-Type:text/uri-list" --data "https://dspace7.4science.it/dspace-spring-rest/api/core/collections/1c11f3f1-ba1f-4f36-908a-3f1ea9a557eb"
```

For example, in the above request, the item with UUID 1911e8a4-6939-490c-b58b-a5d70f8d91fb will now only be mapped to the collection with UUID 1c11f3f1-ba1f-4f36-908a-3f1ea9a557eb.
Any previous mappings are removed/replaced.

The collection(s) MUST be included in the body using the `text/uri-list` content type.

Return codes:
* 204: if the update succeeded (including the case of no-op if the mapping was already as requested)
* 401 Forbidden - if you are not authenticated
* 403 Unauthorized - if you are not logged in with sufficient permissions
* 405: if the item is a template item
* 422: if the specified collection is not found or is the owningCollection of the item

**DELETE /api/core/items/<item:uuid>/mappedCollections**
Copy link
Member

Choose a reason for hiding this comment

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

there are lot of discussion in stack overflow about the possibility or less to include a request body in the DELETE method
https://stackoverflow.com/questions/299628/is-an-entity-body-allowed-for-an-http-delete-request
The result of such discussions generally agree that it is formally possible (not denied by the spec) but it looks confusing to many people and at the best it is not standardised the semantic/purpose of the body and in some case there are suggestions to just ignore it

Personally I see a major issue with this use of the DELETE method here. Looking to the http spec

The DELETE method requests that the origin server delete the resource identified by the Request-URI.

in our case we are saying that what need to be deleted is not identified by the Request-URI


A DELETE request will result in removing an existing mapping between the item and collection
If the collection exists and is a mapped collection for the item, the relation should be deleted

```
curl -i -X DELETE https://dspace7.4science.it/dspace-spring-rest/api/core/items/1911e8a4-6939-490c-b58b-a5d70f8d91fb/mappedCollections
-H "Content-Type:text/uri-list" --data "https://dspace7.4science.it/dspace-spring-rest/api/core/collections/1c11f3f1-ba1f-4f36-908a-3f1ea9a557eb"
```

The collection(s) MUST be included in the body using the `text/uri-list` content type.

Return codes:
* 204: if the delete succeeded (including the case of no-op if the collection was not mapped)
* 401 Forbidden - if you are not authenticated
* 403 Unauthorized - if you are not logged in with sufficient permissions
* 405: if the item is a template item
* 422: if the specified collection is not found or is the owningCollection of the item


### Template Item
**/api/core/items/<:uuid>/templateItemOf**

Example: to be provided

It returns the collection that have the item as template

## Deleting a collection
## Deleting an item

**DELETE /api/core/items/<:uuid>**

Expand Down