This Confluence wiki site, maintained by DuraSpace prior to the recent merger with LYRASIS, will transition from the domain to the domain on Saturday, Nov 16 beginning at approximately 7pm ET. A period of downtime of 2-3 hours is expected. After the transition, this wiki will be available at All links to wiki pages will be redirected to the correct URL. If you have questions prior to or following the transition please contact:
Page tree

Versions Compared


  • This line was added.
  • This line was removed.
  • Formatting was changed.


In DSpace 5, the REST API adds authentication, allows Creation, Update, and Delete to objects, can access restricted materials if authorized, and it requires SSL.

Disabling SSL

For localhost development purposes, SSL can add additional getting-started difficulty, so security can be disabled. To disable DSpace REST's requirement to require security/ssl, alter [dspace]/webapps/rest/WEB-INF/web.xml or [dspace-source]/dspace-rest/src/main/webapp/WEB-INF/web.xml and comment out the security<security-constraint constraint> block, and restart your servlet container. Production usages of the REST API should use SSL, as authentication credentials should not go over the internet unencrypted.


Example usage from command line in XML format with pretty printing:

Code Block
curl -s -H "Accept: application/xml" http://localhost:8080/rest/communities | xmllint --format - 


Example usage from command line in JSON format with pretty printing: 

Code Block
curl -s -H "Accept: application/json" http://localhost:8080/rest/communities | python -m json.tool

For this documentation, we will assume that the URL to the "REST" webapp will be http://localhost:8080/rest/ for production systems, this address will be slightly different, such as: http The path to an endpoint, will go after the /rest/, such as /rest/communities, all-together this is: http://localhost:8080/rest/communities

Another thing to note is that there are Query Parameters that you can tack on to the end of an endpoint to do extra things. The most commonly used one in this API is "?expand". Instead of every API call defaulting to giving you every possible piece of information about it, it only gives a most commonly used set by default and gives the more "expensive" information when you deliberately request it. Each endpoint will provide a list of available expands in the output, but for getting started, you can start with ?expand=all, to make the endpoint provide all of its information (parent objects, metadata, child objects). You can include multiple expands, such as: ?expand=collections,subCommunities .


DSpace 6.x supports pagination by allowing two query parameters: limit and offset. Note however that the aggregate results number is not supplied (see DS-3887). Endpoints which return arrays of objects, such as /communities, /collections or /items, are "paginated":  the full list is broken into "pages" which start at offset from the beginning of the list and contain at most limit elements.  By repeated queries you can retrieve any portion of the array or all of it.  The default value of offset  is 0 and the default value of limit is 100.  So, as an example, to retrieve the sixth through tenth elements of the full list of Collections, you could do this:

Code Block
curl -s -H "Accept: application/json" http://localhost:8080/rest/collections?offset=5\&limit=5

Index / Authentication


REST API Authentication has changed in DSpace 6.x.  It now uses a JSESSIONID cookie (see below).  The previous (5.x) authentication scheme using a rest-dspace-token is no longer supported.

GET/REST API static documentation page

Login to the REST API using a DSpace EPerson

/ User

(user). It returns

an dspace-rest-token

a JSESSIONID cookie, that can be used for future authenticated requests.

Example Request:

Code Block
# Can use either POST or GET (POST recommended). Must pass the parameters "email" and "password".
curl -
H "Content-Type: application/json"
v -X POST --data
", "
:"dspace"}' http://localhost:8080

Example Response:

Code Block
HTTP/1.1 200 OK
Set-Cookie: JSESSIONID=6B98CF8648BCE57DCD99689FE77CB1B8; Path=/rest/; Secure; HttpOnly

Example of using JSESSIONID cookie for subsequent (authenticated) requests:

Code Block
curl -v --cookie "JSESSIONID=6B98CF8648BCE57DCD99689FE77CB1B8"
# This should return <authenticated>true</authenticated>, and information about the authenticated user session

Invalid email/password combinations will receive an HTTP

403 Forbidden.

401 Unauthorized response.

Please note, special characters need to be HTTP URL encoded.
For example, an email address like (notice the + special character) would need to be encoded as


Login to the REST API using Shibboleth authentication. In order to work, this requires additional Apache configuration. To authenticate, execute the following steps:

