Skip to content

Latest commit

 

History

History
499 lines (417 loc) · 15.5 KB

collections.md

File metadata and controls

499 lines (417 loc) · 15.5 KB

Collections Endpoints

Back to the list of all defined endpoints

Main Endpoint

/api/core/collections

Provide access to the list of collections (DBMS based).

Example: http://dspace7.4science.it/dspace-spring-rest/#/dspace-spring-rest/api/core/collections

Single Collection

/api/core/collections/<:uuid>

Provide detailed information about a specific community. The JSON response document is as follow

{
  "uuid": "1c11f3f1-ba1f-4f36-908a-3f1ea9a557eb",
  "name": "Collection of Sample Items",
  "handle": "10673/2",
  "metadata": {
    "dc.description": [
      {
        "value": "<p>This is a <em>DSpace Collection</em> which contains sample DSpace Items.</p>\r\n<p><strong>Collections in DSpace may only contain Items.</strong></p>\r\n<p>This particular Collection has its own logo (the <a href=\"http://www.opensource.org/\">Open Source Initiative</a> logo).</p>\r\n<p>This introductory text is editable by System Administrators, Community Administrators (of a parent Community) or Collection Administrators (of this Collection).</p>",
        "language": null,
        "authority": null,
        "confidence": -1
      }
    ],
    "dc.description.abstract": [
      {
        "value": "This collection contains sample items.",
        "language": null,
        "authority": null,
        "confidence": -1
      }
    ],
    "dc.description.tableofcontents": [
      {
        "value": "<p>This is the <strong>news</strong> section for this Collection. System Administrators, Community Administrators (of a parent Community) or Collection Administrators (of this Collection) can edit this News field.</p>",
        "language": null,
        "authority": null,
        "confidence": -1
      }
    ],
    "dc.provenance": [
      {
        "value": "This field is for private provenance information. It is only visible to Administrative users and is not displayed in the user interface by default.",
        "language": null,
        "authority": null,
        "confidence": -1
      },
      {
        "value": "Second provenance value",
        "language": null,
        "authority": null,
        "confidence": -1
      }
    ],
    "dc.rights": [
      {
        "value": "<p><em>If this collection had a specific copyright statement, it would be placed here.</em></p>",
        "language": null,
        "authority": null,
        "confidence": -1
      }
    ],
    "dc.rights.license": [
      {
        "value": "",
        "language": null,
        "authority": null,
        "confidence": -1
      }
    ],
    "dc.title": [
      {
        "value": "Collection of Sample Items",
        "language": null,
        "authority": null,
        "confidence": -1
      }
    ]
  },
  "type": "collection"
}

Exposed links:

  • logo: link to the bitstream that represent the collection's logo
  • license: link to the license template used by the collection
  • defaultAccessConditions: link to the resource policies applied by default to new submissions in the collection
  • parentCommunity: the community containing this collection

Patch operations

Collection metadata can be modified as described in Modifying metadata via Patch.

Linked entities

Logo

Retrieve Logo

GET /api/core/collections/<:uuid>/logo

Example: https://dspace7.4science.it/dspace-spring-rest/#https://dspace7.4science.it/dspace-spring-rest/api/core/collections/1c11f3f1-ba1f-4f36-908a-3f1ea9a557eb/logo

