Merge pull request #52 from DSpace/mapping-collection

Mapping collection

README.md

@@ -98,7 +98,15 @@ Only supported for collection associations (i.e. associations allowing for multi
    ```
 
 - `DELETE`:
-Unbinds (unlinks) the association. Return `405 Method Not Allowed` if the association is required (and cannot be removed)
+Unbinds (unlinks) the association. Return `405 Method Not Allowed` if the association is required (and cannot be removed).  DELETE requests should _not_ contain a request body as some clients do not support sending a DELETE request with a body. Therefore, if an individual association needs to be removed, the DELETE request should reference that individual association in the URI of the request. For example:
+   ```
+   # Example curl command to delete a *single* Collection mapping for an Item
+   curl -i -X DELETE "http://localhost:8080/rest/api/core/items/<:uuid>/mappedCollections/<:collection_uuid>"
+   
+   # Example curl command to delete *ALL* Collection mappings for an item (unsupported at this time)
+   curl -i -X DELETE "http://localhost:8080/rest/api/core/items/<:uuid>/mappedCollections
+   ```
+
 
 ### Error codes
 400 Bad Request - if multiple URIs were given for a to-one-association

items.md

@@ -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
@@ -245,14 +246,76 @@ 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**
+
+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"
+    }
+```
+
+**GET /api/core/items/<:uuid>/mappedCollections/<:collection_uuid>**
+
+_Unsupported._ If you want detailed information about a single mapped collection, use the `/api/core/collections/<collection:uuid>` endpoint.
+
+**POST /api/core/items/<: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/<:uuid>/mappedCollections**
+
+_Unsupported._ You may replace or update mapped collections using DELETE requests and/or POST requests.
+
+**DELETE /api/core/items/<:uuid>/mappedCollections**
+
+_Unsupported._ At this time, we do not support removing all mapped Collections in a single request. Please use `DELETE /api/core/items/<:uuid>/mappedCollections/<:collection_uuid>` to remove mapped Collections one by one.
+
+**DELETE /api/core/items/<:uuid>/mappedCollections/<:collection_uuid>**
+
+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/1c11f3f1-ba1f-4f36-908a-3f1ea9a557eb"
+```
+
+The above request would remove the mapping between Collection with UUID `1c11f3f1-ba1f-4f36-908a-3f1ea9a557eb` and Item with UUID `1911e8a4-6939-490c-b58b-a5d70f8d91fb`.
+
+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>**