...

What is DSpace REST API (v4-v6)

The REST API module provides a programmatic interface to DSpace Communities, Collections, Items, and Bitstreams.

DSpace 4 introduced the initial REST API, which did not allow for authentication, and provided only READ-ONLY access to publicly accessible Communities, Collections, Items, and Bitstreams. DSpace 5 builds off of this and allows authentication to access restricted content, as well as allowing Create, Edit and Delete on the DSpace Objects. DSpace 5 REST API also provides improved pagination over resources and searching. There has been a minor drift between the DSpace 4 REST API and the DSpace 5 REST API, so client applications will need to be targeted per version.

Installing the REST API (v4-v6)

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:

...

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-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.

REST Endpoints

The REST API is modeled after the DSpace Objects of Communities, Collections, Items, and Bitstreams. The API is not a straight database schema dump of these entities, but provides some wrapping that makes it easy to follow relationships in the API output.

...

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

Index / Authentication

...

# Can use either POST or GET (POST recommended). Must pass the parameters "email" and "password".
curl -v -X POST --data "email=admin@dspace.org&password=mypass" https://dspace.myu.edu/rest/login

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

curl -v --cookie "JSESSIONID=6B98CF8648BCE57DCD99689FE77CB1B8" https://dspace.myu.edu/rest/status
# This should return <authenticated>true</authenticated>, and information about the authenticated user session

curl -v -L -c cookiejar "https://dspace.myu.edu/rest/shibboleth-login"

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

curl -v -X POST --cookie "JSESSIONID=6B98CF8648BCE57DCD99689FE77CB1B8" https://dspace.myu.edu/rest/logout

curl -v --cookie "JSESSIONID=6B98CF8648BCE57DCD99689FE77CB1B8" https://dspace.myu.edu/rest/status
# This should show <authenticated>false</authenticated>

curl https://dspace.myu.edu/rest/test

REST api is running.

curl -v --cookie "JSESSIONID=6B98CF8648BCE57DCD99689FE77CB1B8" https://dspace.myu.edu/rest/status

curl -v -H "Accept: application/json" --cookie "JSESSIONID=6B98CF8648BCE57DCD99689FE77CB1B8" https://dspace.myu.edu/rest/status

{
  "okay":true,
  "authenticated":true,
  "email":"admin@dspace.org",
  "fullname":"DSpace Administrator",
  "sourceVersion":"6.0",
  "apiVersion":"6"
}

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:

...

1. Using a web browser:
   1. Go to https://dspace.myu.edu/rest/shibboleth-login, 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 "https://dspace.myu.edu/rest/shibboleth-login"

      



   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 "https://dspace.myu.edu/dspace-rest/status" --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

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 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.

Collections

Collections in DSpace are containers of Items. (ex: Engineering Faculty Publications)

• GET /collections - Return all collections of DSpace in array.
• 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.

Items

Items in DSpace represent a "work" and combine metadata and files, known as Bitstreams.

• 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. 
• 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.

Bitstreams

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.

...

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.

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.

Hierarchy

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

...

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.

...

• 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:

...

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

Introduction to Jersey for developers

The REST API for DSpace is implemented using Jersey, the reference implementation of the Java standard for building RESTful Web Services (JAX-RS 1). That means this API should be easier to expand and maintain than other API approaches, as this approach has been widely adopted in the industry. If this client documentation does not fully answer about how an endpoint works, it is helpful to look directly at the Java REST API code, to see how it is implemented. The code typically has required parameters, optional parameters, and indicates the type of data that will be responded.

...

• @Path("/communities"), which then allows it to be routed to http://localhost:8080/communities, this is then the base path for all the requests within this class.

• @GET, which indicates that this method responds to GET http requests

• @POST, which indicates that this method responds to POST http requests
• @PUT, which indicates that this method responds to PUT http requests
• @DELETE, which indicates that this method responds to DELETE http requests
• @Path("/{community_id}"), the path is appended to the class level @Path above, this one uses a variable {community_id}. The total endpoint would be http://localhost:8080/rest/communities/123, where 123 is the ID.
  

• @Consumes({ MediaType.APPLICATION_JSON, MediaType.APPLICATION_XML }), this indicates that this request expects input of either JSON or XML. Another endpoint accepts HTML input.

• @PathParam("community_id") Integer communityId, this maps the path placeholder variable {community_id} to Java int communityID
  
• @QueryParam("userIP") String user_ip, this maps a query param like ?userIP=8.8.4.4 to Java String user_id variable, and user_id == "8.8.4.4"

Configuration for DSpace REST

Recording Proxy Access by Tools

http://localhost:8080/rest/items/:ID?userIP=ip&userAgent=userAgent&xforwardedfor=xforwardedfor

Additional Information

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

...