Versions Compared

Old Version 15

changes.mady.by.user Tim Donohue

Saved on

compared with

New Version 16

changes.mady.by.user Tim Donohue

Saved on

Key

  • This line was added.
  • This line was removed.
  • Formatting was changed.

...

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: http 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

...

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 "https:/ -X POST --data "email=admin@dspace.org&password=mypass" https://dspace.myu.edu/rest/login?email=admin@dspace.org&password=dspace"

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" --cookie "JSESSIONID=6B98CF8648BCE57DCD99689FE77CB1B8"
# 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 may 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.

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 --vcookie "JSESSIONID=6B98CF8648BCE57DCD99689FE77CB1B8" https://dspace.myu.edu/rest/logout" --cookie "JSESSIONID=6B98CF8648BCE57DCD99689FE77CB1B8"

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" --cookie "JSESSIONID=6B98CF8648BCE57DCD99689FE77CB1B8"
# 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" --cookie "JSESSIONID=6B98CF8648BCE57DCD99689FE77CB1B8"

Example Request (JSON):

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

Example JSON Response:

Code Block
{"okay":true,"authenticated":true,"email":"dspacedemo+admin@gmail.com","fullname":"DSpace Administrator","sourceVersion":"6.0","apiVersion":"6"}

Communities

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

...