Versions Compared

Old Version 23

changes.mady.by.user Tom Desair

Saved on

compared with

New Version 24

changes.mady.by.user Mark H. Wood

Saved on

Key

  • This line was added.
  • This line was removed.
  • Formatting was changed.
Comment: Explained array pagination, with example

...

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
languagebash
curl -s -H "Accept: application/json" http://localhost:8080/rest/collections?offset=5\&limit=5


Index / Authentication

Note

REST API Authentication has changed in DSpace 6.x.  It now uses a JSESSIONID cookie (see below).  The previous (5.x) authentication scheme using a rest-dspace-token is no longer supported.


MethodEndpointDescription
GET/REST API static documentation page
POST/login

Login to the REST API using a DSpace EPerson (user). It returns a JSESSIONID cookie, that can be used for future authenticated requests.

Example Request:

Code Block
# 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

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) requests:

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

Invalid email/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.

GET/shibboleth-login

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


POST/logout

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/logout

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:

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

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:

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

Example Response:

Code Block
REST api is running.


GET/status

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

Example Request (JSON):

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

Example JSON Response:

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


Shibboleth Apache configuration for the REST API

...

Configuration for DSpace REST

Propertyrest.stats
Example Valuetrue
Informational NoteBoolean value indicates whether statistics should be recorded for access via the REST API; Defaults to 'false'.

Recording Proxy Access by Tools

...