All Versions
- DSpace 7.x (Current Release)
- DSpace 8.x (Unreleased)
- DSpace 6.x (EOL)
- DSpace 5.x (EOL)
- More Versions...
...
Warning | ||
---|---|---|
| ||
This documentation describes the deprecated DSpace v4-6 REST API. This old API is still available in DSpace 7, but will be removed in DSpace 8.The new DSpace 7 REST API is described at https://github.com/DSpace/Rest7Contract/blob/master/README.md We highly recommend all users migrate scripts/tools to use the new REST API. This API is no longer actively supported or maintained. |
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.
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:
Code Block |
---|
<Context path="/rest" docBase="/dspace/webapps/rest" /> |
In DSpace 4, the initial/official Jersey-based REST API was added to DSpace. The DSpace 4 REST API provides READ-ONLY access to DSpace Objects.
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.
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.
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.
Info | ||
---|---|---|
| ||
Note: You must set your request header's "Accept" property to either JSON (application/json) or XML (application/xml) depending on the format you prefer to work with. |
Example usage from command line in XML format with pretty printing:
Code Block |
---|
curl -s -H "Accept: application/xml" http://localhost:8080/rest/communities | xmllint --format - |
Example usage from command line in JSON format with pretty printing:
Code Block |
---|
curl -s -H "Accept: application/json" http://localhost:8080/rest/communities | python -m json.tool |
For this documentation, we will assume that the URL to the "REST" webapp will be http://localhost:8080/rest/ for production systems, this address will be slightly different, such as: https://demo.dspace.org/rest/. The path to an endpoint, will go after the /rest/, such as /rest/communities, all-together this is: http://localhost:8080/rest/communities
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 .
Two other query parameters of note are limit
and offset. Endpoints which return arrays of objects, such as
/communities, are "paginated": the full list is broken into "pages" which start at offset
from the beginning of the list and contain at most limit
elements. By repeated queries you can retrieve any portion of the array or all of it. Offsets begin at zero. So, to retrieve the sixth through tenth elements of the full list of Collections, you could do this:
This older REST API is disabled in the build by default. To build it, you must run:
Code Block |
---|
# The "-Pdspace-rest" flag will build the deprecated "rest" webapp alongside the new "server" webapp
mvn clean package -Pdspace-rest |
The REST API deploys as a separate "rest" 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:
Code Block |
---|
<Context path="/rest" docBase="/dspace/webapps/rest" /> |
In DSpace 4, the initial/official Jersey-based REST API was added to DSpace. The DSpace 4 REST API provides READ-ONLY access to DSpace Objects.
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.
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.
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.
Info | ||
---|---|---|
| ||
Note: You must set your request header's "Accept" property to either JSON (application/json) or XML (application/xml) depending on the format you prefer to work with. |
Example usage from command line in XML format with pretty printing:
Code Block |
---|
curl -s -H "Accept: application/xml" http://localhost:8080/rest/communities | xmllint --format - |
Example usage from command line in JSON format with pretty printing:
Code Block | ||
---|---|---|
curl | ||
Code Block | ||
| ||
curl -s -H "Accept: application/json" http://localhost:8080/rest/collections?offset=5\&limit=5 |
Note |
---|
REST API Authentication has changed in DSpace 6.x. It now uses a |
communities | python -m json.tool |
For this documentation, we will assume that the URL to the "REST" webapp will be http://localhost:8080/rest/ for production systems, this address will be slightly different, such as: https://demo.dspace.org/rest/. The path to an endpoint, will go after the /rest/, such as /rest/communities, all-together this is: http://localhost:8080/rest/communities
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 .
Two other query parameters of note are limit
and offset. Endpoints which return arrays of objects, such as
/communities, are "paginated": the full list is broken into "pages" which start at offset
from the beginning of the list and contain at most limit
elements. By repeated queries you can retrieve any portion of the array or all of it. Offsets begin at zero. So, to retrieve the sixth through tenth elements of the full list of Collections, you could do this:
Code Block | ||
---|---|---|
| ||
curl -s -H "Accept: application/json" http://localhost:8080/rest/collections?offset=5\&limit=5 |
Note |
---|
REST API Authentication has changed in DSpace 6.x. It now uses a |
Method | Endpoint | Description | ||||||||||||||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
GET | / | REST API static documentation page | ||||||||||||||||||||||
POST | /login | Login to the REST API using a DSpace EPerson (user). It returns a Example Request:
| ||||||||||||||||||||||
Method | Endpoint | Description | ||||||||||||||||||||||
GET | / | REST API static documentation page | ||||||||||||||||||||||
POST | /login | Login to the REST API using a DSpace EPerson (user). It returns a Example Request:
Example Response:
Example of using JSESSIONID cookie for subsequent (authenticated) requests:
Invalid email/password combinations will receive an Please note, special characters need to be HTTP URL encoded. | ||||||||||||||||||||||
GET | /shibboleth-login |
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 we 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 "http://localhost:8080/dspace-rest/status" --cookie "JSESSIONID=0633C6379266A283E53F65DF8EF61AB9" |
Logout from the REST API, by providing a JSESSIONID
cookie. After being posted this cookie will no longer work.
Example Request:
Code Block |
---|
curl -v -X POST --cookie "JSESSIONID=6B98CF8648BCE57DCD99689FE77CB1B8" https://dspace.myu.edu/rest/logoutlogin |
Example Response:
Code Block |
---|
HTTP/1.1 200 OK
Set-Cookie: JSESSIONID=6B98CF8648BCE57DCD99689FE77CB1B8; Path=/rest/; Secure; HttpOnly |
Example of using JSESSIONID cookie for subsequent (authenticated) requestsAfter posting a logout request, cookie is invalidated and the "/status" path should show you as unauthenticated (even when passing that same cookie). For example:
Code Block |
---|
curl -v --cookie "JSESSIONID=6B98CF8648BCE57DCD99689FE77CB1B8" https://dspace.myu.edu/rest/status # This should showreturn <authenticated>false<<authenticated>true</authenticated>, and information about the authenticated user session |
Invalid token will result in HTTP 400 Invalid Requestemail/password combinations will receive an HTTP 401 Unauthorized
response.
Please note, special characters need to be HTTP URL encoded.
For example, an email address like dspacedemo+admin@gmail.com
(notice the + special character) would need to be encoded as dspacedemo%2Badmin@gmail.com
.
Login to the REST API using Shibboleth authentication. In order to work, this requires additional Apache configuration. To authenticate, execute the following steps:
1. Call the REST Shibboleth login point with a Cookie jar:
Code Block |
---|
curl -v -L -c cookiejar " |
Returns string "REST api is running", for testing that the API is up.
Example Request:
https://dspace.myu.edu/rest/ |
Example Response:
Code Block |
---|
REST api is running. |
Receive information about the currently authenticated user token, or the API itself (e.g. version information).
Example Request (XML by default):
Code Block |
---|
curl -v --cookie "JSESSIONID=6B98CF8648BCE57DCD99689FE77CB1B8" https://dspace.myu.edu/rest/status |
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 we 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 |
"http://localhost:8080/dspace-rest/status" --cookie "JSESSIONID= |
Example JSON Response:
Code Block |
---|
{
"okay":true,
"authenticated":true,
"email":"admin@dspace.org",
"fullname":"DSpace Administrator",
"sourceVersion":"6.0",
"apiVersion":"6"
} |
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:
| ||||||||
POST | /logout | Logout from the REST API, by providing a Example Request:
After posting a logout request, cookie is invalidated and the "/status" path should show you as unauthenticated (even when passing that same cookie). For example:
Invalid token will result in HTTP 400 Invalid Request | ||||||
GET | /test | Returns string "REST api is running", for testing that the API is up. Example Request:
Example Response:
| ||||||
GET | /status | Receive information about the currently authenticated user token, or the API itself (e.g. version information). Example Request (XML by default):
Example Request (JSON):
Example JSON Response:
|
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:
Code Block |
---|
<Location "/rest/shibboleth-login"> |
Code Block |
<Location "/rest/shibboleth-login"> AuthType shibboleth ShibRequireSession On # Please note that setting ShibUseHeaders to "On" is a potential security risk. AuthType shibboleth ShibRequireSession On # Please note that setting ShibUseHeaders to "On" is a potential security risk. # You may wish to set it to "Off". See the mod_shib docs for details about this setting: # https://wiki.shibboleth.net/confluence/display/SHIB2/NativeSPApacheConfig#NativeSPApacheConfig-AuthConfigOptions # Here's a good guide to configuring Apache + Tomcat when this setting is "Off": # https://www.switch.ch/de/aai/support/serviceproviders/sp-access-rules.html#javaapplications ShibUseHeaders On require valid-user </Location> |
You can test your configuration in 3 different ways:
https://wiki.shibboleth.net/confluence/display/SHIB2/NativeSPApacheConfig#NativeSPApacheConfig-AuthConfigOptions
# Here's a good guide to configuring Apache + Tomcat when this setting is "Off":
# https://www.switch.ch/de/aai/support/serviceproviders/sp-access-rules.html#javaapplications
ShibUseHeaders On
require valid-user
</Location> |
You can test your configuration in 3 different ways:
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./rest/shibboleth-login
URL. You should then see a blank page but in the response headers, the JSESSIONID cookie should be present./rest/status
and you should see information on the current authenticated ePerson.Code Block |
---|
curl -v -L -c cookiejar "https://dspace.myu.edu/rest/shibboleth-login" |
/rest/shibboleth-login
URL which will return you the JSESSIONID.Using that JSESSIONID, check if you have authenticated successfully:
Code Block |
---|
curl -v " |
https://dspace.myu.edu/dspace-rest/ |
/rest/shibboleth-login
URL. You should then see a blank page but in the response headers, the JSESSIONID cookie should be present./rest/status
and you should see information on the current authenticated ePerson.status" --cookie "JSESSIONID=0633C6379266A283E53F65DF8EF61AB9" |
_shibsession_64656661756c74687...
You can also grab this cookie from your browser.Double check that the cookie you took is valid:
Code Block |
---|
curl -v -L -c cookiejar "'https://dspace.myu.edu/rest/shibboleth-login" |
/rest/shibboleth-login
URL which will return you the JSESSIONID.-url/Shibboleth.sso/Session' -H 'Cookie: _shibsession_64656661756c7468747470733a2f2f7265706f7369746f72792e636172646966666d65742e61632e756b2f73686962626f6c657468=_a8d3ad20d8b655250c7357f7ac0e2910;' |
Use this cookie to obtain a Tomcat JSESSIONID:Using that JSESSIONID, check if you have authenticated successfully:
Code Block |
---|
curl -v "'https://dspace.myu.edu/dspace-rest/status" --cookie "JSESSIONID=0633C6379266A283E53F65DF8EF61AB9" |
-url/rest/shibboleth-login' -H 'Cookie: _shibsession_64656661756c7468747470733a2f2f7265706f7369746f72792e636172646966666d65742e61632e756b2f73686962626f6c657468=_a8d3ad20d8b655250c7357f7ac0e2910;' |
Use the returned JSESSIONID to check if you have authenticated successfully
_shibsession_64656661756c74687...
You can also grab this cookie from your browser.Double check that the cookie you took is valid:
Code Block |
---|
curl -v 'https"http://dspace-url/Shibboleth.sso/Session' -H 'Cookie: _shibsession_64656661756c7468747470733a2f2f7265706f7369746f72792e636172646966666d65742e61632e756b2f73686962626f6c657468=_a8d3ad20d8b655250c7357f7ac0e2910;' |
Use this cookie to obtain a Tomcat JSESSIONID:
Code Block |
---|
curl -v 'https://dspace-url/rest/shibboleth-login' -H 'Cookie: _shibsession_64656661756c7468747470733a2f2f7265706f7369746f72792e636172646966666d65742e61632e756b2f73686962626f6c657468=_a8d3ad20d8b655250c7357f7ac0e2910;' |
Use the returned JSESSIONID to check if you have authenticated successfully:
Code Block |
---|
curl -v "http://dspace-url/rest/status" --cookie "JSESSIONID=0633C6379266A283E53F65DF8EF61AB9" |
Communities in DSpace are used for organization and hierarchy, and are containers that hold sub-Communities and Collections. (ex: Department of Engineering)
Collections in DSpace are containers of Items. (ex: Engineering Faculty Publications)
-url/rest/status" --cookie "JSESSIONID=0633C6379266A283E53F65DF8EF61AB9" |
Communities in DSpace are used for organization and hierarchy, and are containers that hold sub-Communities and Collections. (ex: Department of Engineering)
Collections in DSpace are containers of Items. (ex: Engineering Faculty Publications)
POST /collections/{collectionId}/items - Create posted item in collection. You must post an Item
Code Block |
---|
curl -v -H "Content-Type: application/json"
--cookie "JSESSIONID=6B98CF8648BCE57DCD99689FE77CB1B8"
--data "{\"metadata\":[ {\"key\": \"dc.title\", \"value\": \"Testing Item\"}, {\"key\": \"dc.contributor.author\", \"value\": \"Jane Smith\"}]}"
https://dspace-url/rest/[collection-uuid]/items |
Items in DSpace represent a "work" and combine metadata and files, known as 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.
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.
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).
...
Note: since the schema object contains no data fields, the following method has not been implemented: PUT /registries/schema/{schema_id}
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.
...
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"}
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.
...
@GET, which indicates that this method responds to GET http requests
@Consumes({ MediaType.APPLICATION_JSON, MediaType.APPLICATION_XML }), this indicates that this request expects input of either JSON or XML. Another endpoint accepts HTML input.
Property | rest.stats |
---|---|
Example Value | true |
Informational Note | Boolean value indicates whether statistics should be recorded for access via the REST API; Defaults to 'false'. |
For the purpose of more accurate statistics, a web-based tool may specify who is using it, by adding parameters to the request:
Code Block |
---|
http://localhost:8080/rest/items/:ID?userIP=ip&userAgent=userAgent&xforwardedfor=xforwardedfor |
If no parameters are given, the details of the HTTP request's sender are used in statistics. This enables tools to record the details of their user rather than themselves.
Additional information can be found in the README for dspace-rest, and in the GitHub Pull Request for DSpace REST (Jersey).
...