1. Call the REST Shibboleth login point with a Cookie jar:

Code Block
curl -v -L -c cookiejar ""

2. This should take you again to the IdP login page. You can submit this form using curl using the same cookie jar. However this is IdP dependant so we cannot provide an example here.

3. Once you submit the form using curl, you should be taken back to the /rest/shibboleth-login URL which will return you the JSESSIONID.

4. Using that JSESSIONID, check if you have authenticated successfully:

Code Block
curl -v "http://localhost:8080/dspace-rest/status" --cookie "JSESSIONID=0633C6379266A283E53F65DF8EF61AB9"


Logout from the REST API, by providing a

header rest-dspace-token

JSESSIONID cookie. After being posted this


cookie will no longer work.

Example Request:

Code Block
curl -v -X POST -
H "Content-Type: application/json" -H "rest-dspace-token: 1febef81-5eb6-4e76-a0ea-a5be245563a5" http://localhost:8080/rest/logout
-cookie "JSESSIONID=6B98CF8648BCE57DCD99689FE77CB1B8"

After posting a logout request, cookie is invalidated and the "/status" path should show you as unauthenticated (even when passing that same cookie). For example:

Code Block
curl -v --cookie "JSESSIONID=6B98CF8648BCE57DCD99689FE77CB1B8"
# This should show <authenticated>false</authenticated>

Invalid token will result in HTTP 400 Invalid Request


Returns string "REST api is running", for testing that the API is up.

Example Request:

Code Block

Example Response:

Code Block
REST api is running.


Receive information about the currently authenticated user token, or the API itself (e.g. version information).

Example Request (XML by default):

Code Block
curl -
X GET -H "Content-Type: application/json" -H "Accept:
v --cookie "JSESSIONID=6B98CF8648BCE57DCD99689FE77CB1B8"

Example Request (JSON):

Code Block
curl -v -H "Accept: application/json" -
H "rest-dspace-token: f2f478e2-90f2-4e77-a757-4e838ae94154" http://localhost:8080
-cookie "JSESSIONID=6B98CF8648BCE57DCD99689FE77CB1B8"

Example JSON Response:

Code Block
  "fullname":"DSpace Administrator",

Shibboleth Apache configuration for the REST API

Before Shibboleth authentication for the REST API will work, you need to secure the /rest/shibboleth-login endpoint. Add this configuration section to your Apache HTTPD Shibboleth configuration:

Code Block
<Location "/rest/shibboleth-login">
         AuthType shibboleth
         ShibRequireSession On
         # Please note that setting ShibUseHeaders to "On" is a potential security risk. 
         # You may wish to set it to "Off". See the mod_shib docs for details about this setting:
         # Here's a good guide to configuring Apache + Tomcat when this setting is "Off": 
         ShibUseHeaders On
         require valid-user

You can test your configuration in 3 different ways:

  1. Using a web browser:
    1. Go to, this should redirect you to the login page of your IdP if you don't have a Shibboleth session yet.
    2. Enter your test credentials and this should take you back to the /rest/shibboleth-login URL. You should then see a blank page but in the response headers, the JSESSIONID cookie should be present.
    3. Then go to /rest/status and you should see information on the current authenticated ePerson.
  2. Using curl without a Shibboleth Session
    1. Call the REST Shibboleth login point with a Cookie jar: 

      Code Block
      curl -v -L -c cookiejar ""

    2. This should take you again to the IdP login page. You can submit this form using curl using the same cookie jar. However this is IdP dependant so I cannot provide an example here.
    3. Once you submit the form using curl, you should be taken back to the /rest/shibboleth-login URL which will return you the JSESSIONID.
    4. Using that JSESSIONID, check if you have authenticated successfully: 

      Code Block
      curl -v "" --cookie "JSESSIONID=0633C6379266A283E53F65DF8EF61AB9"

  3. Using curl with a Shibboleth Session (cookie)
    1. When you post the Shibboleth login form, the Shibboleth daemon on the DSpace server also returns you a Shibboleth Cookie. This cookie looks like _shibsession_64656661756c74687... You can also grab this cookie from your browser.
    2. Double check that the cookie you took is valid:

      Code Block
      curl -v 'https://dspace-url/Shibboleth.sso/Session' -H 'Cookie: _shibsession_64656661756c7468747470733a2f2f7265706f7369746f72792e636172646966666d65742e61632e756b2f73686962626f6c657468=_a8d3ad20d8b655250c7357f7ac0e2910;'

    3. This should give you information if the Shibboleth session is valid and on the number of attributes. 
    4. Use this cookie to obtain a Tomcat JSESSIONID:

      Code Block
      curl -v 'https://dspace-url/rest/shibboleth-login' -H 'Cookie: _shibsession_64656661756c7468747470733a2f2f7265706f7369746f72792e636172646966666d65742e61632e756b2f73686962626f6c657468=_a8d3ad20d8b655250c7357f7ac0e2910;'

    5. Use the returned JSESSIONID to check if you have authenticated successfully:

      Code Block
      curl -v "http://dspace-url/rest/status" --cookie "JSESSIONID=0633C6379266A283E53F65DF8EF61AB9"


