All Versions


DSpace Documentation


Page tree

Current Release

This documentation covers the latest release of DSpace, version 7.x. Looking for another version? See all documentation.

Skip to end of metadata
Go to start of metadata

Overview

The REST API for DSpace is provided as part of the "server" webapp ([dspace-source]/dspace-server-webapp/).  It is available on the `/api/` subpath of that webapp (i.e. ${dspace.server.url}/api/), though a human browseable/searchable interface (using the HAL Browser) is also available at the root path (i.e. ${dspace.server.url}).

The REST API only responds in JSON at this time.

REST Contract / Documentation

The REST Contract is maintained in GitHub at https://github.com/DSpace/RestContract/blob/main/README.md 

This contract provides detailed information on how to interact with the API, what endpoints are available, etc.  All features/capabilities of the DSpace UI are available in this API.

REST Configuration

The following REST API configurations are provided in [dspace]/config/rest.cfg and may be overridden in your local.cfg

Property:

rest.cors.allow-origins

Example Value:

rest.cors.allow-origins = ${dspace.ui.url}

Informational Note:

Allowed Cross-Origin-Resource-Sharing (CORS) origins (in "Access-Control-Allow-Origin" header). Only these origins (client URLs) can successfully authenticate with your REST API. Defaults to ${dspace.ui.url} if unspecified (as the UI must have access to the REST API).  If you customize that setting, MAKE SURE TO include ${dspace.ui.url} in that setting if you wish to continue trusting the UI.

Multiple allowed origin URLs may be comma separated (or this configuration can be defined multiple times). Wildcard value (*) is NOT SUPPORTED.

Keep in mind any URLs added to this setting must be an exact match with the origin: mode (http vs https), domain, port, and subpath(s) all must match.. So, for example, these URLs are all considered different origins: "http://mydspace.edu", "http://mydspace.edu:4000" (different port), "https://mydspace.edu" (http vs https), "https://myapp.mydspace.edu" (different domain), and "https://mydspace.edu/myapp" (different subpath).

NOTE: If you modify this value to allow additional UIs to access your REST API, then you may also need to modify proxies.trusted.ipranges to trust the IP address of each UI.  Modifying trusted proxies is only necessary if the X-FORWARDED-FOR header must be trusted from each additional UIs. (The DSpace UI currently requires the X-FORWARDED-FOR header to be trusted). By default, proxies.trusted.ipranges will only trust the IP address of the ${dspace.ui.url} configuration.

(Requires reboot of servlet container, e.g. Tomcat, to reload)

Property:

rest.cors.allow-credentials

Example Value:

rest.cors.allow-credentials = true

Informational Note:

Whether or not to allow credentials (e.g. cookies) sent by the client/browser in CORS requests (in "Access-Control-Allow-Credentials" header).

For DSpace, this MUST be set to "true" to support CSRF checks (which use Cookies) and external authentication via Shibboleth (and similar). Defaults to "true" if unspecified. (Requires reboot of servlet container, e.g. Tomcat, to reload)

Property:

rest.projections.full.max

Example Value:

rest.projections.full.max = 2

Informational Note:

This property determines the max embeddepth for a FullProjection. This is also used by the SpecificLevelProjection
as a fallback in case the property is defined on the bean. Usually, this should be kept as-is for best performance.

Property:

rest.projection.specificLevel.maxEmbed

Example Value:

rest.projection.specificLevel.maxEmbed = 5

Informational Note:

This property determines the max embed depth for a SpecificLevelProjection. Usually, this should be kept as-is for best performance.

Property:

rest.properties.exposed

Example Value:

rest.properties.exposed = plugin.named.org.dspace.curate.CurationTask
rest.properties.exposed = google.analytics.key

Informational Note:

Define which configuration properties are exposed through the http://<dspace.server.url>/api/config/properties/ REST API endpoint. 

If a rest request is made for a property which exists, but isn't listed here, the server will respond that the property wasn't found. This property can be defined multiple times to allow access to multiple configuration properties.

Generally, speaking, it is ONLY recommended to expose configuration settings where they are necessary for the UI or client, as exposing too many configurations could be a security issue.  This is why we only expose the two above settings by default.

Technical Design

The REST API & Server Webapp are built on Spring Boot and Spring HATEOAS, using Spring Security. It also aligns with Spring Data REST (though at this time it doesn't use it directly because of incompatibility with the DSpace data model).

The REST API is stateless, aligns with HATEOAS (Hypertext as the Engine of Application State) principles, returning HAL formatted JSON.  This allows the REST API to be easily browsable/interactable via third-party tools that understand HAL & HATEOAS, such as the HAL BrowserJSON Web Tokens (JWT) are used to store state/session information between requests.

For better security, the REST API requires usage of CSRF tokens for all modifying requests.

More information can be found in the REST Contract at https://github.com/DSpace/RestContract/blob/main/README.md#rest-design-principles

  • No labels