...

The REST API deploys as a standard webapp for your servlet container / tomcat. For example, depending on how you deploy webapps, one way would be to alter tomcat-home/conf/server.xml and add:

Code Block
<Context path="/rest"

...

  docBase="/dspace/webapps/rest"

...

/>

In DSpace 4, the initial/official Jersey-based REST API was added to DSpace. The DSpace 4 REST API provides READ-ONLY access to DSpace Objects.

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

Since the DSpace 5 version of the REST API allows for authentication, and can include restricted access materials, it requires 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.

...

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

...

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

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://demo.dspace.org/rest/. The path to an endpoint, will go after the /rest/, such as /rest/communities, all-together this is: http://localhost:8080/rest/communities

...

Receive information about the currently authenticated user token GET Accept: application/json" -H " f2f478e290f24e77a7574e838ae94154

Method	Endpoint	Description
GET	/	REST API static documentation page
POST	/login	Login to the REST API using a DSpace EPerson / User(user). It returns an dspace-rest-a token, that can be used for future authenticated requests .(as a value of the rest-dspace-token request header). Example Request: curl -H "Content-Type: application/json" --data '{"email":"admin@dspace.org", "password":"dspace"}' http://localhost:8080/rest/login Example Response: 1febef81-5eb6-4e76-a0ea-a5be245563a5 Invalid email/password combinations will receive an HTTP 403 Forbidden.
POST	/logout	Logout from the REST API, by providing a header rest-dspace-token. After being posted this token will no longer work. Example Request: curl -X POST -H "Content-Type: application/json" -H "rest-dspace-token: 1febef81-5eb6-4e76-a0ea-a5be245563a5" http://localhost:8080/rest/logout Invalid token will result in HTTP 400 Invalid Request
GET	/test	Returns string "REST api is running", for testing that the API is up. Example Request: curl http://localhost:8080/rest/test Example Response: REST api is running.
The extended tokens are generated and stored in memory, not in the database or on disk. There are no timeouts for these tokens. This means that tokens remain valid as long as DSpace is not restarted. A restart of DSpace will invalidate all extended tokens. If applications re-use a token over multiple calls, especially if they are spread over a potentially longer time window, it is highly recommended that the /status endpoint is called to guarantee that a specific token is still valid. Applications that consume the DSpace REST API have no way of telling when DSpace has been restarted. In the DSpace logs, calls with invalid tokens can often look like anonymous requests being made.
POST	/logout	Logout from the REST API, by providing a header rest-dspace-token. After being posted this token will no longer work	GET	/status	. Example Request: curl -X	POST -H "Content-Type: application/json" -H "	rest-dspace-token:	1febef81-	5eb6-	4e76-	a0ea-	a5be245563a5" http://localhost:8080/rest/logout Invalid token will result in HTTP 400 Invalid Request
GET	/test	Returns string "REST api is running", for testing that the API is up. Example Request: curl http://localhost:8080/rest/test Example Response: REST api is running.
GET	/status	Receive information about the currently authenticated user token. Example Request: curl -X GET -H "Content-Type: application/json" -H "Accept: application/json" -H "rest-dspace-token: statusExample Response: {"okay":true,"authenticated":true,"email":"admin@dspace.org","fullname":"DSpace Administrator","token":" f2f478e2-90f2-4e77-a757-4e838ae94154" }

Communities

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

http://localhost:8080/rest/status

Example Response:
{"okay":true,"authenticated":true,"email":"admin@dspace.org","fullname":"DSpace Administrator","token":"f2f478e2-90f2-4e77-a757-4e838ae94154"}

Communities

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

GET /communities - Returns array of all communities in DSpace.
GET /communities/top-communities - Returns
GET /communities - Returns array of all communities in DSpace.
GET /communities/top-communities - Returns array of all top communities in DSpace.
GET /communities/{communityId} - Returns community.
GET /communities/{communityId}/collections - Returns array of collections of community.
GET /communities/{communityId}/communities - Returns array of subcommunities of community.
POST /communities - Create new community at top level. You must post community.
POST /communities/{communityId}/collections - Create new collections in community. You must post Collection.
POST /communities/{communityId}/communities - Create new subcommunity in community. You must post Community.
PUT /communities/{communityId} - Update community. You must put Community
DELETE /communities/{communityId} - Delete community.
DELETE /communities/{communityId}/collections/{collectionId} - Delete collection in community.
DELETE /communities/{communityId}/communities/{communityId2} - Delete subcommunity in community.

