Page History
...
Installing the REST API (v4-v6)
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.
Disabling 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.
REST Endpoints
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 |
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.
Disabling 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.
REST Endpoints
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/. 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
...
Code Block |
---|
<Location "/rest/shibboleth-login">
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:
- Using a web browser:
- Go to
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. - Enter your test credentials and this should take you back to the
/rest/shibboleth-login
URL. You should then see a blank page but in the response headers, the JSESSIONID cookie should be present. - Then go to
/rest/status
and you should see information on the current authenticated ePerson.
- Go to
- Using curl without a Shibboleth Session
- Call the REST Shibboleth login point with a Cookie jar:
Code Block curl -v -L -c cookiejar "https://dspace.myu.edu/rest/shibboleth-login"
- 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 I cannot provide an example here.
- Once you submit the form using curl, you should be taken back to the
/rest/shibboleth-login
URL which will return you the JSESSIONID. Using that JSESSIONID, check if you have authenticated successfully:
Code Block curl -v "
- Go to
shibboleth-login, this should redirect you to the login page of your IdP if you don't have a Shibboleth session yet.https://dspace.myu.edu/dspace-rest/
- Enter your test credentials and this should take you back to the
/rest/shibboleth-login
URL. You should then see a blank page but in the response headers, the JSESSIONID cookie should be present. - Then go to
/rest/status
and you should see information on the current authenticated ePerson.
status" --cookie "JSESSIONID=0633C6379266A283E53F65DF8EF61AB9"
- Call the REST Shibboleth login point with a Cookie jar:
- Using curl with a Shibboleth Session (cookie)
- When you post the Shibboleth login form, the Shibboleth daemon on the DSpace server also returns you a Shibboleth Cookie. This cookie looks like
_shibsession_64656661756c74687...
You can also grab this cookie from your browser. Double check that the cookie you took is valid:
- Call the REST Shibboleth login point with a Cookie jar:
Code Block curl -v -L -c cookiejar "'https://dspace.myu.edu/rest/shibboleth-login"
- 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 I cannot provide an example here.
- Once you submit the form using curl, you should be taken back to the
/rest/shibboleth-login
URL which will return you the JSESSIONID. -url/Shibboleth.sso/Session' -H 'Cookie: _shibsession_64656661756c7468747470733a2f2f7265706f7369746f72792e636172646966666d65742e61632e756b2f73686962626f6c657468=_a8d3ad20d8b655250c7357f7ac0e2910;'
- This should give you information if the Shibboleth session is valid and on the number of attributes.
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
- When you post the Shibboleth login form, the Shibboleth daemon on the DSpace server also returns you a Shibboleth Cookie. This cookie looks like
_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;'
- This should give you information if the Shibboleth session is valid and on the number of attributes.
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"
- When you post the Shibboleth login form, the Shibboleth daemon on the DSpace server also returns you a Shibboleth Cookie. This cookie looks like
Communities
Communities in DSpace are used for organization and hierarchy, and are containers that hold sub-Communities and Collections. (ex: Department of Engineering)
- GET /communities - Returns array of all communities in DSpace.
- GET /communities/top-communities - Returns array of all top communities in DSpace.
- GET /communities/{communityId} - Returns community.
- GET /communities/{communityId}/collections - Returns array of collections of community.
- GET /communities/{communityId}/communities - Returns array of subcommunities of community.
- POST /communities - Create new community at top level. You must post community.
- POST /communities/{communityId}/collections - Create new collections in community. You must post Collection.
- POST /communities/{communityId}/communities - Create new subcommunity in community. You must post Community.
- PUT /communities/{communityId} - Update community. You must put Community
- DELETE /communities/{communityId} - Delete community.
- DELETE /communities/{communityId}/collections/{collectionId} - Delete collection in community.
- DELETE /communities/{communityId}/communities/{communityId2} - Delete subcommunity in community.
Collections
Collections in DSpace are containers of Items. (ex: Engineering Faculty Publications)
-url/rest/status" --cookie "JSESSIONID=0633C6379266A283E53F65DF8EF61AB9"
Communities
Communities in DSpace are used for organization and hierarchy, and are containers that hold sub-Communities and Collections. (ex: Department of Engineering)
- GET /communities - Returns array of all communities in DSpace.
- GET /communities/top-communities - Returns array of all top communities in DSpace.
- GET /communities/{communityId} - Returns community.
- GET /communities/{communityId}/collections - Returns array of collections of community.
- GET /communities/{communityId}/communities - Returns array of subcommunities of community.
- POST /communities - Create new community at top level. You must post community.
- POST /communities/{communityId}/collections - Create new collections in community. You must post Collection.
- POST /communities/{communityId}/communities - Create new subcommunity in community. You must post Community.
- PUT /communities/{communityId} - Update community. You must put Community
- DELETE /communities/{communityId} - Delete community.
- DELETE /communities/{communityId}/collections/{collectionId} - Delete collection in community.
- DELETE /communities/{communityId}/communities/{communityId2} - Delete subcommunity in community.
Collections
Collections in DSpace are containers of Items. (ex: Engineering Faculty Publications)
- GET /collections - Return all collections of DSpace in array.
- GET /collections/{collectionId} - Return collection with id.
- GET /collections/{collectionId}/items - Return all items of collection.
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
- GET /collections - Return all collections of DSpace in array.
- GET /collections/{collectionId} - Return collection with id.
- GET /collections/{collectionId}/items - Return all items of collection.
- POST /collections/{collectionId}/items - Create posted item in collection. You must post an Item
- POST /collections/find-collection - Find collection by passed name.
- PUT /collections/{collectionId} - Update collection. You must put Collection.
- DELETE /collections/{collectionId} - Delete collection from DSpace.
- DELETE /collections/{collectionId}/items/{itemId} - Delete item in collection.
...