...

What is DSpace REST API

The REST API module exposes machine readable representations of content in provides a programmatic interface to DSpace Communities, Collections, Items, and Bitstreams.The

DSpace 4 .0 REST API (Jersey) allows for data in DSpace to be re-used by external systems to make new uses of your data. The DSpace 4.0 REST API provides introduced the initial REST API, which did not allow for authentication, and provided only READ-ONLY access via JSON or XML to publicly accessibly accessible Communities, Collections, Items, and Bitstreams. Only non-hidden item metadata (e.g. provenance is hidden by default) are exposed at the Item endpoint. We intend that future DSpace releases will grow and evolve the REST API to support a greater set of features, based on community input and support. This Jersey implementation of a REST API for DSpace is not related to other add-on modules providing REST-API support for DSpace, such as GSOC REST API, Wijiti REST API, Hedtek REST API, or SimpleREST. 

REST Endpoints

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

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:

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

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-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 We have modeled the DSpace entities 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.

...

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 .

Index

• GET / - It returns the REST endpoint documentation page.
• GET /test - Return string "REST api is running", for testing that API is up.
• GET /status - Return information about the currently authenticated session. 
• POST /login - Method to login into DSpace RESTful api. You must post User class. Example: {"email":"test@dspace","password":"pass"}. It returns an authentication token which will be needed for future requests to authenticated endpoints. Use the token in header "rest-dspace-token"
• POST /logout - Method to logout from DSpace RESTful api. You must post request with header "rest-dspace-token" token, after which time, that token will no longer work.

Communities

• 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

• 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

• 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

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

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.

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":"/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":[]}

Collection Object

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

Item Object

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

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

[{"id":317127,"action":"READ","epersonId":-1,"groupId":0,"resourceId":47166,"resourceType":"bitstream","rpDescription":null,"rpName":null,"rpType":"TYPE_INHERITED","startDate":null,"endDate":null}]

MetadataEntry Object

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

User Object

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

Status Object

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

Communities

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

Collections

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

...

You can access all the collections in a specific community through: /communities/:communityID?expand=all

Items

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

...

You can access all the items in a specific collection through: /collections/:collectionID?expand=items

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.

...

Introduction to Jersey for developers

The REST API for DSpace 4.0 is implemented using Jersey, the reference implementation of the Java standard for building RESTful Web Services (JAX-RS 1, JSR 311). 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.

Below is some sample Jersey code of how you wire up resources, choose to serialize to HTML, JSON or XML. And between display single-entity vs. display list-of-entities.

...

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.

There was no central ProviderRegistry that you have to declare your path. Instead, the code is driven by annotations, here is a list of annotations used in the code for CommunitiesResource.java:

...

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

...