Communities in DSpace are used for organization and hierarchy, and are containers that hold sub-Communities and Collections. (ex: Department of Engineering)


  • GET /collections - Return all collections of DSpace in array. Use the limit parameter to control items per response (default 100) and offset for paging.
  • GET /collections/{collectionId} - Return collection with id.
  • GET /collections/{collectionId}/items - Return all items of collection.
  • POST /collections/{collectionId}/items - Create posted item in collection. You must post an Item
  • POST /collections/find-collection - Find collection by passed name.
  • PUT /collections/{collectionId} - Update collection. You must put Collection.
  • DELETE /collections/{collectionId} - Delete collection from DSpace.
  • DELETE /collections/{collectionId}/items/{itemId} - Delete item in collection.


  • GET /items - Return list of items.
  • GET /items/{item id} - Return item.
  • GET /items/{item id}/metadata - Return item metadata.
  • GET /items/{item id}/bitstreams - Return item bitstreams.
  • POST /items/find-by-metadata-field - Find items by metadata entry. You must post a MetadataEntry.  Jira
    serverDuraSpace JIRA
  • POST /items/{item id}/metadata - Add metadata to item. You must post an array of MetadataEntry.
  • POST /items/{item id}/bitstreams - Add bitstream to item. You must post a Bitstream.
  • PUT /items/{item id}/metadata - Update metadata in item. You must put a MetadataEntry. *
  • DELETE /items/{item id} - Delete item.
  • DELETE /items/{item id}/metadata - Clear item metadata.
  • DELETE /items/{item id}/bitstreams/{bitstream id} - Delete item bitstream.

* note that each metadata entry that you put will replace all prior matching metadata entries, i.e. if you submit n 'dc.subject' entries all pre-existing 'dc.subject' entries in the item will be deleted and replaced with the n entries


Bitstreams are files. They have a filename, size (in bytes), and a file format. Typically in DSpace, the Bitstream will the "full text" article, or some other media. Some files are the actual file that was uploaded (tagged with bundleName:ORIGINAL), others are DSpace-generated files that are derivatives or renditions, such as text-extraction, or thumbnails. You can download files/bitstreams. DSpace doesn't really limit the type of files that it takes in, so this could be PDF, JPG, audio, video, zip, or other. Also, the logo for a Collection or a Community, is also a Bitstream.


  • GET /handle/{handle-prefix}/{handle-suffix} - Returns a Community, Collection, or Item object that matches that handle.


Assembling a full representation of the community and collection hierarchy using the communities and collections endpoints can be inefficient. Retrieve a lightweight representation of the nested community and collection hierarchy.  Each node of the hierarchy contains minimal information (id, handle, name).

  • GET /hierarchy - Retrieve a lightweight representation of the nested community and collection hierarchy.

Schema and Metadata Field Registry

  • GET /registries/schema - Return the list of schemas in the registry
  • GET /registries/schema/{schema_prefix} - Returns the specified schema
  • GET /registries/schema/{schema_prefix}/metadata-fields/{element} - Returns the metadata field within a schema with an unqualified element name
  • GET /registries/schema/{schema_prefix}/metadata-fields/{element}/{qualifier} - Returns the metadata field within a schema with a qualified element name
  • POST /registries/schema/ - Add a schema to the schema registry
  • POST /registries/schema/{schema_prefix}/metadata-fields - Add a metadata field to the specified schema
  • GET /registries/metadata-fields/{field_id} - Return the specified metadata field
  • PUT /registries/metadata-fields/{field_id} - Update the specified metadata field
  • DELETE /registries/metadata-fields/{field_id} - Delete the specified metadata field from the metadata field registry
  • DELETE /registries/schema/{schema_id} - Delete the specified schema from the schema registry