It returns the bitstream representing the logo of this collection. [See the bitstream endpoint for more info](bitstreams.md#Single Bitstream)

Create Logo

POST /api/core/collections/<:uuid>/logo

To be used on a collection without a logo

Curl example:

curl 'https://dspace7.4science.cloud/dspace-spring-rest/api/core/collections/1c11f3f1-ba1f-4f36-908a-3f1ea9a557eb/logo' \
 -XPOST -H 'Content-Type: multipart/form-data' \
 -H 'Authorization: Bearer eyJhbGciOiJI...' \
 -F "file=@Downloads/test.png"
  • The collection is determined using the ID in the URL
  • The file is uploaded using multipart/form-data

It returns the created bitstream. [See the bitstream endpoint for more info](bitstreams.md#Single Bitstream)

The REST API can support Content-Length and Content-MD5 headers to verify integrity

Status codes:

  • 201 Created - 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 collection doesn't exist
  • 412 Precondition Failed - if there is a discrepancy between the declared size or checksum and the computed one
  • 422 Unprocessable Entity - if there was no file, or if the collection already contains a logo

This endpoint only accepts one file at a time. If multiple files are uploaded, any extra files will be ignored.

Replace Logo

Replacing a logo will require deleting the logo and creating a new logo hereafter

Delete Logo

DELETE /api/core/bitstreams/<:uuid>

Use the bitstream delete endpoint for removing the collection logo

If the bitstream is delete, this automatically ensures the relationship between the collection and the logo is removed as well.

License

/api/core/collections/<:uuid>/license

Return information about the license template in use by the collection. The json representation is as follow

{
  "custom": false,
  "text": "NOTE: PLACE YOUR OWN LICENSE HERE\nThis sample license is provided for informational purposes only.\n\nNON-EXCLUSIVE DISTRIBUTION LICENSE\n\nBy signing and submitting this license, you (the author(s) or copyright\nowner) grants to DSpace University (DSU) the non-exclusive right to reproduce,\ntranslate (as defined below), and/or distribute your submission...."
}
  • custom (READ-ONLY): can be true or false. True means that a custom license has been set for the collection otherwise the site license template is used and returned in the text attribute
  • text: contains the textual value of the license template to use for submission in the collection

Item template

Retrieve Item template

GET /api/core/collections/<:uuid>/itemtemplate

Example: https://dspace7.4science.it/dspace-spring-rest/#https://dspace7.4science.it/dspace-spring-rest/api/core/collections/1c11f3f1-ba1f-4f36-908a-3f1ea9a557eb/itemtemplate

It returns the item representing the item template of this collection. [See the item endpoint for more info](items.md#Single Item)

Create Item template

POST /api/core/collections/<:uuid>/itemtemplate

To be used on a collection without a item template. The metadata is included in JSON

{
  "metadata": {
    "dc.type": [
      {
        "value": "Journal Article",
        "language": "en",
        "authority": null,
        "confidence": -1
      }
    ]
  },
  "inArchive": false,
  "discoverable": false,
  "withdrawn": false,
  "type": "item"
}
  • The collection is determined using the ID in the URL
  • The metadata is uploaded using JSON
  • The properties inArchive, discoverable, withdrawn can be omitted or false, but not true

It returns the created item. [See the item endpoint for more info](items.md#Single Item)

Status codes:

  • 201 Created - 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 collection doesn't exist
  • 422 Unprocessable Entity - if inArchive, discoverable, withdrawn was set to true, or if the collection already contains a itemtemplate

Replace Item template

PATCH /api/core/itemtemplates/<:uuid>

See the item template endpoint for details

Delete Item template

DELETE /api/core/itemtemplates/<:uuid>

See the item template endpoint for details

Default Access Conditions

/api/core/collections/<:uuid>/defaultAccessConditions

It returns the resource policies applied by default to new submissions in the collection. They are the DEFAULT_BITSTREAM_READ policies of the collection

The json representation is as follow

{
  "_embedded": {
    "resourcePolicies": [
      {
        "id": 2844,
        "name": null,
        "groupUUID": "11cc35e5-a11d-4b64-b5b9-0052a5d15509",
        "action": "DEFAULT_BITSTREAM_READ",
        "type": "resourcePolicy",
        "_links": {
          "self": {
            "href": "https://dspace7.4science.it/dspace-spring-rest/api/authz/resourcePolicies/2844"
          }
        }
      }
    ]
  },
  "_links": {
    "self": {
      "href": "https://dspace7.4science.it/dspace-spring-rest/api/core/collections/5ad50035-ca22-4a4d-84ca-d5132f34f588/defaultAccessConditions"
    }
  },
  "page": {
    "size": 20,
    "totalElements": 1,
    "totalPages": 1,
    "number": 0
  }
}

see also the ResourcePolicies endpoint

Mapped items

/api/core/collections/<:uuid>/mappedItems

This is a Read-only endpoint to retrieve the mapped items for this collection.

Item mappings can only be modified via /items/[uuid]/mappedCollections

The request will return a list of items

Collection Harvesting Settings

GET /api/core/collections/<:uuid>/harvester

It returns the harvesting settings for the current collection. This information is only accessible for users with collection administration permissions

The harvest_type can be any of:

  • NONE
  • METADATA_ONLY
  • METADATA_AND_REF
  • METADATA_AND_BITSTREAMS

The harvest_status can be any of:

  • READY
  • BUSY
  • QUEUED
  • OAI_ERROR
  • UNKNOWN_ERROR

The metadata_config_id can be one of the ids from the Harvester Metadata Endpoint

A sample json response:

{
  "harvest_type": "METADATA_ONLY",
  "oai_source": "https://dspace.mit.edu/oai/request",
  "oai_set_id": "col_1721.1_114174",
  "harvest_message": null,
  "metadata_config_id": "dc",
  "harvest_status": "READY",
  "harvest_start_time": null,
  "last_harvested": null,
  "_links": {
    "self": {
      "href": "https://dspace7.4science.it/dspace-spring-rest/api/core/collections/6f944500-c300-449a-9023-a5ad8bd21160/harvester"
    }
  },
  "_embedded": {
    "metadata_configs": {
      "configs": [
        {
           "id": "dc",
           "label": "Simple Dublin Core",
           "nameSpace": "http://www.openarchives.org/OAI/2.0/oai_dc/"
        },
        {
           "id": "qdc",
           "label": "Qualified Dublin Core",
           "nameSpace": "http://purl.org/dc/terms/"
        },
        {
           "id": "dim",
           "label": "DSpace Intermediate Metadata",
           "nameSpace": "http://www.dspace.org/xmlns/dspace/dim"
        }
      ],
      "_links": {
        "self": {
          "href": "https://dspace7.4science.it/dspace-spring-rest/api/config/harvestermetadata"
        }
      }
    }
    
  }
}

A sample json response if no harvesting is enabled:

{
  "harvest_type": "NONE",
  "oai_source": null,
  "oai_set_id": null,
  "harvest_message": null,
  "metadata_config_id": null,
  "harvest_status": null,
  "harvest_start_time": null,
  "last_harvested": null,
  "_links": {
    "self": {
      "href": "https://dspace7.4science.it/dspace-spring-rest/api/core/collections/6f944500-c300-449a-9023-a5ad8bd21160/harvester"
    }
  },
  "_embedded": {
    "harvestermetadata": {
      "configs": [
        {
           "id": "dc",
           "label": "Simple Dublin Core",
           "nameSpace": "http://www.openarchives.org/OAI/2.0/oai_dc/"
        },
        {
           "id": "qdc",
           "label": "Qualified Dublin Core",
           "nameSpace": "http://purl.org/dc/terms/"
        },
        {
           "id": "dim",
           "label": "DSpace Intermediate Metadata",
           "nameSpace": "http://www.dspace.org/xmlns/dspace/dim"
        }
      ],
      "_links": {
        "self": {
          "href": "https://dspace7.4science.it/dspace-spring-rest/api/config/harvestermetadata"
        }
      }
    }
    
  }
}

Changing Collection Harvesting Settings

PUT /api/core/collections/<:uuid>/harvester

It updates the harvesting settings for the current collection. This information can only be updated by users with collection administration permissions

A sample json request:

{
  "harvest_type": "METADATA_ONLY",
  "oai_source": "https://dspace.mit.edu/oai/request",
  "oai_set_id": "col_1721.1_114174",
  "metadata_config_id": "dc"
}

A sample json request to disable harvesting is:

{
  "harvest_type": "NONE"
}

Status codes:

  • 200 OK - if the operation succeeded
  • 401 Unauthorized - if you are not authenticated
  • 403 Forbidden - if you are not logged in with sufficient permissions
  • 404 Not found - if the collection doesn't exist
  • 422 Unprocessable Entity - if the harvest_type or the metadata_config_id is not valid

Parent Community

/api/core/collections/<:uuid>/parentCommunity

It returns the community containing this collection, e.g. for trail purposes.
If a collection is part of multiple parent communities, it only returns one community.

Return codes:

  • 200 OK - if the parent community exists and returned
  • 204 No content - if the collection exists but the parent community doesn't exist
  • 401 Unauthorized - if you are not authenticated and the current collection or parent community is not public
  • 403 Forbidden - if you are not logged in with sufficient permissions to retrieve the current collection or parent community
  • 404 Not found - if the current collection doesn't exist

Creating a collection

POST /api/core/collections?parent=<:communityUUID>

To create a collection, perform as post with the JSON below when logged in as admin.

{
  "name": "test collection",
  "metadata": {
    "dc.title": [
      {
        "value": "test collection",
        "language": null,
        "authority": null,
        "confidence": -1
      }
    ]
  }
}

Error messages:

  • 200 OK - if the operation succeed
  • 401 Unauthorized - if you are not authenticated
  • 403 Forbidden - if you are not logged in with sufficient permissions
  • 422 UNPROCESSABLE ENTITY - if the parent community doesn't exist (the REST URI /api/core/collections still exists)

Updating a collection

PUT /api/core/collections/<:uuid>

Provide updated metadata information about a specific collection, when the update is completed the updated object will be returned. The JSON to update can be found below.

{
  "uuid": "20263916-6a3d-4fdc-a44a-4616312f030c",
  "name": "test collection",
  "metadata": {
    "dc.title": [
      {
        "value": "test collection",
        "language": null,
        "authority": null,
        "confidence": -1
      }
    ],
    "dc.description": [
      {
        "value": "Test description",
        "language": null,
        "authority": null,
        "confidence": -1
      }
    ]
  }
}

Error messages:

  • 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 collection doesn't exist
  • 422 UNPROCESSABLE ENTITY - Altering one of the non-editable parameters will result in a 422 UNPROCESSABLE ENTITY error. The non-editable parameters are optional, but if they are specified, they have to remain identical to the current value. The id, uuid, handle and type are non-editable.

Deleting a collection

DELETE /api/core/collections/<:uuid>

Delete a collection.

  • 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 community doesn't exist (or was already deleted)