Page tree

Versions Compared

Key

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

...

MethodEndpointDescription
GET/

REST API static documentation page listing available endpoints and their function.


Example:

https://demo.dspace.org/rest

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://demo.dspace.org/rest/test

https://demo.dspace.org/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://demo.dspace.org/rest/status

https://demo.dspace.org/rest/status

Example Request (JSON):

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

Example JSON Response:

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


...

HTTP methodREST endpointDescription
GET/communities

Return an array of all the communities in the repository. The results are paginated.

Example:

https://demo.dspace.org/rest/communities

GET/communities/top-communities

Return an array of all top-level communities. The results are paginated.

Example:

https://demo.dspace.org/rest/communities/top-communities

GET/communities/{community id}

Return the specified community.

Example:

https://demo.dspace.org/rest/communities/e97b847b-2fd5-4751-8d91-fcf0d8895b81

GET/communities/{community id}/collectionsReturn an array of collections of the specified community. The results are paginated.
GET/communities/{community id}/communitiesReturn an array of sub-communities of the specified community. The results are paginated
POST/communitiesCreate a new community at top level. You must post a community object data type.
POST/communities/{community id}/collectionsCreate a new collections in the specified community. You must post collection object data type.
POST/communities/{community id}/communitiesCreate a new sub-community in the specified community. You must post a community object data type.
PUT/communities/{community id}Update the specified community. You must put community object data type.
DELETE/communities/{community id}Delete the specified community.
DELETE/communities/{community id}/collections/{collection id}Delete the specified collection in the specified community.
DELETE/communities/{community id}/communities/{sub-community id}Delete the specified sub-community in the specified community.

...

HTTP methodREST endpointDescription
GET/collectionsReturn an array of all the collections in the repository. The results are paginated.
GET/collections/{collection id}Return the specified collection.
GET/collections/{collection id}/itemsReturn an array all items of the specified collection. The results are paginated.
POST/collections/{collection id}/itemsCreate an item in the specified collection. You must post an item object data type.
POST/collections/find-collectionFind collection by passed name. Returns the first exact match or nothing. You must post a single string, not a JSON object.
PUT/collections/{collection id}Update the specified collection. You must put a collection object data type.
DELETE/collections/{collection id}Delete the specified collection.
DELETE/collections/{collection id}/items/{item id}Delete the specified item in the specified collection.

...

HTTP methodREST endpointDescription
GET/items

Return an array of all the items in the repository. The results are paginated.

Example:

https://demo.dspace.org/rest/items

GET/items/{item id}Return the specified item.
GET/items/{item id}/metadataReturn metadata of the specified item.
GET/items/{item id}/bitstreamsReturn an array of all the bitstreams of the specified item. The results are paginated.
POST/items/find-by-metadata-fieldFind items by metadata entry. You must post a metadataentry object data type.
POST/items/{item id}/metadataAdd metadata to the specified item. You must post an array of metadataentry object data type.
POST/GET/items/{item id}/bitstreams?name={file name}

Add bitstream to the specified item. You must post the file data and include the name parameter with the value as {file name} in the URL posted to.


Optional query parameters:

description: A description of the bitstream.

groupId: Id of group to set item resource policy to.

year: Year to set embargo date to

month: Month to set embargo date to

day: Day of month to set embargo date to


Example:

/items/{item id}/bitstreams?name=The%20Children%27s%20Crusade%3A%20A%20Duty-Dance%20with%20Death.pdf&description=All%20this%20happened%2C%20more%20or%20less.&groupID=1969&year=2045&month=2&day=13

PUT/items/{item id}/metadataUpdate metadata in the specified item. You must put a metadataentry object data type.

Each metadata entry that will replace all prior matching metadata entries, i.e. if you submit n 'dc.subject' entries all pre-existing 'dc.subject' entries in the item will be deleted and replaced with the n entries
DELETE/items/{item id}Delete the specified item.
DELETE/items/{item id}/metadataClear the metadata of the specified item.
DELETE/items/{item id}/bitstreams/{bitstream id}Delete the specified bitstream of the specified bitstream.

...

HTTP methodREST endpointDescription
GET/bitstreams

Return an array of all the bitstreams in the repository. The results are paginated.

Example:

http://demo.dspace.org/rest/bitstreams

GET/bitstreams/{bitstream id}Return the specified bitstream.
GET/bitstreams/{bitstream id}/policyReturn bitstream policies.
GET/bitstreams/{bitstream id}/retrieveReturn data of bitstream.
POST/bitstreams/{bitstream id}/policyAdd policy to item. You must post a resourcepolicy object data type.
PUT/bitstreams/{bitstream id}/dataUpdate the data/file of the specified bitstream. You must put the data.
PUT/bitstreams/{bitstream id}Update metadata of the specified bitstream. You must put a Bitstream, does not alter the file/data.
DELETE/bitstreams/{bitstream id}Delete the specified bitstream.
DELETE/bitstreams/{bitstream id}/policy/{policy_id}Delete the specified resource policy of the specified bitstream.

...