Note: since the schema object contains no data fields, the following method has not been implemented: PUT /registries/schema/{schema_id}

Report Tools

Reporting Tools that allow a repository manager to audit a collection for metadata consistency and bitstream consistency.  See REST Based Quality Control Reports for more information.

Collection Report Tool on

Metadata Query Tool on

  • GET /reports - Return a list of report tools built on the rest api
  • GET /reports/{nickname} - Return a redirect to a specific report
  • GET /filters - Return a list of use case filters available for quality control reporting
  • GET /filtered-collections - Return collections and item counts based on pre-defined filters
  • GET /filtered-collections/{collection_id} - Return items and item counts for a collection based on pre-defined filters
  • GET /filtered-items - Retrieve a set of items based on a metadata query and a set of filters

Model - Object data types

Here are all of the data types, not all fields are necessary or supported when posting/putting content, but the output contains this information:

Community Object

Code Block
{"id":456,"name":"Reports Community","handle":"10766/10213","type":"community","link":"/


rest/communities/456","expand":["parentCommunity","collections","subCommunities","logo","all"],"logo":null,"parentCommunity":null,"copyrightText":"","introductoryText":"","shortDescription":"Collection contains materials pertaining to the Able Family","sidebarText":"","countItems":3,"subcommunities":[],"collections":[]}

Collection Object

Code Block
{"id":730,"name":"Annual Reports Collection","handle":"10766/10214","type":"collection","link":"/



Item Object

Code Block
{"id":14301,"name":"2015 Annual Report","handle":"123456789/13470","type":"item","link":"/


rest/items/14301","expand":["metadata","parentCollection","parentCollectionList","parentCommunityList","bitstreams","all"],"lastModified":"2015-01-12 15:44:12.978","parentCollection":null,"parentCollectionList":null,"parentCommunityList":null,"bitstreams":null,"archived":"true","withdrawn":"false"}

Bitstream Object

Code Block
{"id":47166,"name":"appearance and physiology 100 percent copied from wikipedia.pdf","handle":null,"type":"bitstream","link":"/


rest/bitstreams/47166","expand":["parent","policies","all"],"bundleName":"ORIGINAL","description":"","format":"Adobe PDF","mimeType":"application/pdf","sizeBytes":129112,"parentObject":null,"retrieveLink":"/bitstreams/47166/retrieve","checkSum":{"value":"62778292a3a6dccbe2662a2bfca3b86e","checkSumAlgorithm":"MD5"},"sequenceId":1,"policies":null}

ResourcePolicy Object

Code Block

MetadataEntry Object

Code Block
{"key":"dc.description.abstract", "value":"This is the description abstract", "language": null}

User Object

Code Block

Status Object

Code Block
{"okay":true,"authenticated":true,"email":"","fullname":"DSpace Test User","token":"6d45daaa-7b02-4ae7-86de-a960838fae5c"}


Introduction to Jersey for developers


Configuration for DSpace REST

Example Valuetrue
Informational NoteBoolean value indicates whether statistics should be recorded for access via the REST API; Defaults to 'false'.

Recording Proxy Access by Tools

For the purpose of more accurate statistics, a web-based tool may specify who is using it, by adding parameters to the request:

Code Block

If no parameters are given, the details of the HTTP request's sender are used in statistics. This enables tools to record the details of their user rather than themselves.

Deploying the DSpace REST API in your Servlet Container

The dspace-rest module is automatically configured to compile and build with DSpace 4.0, so a mvn+ant process will create the webapp. To make it work in your environment, you would just need to add a context entry for it in your servlet container. For example, in tomcat, one might alter $CATALINA_HOME/conf/server.xml and add:

Code Block
<Context path="/rest" docBase="/dspace/webapps/rest"/>

Additional Information

Additional information can be found in the README for dspace-rest, and in the GitHub Pull Request for DSpace REST (Jersey).