6.93 KB

#DSpace REST API (Jersey)

A RESTful web services API for DSpace, built using JAX-RS1 JERSEY.

##Getting Started This REST API is integrated directly into the DSpace codebase.

  • Rebuild as usual: mvn + ant
  • Deploy the webapp (i.e to Tomcat)
    • <Context path="/rest" docBase="/dspace/webapps/rest" />

REST API can do all CRUD (create, read, update, delete) operations over communities, collections, items, bitstream and bitstream policies. Without logging into the REST API, you have read access as an anonymous user (member of the Anonymous group). If you want to make changes in DSpace using the REST API, you must log into the API using the "login" endpoint and then use the returned token in request header of your subsequent API calls.


Resource CREATE READ list READ single Edit Delete Search
/communities Y Y Y Y Y
/collections Y Y Y Y Y Y
/items Y Y Y Y Y Y
/bitstreams Y Y Y Y Y

Search in collections is possible only by name and search in items only by metadata field.

###Index Get information on how to use the API

Test whether the REST API is running and available

Log into REST API

Logout from REST API

Get status of REST API and the logged-in user

###Communities View the list of top-level communities

View the list of all communities

View a specific community

View the list of subcollections in community

View the list of subcommunities in community

Create new top-level community

Create new subcollection in community

Create new subcommunity in community

Update community

Delete community

Delete subcollection in community

Delete subcommunity in community

###Collections View the list of collections

View a specific collection

View items in collection

Create item in collection

Find collection by name

Update collection

Delete collection

Delete item in collection

###Items View the list of items

View speciific item

View an Item and view its bitstreams

View an Item, and view its metadata

Find item by metadata

Add metadata to item

Create bitstream in item

Update metadata in item

Delete item

Delete all metadata in item

Delete bitstream in item

###Bitstreams View the list of bitstreams

View information about a bitstream

View/Download a specific Bitstream

View the list of policies of bitstream

Add policy to bitstream

Update bitstream

Update data of bitstream

Delete bitstream

Delete policy of bitstream

####Statistics Recording view events of items and download events of bitstreams (set stats = true in rest.cfg to enable recording of events) http://localhost:8080/rest/items/:ID?userIP=ip&userAgent=userAgent&xforwardedfor=xforwardedfor If no parameters are given, the details of the HTTP request sender are used in statistics. This enables tools like proxies to supply the details of their user rather than themselves.

###Handles Lookup a DSpaceObject by its Handle, this produces the name/ID that you look up in /bitstreams, /items, /collections, /communities

##Expand There is an ?expand= query parameter for more expensive operations. You can add it at the end of the request URL. It is optional, all, some or none. The response will usually indicate what the available "expand" options are.

##HTTP Responses

  • 200 OK - The requested object/objects exists
  • 401 Unauthorized - The anonymous user does not have READ access to that object
  • 404 Not Found - The specified object doesn't exist
  • 405 Method Not Allowed - Wrong request method (GET,POST,PUT,DELETE) or wrong data format (JSON/XML).
  • 415 Unsupported Media Type - Missing "Content-Type: application/json" or "Content-Type: application/xml" request header
  • 500 Server Error - Likely a SQLException, IOException, more details in the logs.