Child pages
  • DSpace REST API Home
Skip to end of metadata
Go to start of metadata

KnowledgeArc's DSpace REST API provides the most comprehensive programming interface to the DSpace digital asset management system, exposing additional endpoints not provided by atlernative implementations. It also aims to provide a more structured API, improve response performance and reduce server load.

The KnowledgeArc DSpace REST API is currently the longest running REST API project and has been used in production environments since 2011.

If you would like to participate in the development of this API implementation, please feel free to sign up, or fork the code and make your changes via Github. The REST API is fully integrated into DSpace and is available at https://github.com/knowledgearc/DSpace.

Alternatively, you are welcome to merge any or all parts of this API implementation into your own projects.

Download

The REST API Module

The DSpace REST API code is available at https://github.com/knowledgearc/dspace-rest-api.

There are currently three versions of the REST API that are actively maintained:

REST API for DSpace 5.x: https://github.com/knowledgearc/dspace-rest-api/tree/dspace-rest-5.1

REST API for DSpace 3.x; https://github.com/knowledgearc/dspace-rest-api/tree/dspace-rest-3_x

REST API for DSpace 1.8; https://github.com/wijiti/dspace-rest-api/tree/dspace-rest-1.8.1

DSpace (REST API Version)

A customized version of DSpace has been created with REST API integrated as part of the distribution:

DSpace w/ REST API 5.x; https://github.com/knowledgearc/DSpace/tree/dspace-5.1

DSpace w/ REST API 3.x; https://github.com/wijiti/DSpace/archive/dspace-3_x.zip

DSpace w/ REST API 1.8.x; https://github.com/wijiti/DSpace/archive/dspace-1_8_x.zip

Installation

There are three ways to install and test the DSpace REST API. For both approaches you should have Apache Maven installed.

1) Install as an webapp (This way assumes you are running DSpace under Tomcat.)

  • Locate the build.properties under the base folder, and alter the only attribute - dspace.dir to the current location of main DSpace configuration file of your DSpace instance.

    # DSpace installation directory. This is the location where you want to install DSpace.
    dspace.dir=/dspace
  • [Only for REST API 3.x version] Locate src/main/webapp/WEB-INF/web.xml (under directory you just downloaded DSpace REST API). Find variable named dspace-config and alter it to point to current location of dspace.cfg file of your DSpace instance. 

      <context-param>
        <param-name>dspace-config</param-name>
        <param-value>${dspace.dir}/config/dspace.cfg</param-value>
        <!-- <param-value>/dspace/config/dspace.cfg</param-value> -->
      </context-param>
  • [Only for REST API 1.8 version] Locate src/main/webapp/WEB-INF/web.xml (under directory you just downloaded DSpace REST API). Find variable named dspace.dir and alter it to point to current location of main DSpace configuration file of your DSpace instance.

      <context-param>
          <description>
              The location of the main DSpace configuration file
          </description>
          <param-name>dspace.dir</param-name>
          <param-value>${dspace.dir}</param-value>
        <!-- <param-value>/dspace</param-value> -->
      </context-param>
  • Position into the root directory of the REST API and type mvn package. If everything goes well, in target directory will be packaged dspace-rest-[version].war. 
  • Deploy this file (changing the name to rest.war)  to your current Tomcat webapp directory. The application will be available under http://localhost:8080/rest/ by default.
  • If it shows error for missing some classes of jars, please download and place it to the WEB-INF\lib folder.

2) Install as a DSpace Module in a source code installation

For REST API 5.x version

  • The DSpace includes the dspace-rest directory already, so delete all codes below it.
  • Checkout the REST API source code into dspace-rest directory. 
  • Locate the build.properties under the dspace-rest directory, and alter the only attribute - dspace.dir to the current location of main DSpace configuration file of your DSpace instance.

    # DSpace installation directory. This is the location where you want to install DSpace.
    dspace.dir=/dspace
  • Once you rebuild your dspace-src code with mvn package and ant update, you will need to copy the compiled rest.war file produced in the target directory to tomcat's webapps directory.

For REST API 3.x and 1.8 version

  • Create a new directory for the REST module source code - dspace-src/dspace-rest.
  • Checkout the REST API source code into the new directory
  • Incorporate the new module into your project by adding a new <profile> element for dspace-rest in dspace-src/pom.xml and adding necessary dependency.

    For REST API 3.x version

    <profile>
       <id>dspace-rest</id>
        <activation>
            <file>
                <exists>dspace-rest/pom.xml</exists>
            </file>
        </activation>
        <modules>
            <module>dspace-rest</module>
        </modules>
    </profile>
    ..........
    <dependency>
        <groupId>org.dspace</groupId>
        <artifactId>dspace-rest</artifactId>
        <version>3.0</version>
        <type>war</type>
    </dependency>
    <dependency>
        <groupId>org.dspace</groupId>
        <artifactId>dspace-rest</artifactId>
        <version>3.0</version>
        <type>jar</type>
        <classifier>classes</classifier>
    </dependency>

    For REST API 1.8 version

    <profile>
        <id>dspace-rest</id>
        <activation>
            <activeByDefault>true</activeByDefault>
        </activation>
        <modules>
            <module>dspace-rest</module>
        </modules>
    </profile>
    ..........
    <dependency>
        <groupId>org.dspace</groupId>
        <artifactId>dspace-rest</artifactId>
        <version>${project.version}</version>
        <type>war</type>
    </dependency>
  • Create a new directory dspace-src/dspace/modules/rest.

  • Add a sub-directory src/main/webapp and a pom.xml to the created directory dspace-src/dspace/modules/rest. The pom.xml file can be referenced as here. 
    REST API 3.x pom.xml (for 3.1, open file and change <version>3.0</version> to <version>3.1</version>)
    REST API 1.8 pom.xml
  • Add a <profile> to dspace-src/dspace/modules/pom.xml.

    <profile>
        <id>dspace-rest</id>
        <activation>
            <activeByDefault>true</activeByDefault>
        </activation>
        <modules>
            <module>rest</module>
        </modules>
    </profile>


  • Once you rebuild your dspace-src code with mvn package and ant update, you will need to copy the compiled rest.war file produced in the target directory to tomcat's webapps directory.

3) Install DSpace with REST API integrated

Download Wijiti's version of DSpace then package and install as you would a standard DSpace instance.

Note

  • Since for the new endpoints especially for POST item endpoint, it needs to invoke a static method(Item.create method) of Item class to create a new item for creating. But actually the Item.create method is default access modifier, so it can not be accessed by outside of the package which making rest api codes not compiled. In order to make the rest api codes compiled successfully as standalone webapp, we have copied the corresponding Item java source file into rest api codes and made the access modifier change as below. If rest api integrated with dspace codes, it's just need remove the Item java class from rest api codes and do below change for the dspace's codes.
    static Item create(Context context) --> public static Item create(Context context)

API Documentation

DSpace REST API documentation provides 3rd party developers with all the information they require to implement their own DSpace repository integrations.

Navigate space

 

  • No labels