...

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/{GET /collections/{collectionId} - Return collection with id.
GET /collections/{collectionId}/items - Return all items of collection. Use the limit parameter to control items per response (default 100) and offset for paging.
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. Use the limit parameter to control items per response (default 100) and offset for paging.
POST /items/find-by-metadata-field - Find items by metadata entry. You must post a MetadataEntry.
Jira
server DuraSpace JIRA
serverId c815ca92-fd23-34c2-8fe3-956808caf8c5
key DS-2501
POST /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.

...

GET /bitstreams - Return all bitstreams in DSpace. Use the limit parameter to control items per response (default 100) and offset for paging.
GET /bitstreams/{bitstream id} - Return bitstream.
GET /bitstreams/{bitstream id}/policy - Return bitstream policies.
GET /bitstreams/{bitstream id}/retrieve - Return data of bitstream.
POST /bitstreams/{bitstream id}/policy - Add policy to item. You must post a ResourcePolicy
PUT /bitstreams/{bitstream id}/data - Update data/file of bitstream. You must put the data
PUT /bitstreams/{bitstream id} - Update metadata of bitstream. You must put a Bitstream, does not alter the file/data
DELETE /bitstreams/{bitstream id} - Delete bitstream from DSpace.
DELETE /bitstreams/{bitstream id}/policy/{policy_id} - Delete bitstream policy.

You can access the parent object of a Bitstream (normally an Item, but possibly a Collection or Community when it is its logo) through: /bitstreams/:bitstreamID?expand=parent

As the documentation may state "You must post a ResourcePolicy" or some other object type, this means that there is a structure of data types, that your XML or JSON must be of type, when it is posted in the body.

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

Handle

In DSpace, Communities, Collections, and Items typically get minted a Handle Identifier. You can reference these objects in the REST API by their handle, as opposed to having to use the internal item-ID.

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

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

{"id":456,"name":"Reports Community","handle":"10766/10213","type":"community","link":"/rest/communities/456","expand":["parentCommunity","collections","subCommunities","logo","all"{"id":456,"name":"Reports Community","handle":"10766/10213","type":"community","link":"/RESTapi/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":[]}

...

{"id":730,"name":"Annual Reports Collection","handle":"10766/10214","type":"collection","link":"/RESTapirest/collections/730","expand":["parentCommunityList","parentCommunity","items","license","logo","all"],"logo":null,"parentCommunity":null,"parentCommunityList":[],"items":[],"license":null,"copyrightText":"","introductoryText":"","shortDescription":"","sidebarText":"","numberItems":3}

...

{"id":14301,"name":"2015 Annual Report","handle":"123456789/13470","type":"item","link":"/RESTapirest/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"}

...

{"id":47166,"name":"appearance and physiology 100 percent copied from wikipedia.pdf","handle":null,"type":"bitstream","link":"/RESTapirest/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}

...

{"key":"dc.description.abstract", "value":"This is the description abstract", "langlanguage": null}

User Object

{"email":"test@dspace.org","password":"pass"}

...

{"okay":true,"authenticated":true,"email":"test@dspace.org","fullname":"DSpace Test User","token":"6d45daaa-7b02-4ae7-86de-a960838fae5c"}

Introduction to Jersey for developers

...

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
http://localhost:8080/rest/items/:ID?userIP=ip&userAgent=userAgent&xforwarderforxforwardedfor=xforwarderforxforwardedfor

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

...

.

...

<Context path="/rest" docBase="/dspace/webapps/rest" allowLinking="true"/>

Additional Information

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

Usage examples can be found at: https://github.com/BrunoNZ/dspace-rest-requests

All Versions

DSpace Documentation

Page tree

Versions Compared

Old Version 4

New Version Current

Key

Disabling SSL

Communities

Communities

Model - Object data types

Handle

Model - Object data types

Introduction to Jersey for developers

Deploying the DSpace REST API in your Servlet Container

Additional Information

All Versions

DSpace Documentation

Page tree

Page History

Versions Compared

Old Version 4

New Version Current

Key

Disabling SSL

Communities

Communities

Model - Object data types

Handle

Model - Object data types

Introduction to Jersey for developers

Deploying the DSpace REST API in your Servlet Container

Additional Information