DSpace REST API
...
Warning |
---|
This |
...
Panel | ||||||||
---|---|---|---|---|---|---|---|---|
|
Details
Project Title: | DSpace REST API |
Author: | Bojan Suzic |
Mentors (at GSoC): | Aaron Zeckoski, Mark Diggory |
Contacting author: | bojan.suzic AT gmail _DOT _com - using subject line DSpace REST |
SCM Location for Project: |
Project description
...
page is outdated, and refers to documentation for the 2011 Google Summer of Code prototype REST API project. This GSoC project is not developed anymore and it has spawned successors and alternatives. You can learn more about current REST API efforts here:
|
Excerpt |
---|
This is a wiki page for DSpace REST API addon. The project is in development phase, but can be tested by the users. For the details please check this page. |
Panel | ||||||||
---|---|---|---|---|---|---|---|---|
|
Details
Project Title: | DSpace REST API |
Author: | Bojan Suzic |
Mentors (at GSoC): | Aaron Zeckoski, Mark Diggory |
Contacting author: | bojan.suzic AT gmail _DOT _com - using subject line DSpace REST |
SCM Location for Project: | |
Alternative (improved) | https://github.com/wijiti/dspace-rest-api |
Project description
The REST approach promotes simplification and decoupling of software architecture, enabling further scalability, portability, granularity and simplified interaction of software systems and components.
The aim of this project is to provide DSpace with REST capable API and underlying component, which will enable developers and end-users to exploit the advantages of such approach.
Some of uses this module is intended to provide could be, for instance:
- interaction between DSpace systems and/or other repositories
- automation of different activities, e.g. submission of packages
- integrating repositories in process workflows of other applications or systems
- interaction with many kinds of systems or web applications, such as CMS, LMS, LCMS, VLS, AMS etc
- providing of other approaches to UI, such as client based/run UI
- crawling of repositories, exposing information in structural way
This project is continuation of GSoC 2009 and GSoC 2010 .
Some of uses this module is intended to provide could be, for instance:
- interaction between DSpace systems and/or other repositories
- automation of different activities, e.g. submission of packages
- integrating repositories in process workflows of other applications or systems
- interaction with many kinds of systems or web applications, such as CMS, LMS, LCMS, VLS, AMS etc
- providing of other approaches to UI, such as client based/run UI
- crawling of repositories, exposing information in structural way
This project is continuation of GSoC 2009 and GSoC 2010 . In the first stage the basic support for REST for DSpace is provided, exposing many parts of DSpace functionality to the clients. Currently the module is being tested and improved in preparation for upcomign DSpace release.
Based on REST API for DSpace the new GSoC (2011) project is started. Vibhaj Rajan DSpace UI Client based on JavaScript and appropriate framework (JQuery). More inforormationinformation: Client UI REST API
Release plan and issues
It is expected to have working and tested code for Important:During Q1-Q3 of 2012 thanks to Hayden Young and other contributors from Wijiti Pty Ltd a great effort has been invested to continue the development of REST API for DSpace. They reworked the code base, refreshed the project to be compatible with newest DSpace 1.8 release. According to relevant discussions on DSpace developer meetings, there is possibility to have this code released asynchronously of DSpace, as independent module. After initial release the code will be actively maintained.
Currently (mid October 2010) there are several issues opened, of them I would notice the following:
.1 version, fixed the bugs and provided the integration of DSpace, REST API and Joomla CMS. There are also other numerous improvements introduced. Their contribution can be reached via GitHub, including development site and documentation update.
Based on this update, the integration with Joomla CMS is provieded as a part of the Saber Project, which has been implemented and demonstrated at Monash University.
Release plan and issues
It is expected to have working and tested code for DSpace 1.8 release. According to relevant discussions on DSpace developer meetings, there is possibility to have this code released asynchronously of DSpace, as independent module. After initial release the code will be actively maintained.
Currently (mid October 2010) there are several issues opened, of them I would notice the following:
- Performance issues during browsing bigger datasets. This is generally related to DSpace API. I have Performance issues during browsing bigger datasets. This is generally related to DSpace API. I have reported this problem and proposed solution at http://jira.dspace.org/jira/browse/DS-659. However as I am not sure whether it will be accepted and included in the upcoming release I will change the code and translate some functions used from DSpace API to DSpace REST API. This way some handling will be done directly at REST API level. Consequently some additional features related to sorting/ordering will be available.
- Multiple loops in listing Collections and some other entities. This issue is resolved as of end September. Additionally, option to fine-grain details level of the output is implemented (three levels).
- HTTP Basic Auth - this is easily to implement and will be done shortly
- Some Authorization related issues: the authorization handling is done on the level of DSpace API. However some functions translated to REST API are not directly available to users and thus do not provide Authorization mechanisms. In order to prevent misuse etc. this gap should be filled at REST API level.
- Not finished end-points. Working on them.
- Testing. Testing. I also need cooperation of you potential users. I need repository for testing containing at least several hundreds of items. If you can provide me with that please contact me via email.
- DSpace 1.5 and older versions support - planned to be implemented at the end of initial public release.
...
In the following section listed are supported endpoints on the application level. The items marked with dot (in C column) are in phase of implementation, while other items are considered already working.
Please note that additional tests should be made in order to ensure proper stability of the whole application.
...
Earlier Implementation Description - GSoC09
C | Verb | URL | Description | Mandatory parameters | Optional parameters | Sorting fields | Response Data | Formats | Response codes | ||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
|
|
| Returns a list of all communities on the system or return just top level communities. | - | The list of communities containing respective fields . |
| |||||||||
|
|
| Return detailed information about |
|
| - | Fields describing community. |
| |||||||
|
|
| Return a particular data field found in the community
element ): id - entity identifier, internal to the system name - entity name countItems - number of items under community handle - handle of the community (unique persistent resource identifier) type - entity type (object type in the system) collections - collections contained in the community, ordered by id canedit - states user persmission on the community (editing) anchestor - anchestors of the community children - subcommunities, ordered by id administrators - group administrators, ordered by id recent - recent items in the community shortDescription - short description copyrightText - copyright text sidebarText - sidebar text introductoryText - introductory text logo - community logo; to retrieve use returned id with /bistream/receive endpoint |
| Respective field info |
| |||||||||
|
|
| Return a list of all collections in the system. | - | The list of the collections containing respective fields. |
| |||||||||
|
|
| Return detailed information about |
| Fields of the collection entity. |
| |||||||||
|
|
| Return a particular data field found in the collection
element ): id - entity identifier, internal to the system name - collection name licence - collection licence items - items contained in collection handle - handle of the collection (unique persistent resource identifier) canedit - states user permission on the collection (edit) communities - communities collection is a part of countItems - number of the items in the collection type - entity type (object type in the system) shortDescription - short description of the collection introText - introductory text for the collection copyrightText - copyright text for the collection sidebarText - sidebar text for the collection provenance - provenance logo - information about collection's logo (to retrieve use logo id in /bitstream/receive endpoint) |
|
| Respective field info |
| ||||||||
|
|
| Return a list of the items in the system | - | - | The list of the items containing related fields . |
|
| |||||||
|
|
| Return detailed information about an item. |
|
| Fields of the item entity. |
| 200, 204, 400, 500 | |||||||
|
|
| Return a particular data field fould in the item
element ): metadata - item metadata submitter - submitter group isArchived - archival status of the item isWithdrawn - states if the item is withdrawn owningCollection - owning collection of the item lastModified - last modified time collections - collections the item appears in communities - communities the item appears is name - name of the item bitstreams - bitstreams related to the item handle - item handle (unique identified) canedit - states can user edit the item id - item id type - element type bundles - bundles related to the item |
| - | Respective field info |
| 200, 204, 400, 500 | |||||||
|
|
| Return bitstream object - usually the library item file. |
| - | - | Fields of the bitstream entity. |
| 200, 400, 401, 403, 404, 500 | ||||||
|
|
| Return a particular data field found in bitstream
Supported fields (for element ): mimeType - mime type of file bundles - bundles the bitstream is a part of checkSum - checksum of the file checkSumAlgorithm - checksum algorithm used description - bitstream description formatDescription - file format description sequenceId - sequence id of the file size - size of the file source - source (typically filename with path information) storeNumber - asset store number where the bitstream is stored userFormatDescription - user's format description name - bitstream name handle - unique id of the bitstream id - internal id of the bitstream type - type of the entity (referring to bitstream) Note: bitstream can be not only the content of the item (like book pdf file etc), but also licence file or logo of community |
| - | Respective field info |
| 200, 400, 401, 403, 404, 500 | |||||||
|
|
| Return bitstream |
| - | - | Return bitstream |
| 200, 400, 401, 403, 404, 500 | ||||||
|
|
| Return a list of the groups in the system | - | - | The list of the groups containing related fields . |
| 200, 204, 400, 500 | |||||||
|
|
| Return a group object |
| - | Fields of the group entity. |
| 200, 204, 400, 500 | |||||||
|
|
| Return a particular data field found in the group entity
Supported fields (for element ): handle - unique id (external) id - internal id of the gruop isEmpty - is the group empty members - group members (as users) memberGroups - group members (as groups) name - group name type - entity type (referring to group) |
| - | Respective field info |
| 200, 204, 400, 500 | |||||||
|
|
| Return a list of the users in the system | - | - | The list of the users containing related fields . |
| 200,204,400,500 | |||||||
|
|
| Return a user info |
| - | Fields of the user entity. |
| 200,204,400,500 | |||||||
|
|
| Return a particular data field found in the user
Supported fields (for element ): email - user's email firstName - first name fullName - full name handle - handle (unique, external) id - internal id of the user language - preferred language lastName - last name name - name netId - network id requireCertificate - requires certificate to login selfRegistered - is user self registered type - type of the object |
| - | Respective field info |
| 200,204,400,500 |
Note: modifier idOnly
is referred only to first layer of the results. For all other layers (e.g. nested results) only ids are returned in some cases, due to possible loops. Example: for community containing collections, on second level the response contains only ids for some elements where multiple loops may be created (community->has_collection->has_community....). Other data is modified according to idOnly
flag.
Optional parameters
Parameter | Description | ||||||
---|---|---|---|---|---|---|---|
topLevelOnly | returns only top level communities | ||||||
idOnly | if true return only the identifiers for the record | ||||||
immediateOnly | return only direct parent community | ||||||
isAuthorized | return only collections user has permission to work on | ||||||
inArchive | return archived items for respective collection | ||||||
detail | parameters: |
Sorting fields:
Info | ||
---|---|---|
| ||
The sorting of the fields / output results is currently partially supported. This part of the application is implemented independently of the endpoints and will be worked on after the most of endpoints are completed. |
Parameter | Description | Ordering supported | ||||||
---|---|---|---|---|---|---|---|---|
id | sort results by entity id |
| ||||||
name | sort results by entity name |
| ||||||
countitems | sort results by number of items contained |
| ||||||
lastmodified | sort results by date of last item modification |
| ||||||
submitterName | sort results by submitter name |
| ||||||
submitterId | sort results by submitter id |
|
Controlling results
Parameter | Description | Default | Example |
---|---|---|---|
| position of the first entity to return | 0 (first) |
|
| page of data to display | 0 (first) |
|
| number of results to show on each page | 0 (all) |
|
| maximum number of entities to return | 0 (all) |
|
|
| the sort order to return entities in |
|
...
Authorization is done on underlying api level; in the case of error the proper message and error code are returned to the user.
Repository manipulation
C | Verb | URL | Description | Mandatory parameters | Optional parameters | Response Data | Formats | Response codes |
---|---|---|---|---|---|---|---|---|
|
|
| Action to be done under community |
| - |
|
| 200, 400, 401, 403, 500 |
|
| /communities/{id}/{element} | Update the field |
| - | Response code |
| 200, 400, 401, 403, 500 |
|
|
| Set the logo for community |
| - | Response code | binary | 200, 400, 401, 403, 500 |
|
|
| Delete community from the system |
| - | Response code | | 200, 400, 401, 403, 500 |
|
|
| Remove attribute/value |
| - | Response code |
|
|
|
|
| Action to be done under collection |
| - | Id ow newly created element |
| 200, 400, 401, 403, 500 |
|
|
| Update field |
| - | Response code |
| 200, 400, 401, 403, 500 |
|
|
| Delete collection from the system - CANNOT BE DONE DIRECTLY | - | - | Response code |
| 200, 400, 401, 403, 500 |
|
|
| Remove attribute/value |
|
| Response code |
| 200,400,401,403,500 |
• |
|
| Set the logo for collection |
|
| Response code | binary | 200,400,401,403,500 |
• |
|
| Action to be done under item |
|
| Id of newly created element |
| 200,400,401,403,500 |
• |
|
| Update field |
| - | Response code |
| 200,400,401,403,500 |
• |
|
| Delete item from the system |
| - | Response code |
| 200,400,401,403,500 |
• |
|
| Delete element/attribute |
| - | Response code |
| 200,400,401,403,500 |
Content searching
C | Verb | URL | Description | Mandatory parameters | Optional parameters | Sorting fields | Response Data | Formats | Response codes |
---|---|---|---|---|---|---|---|---|---|
|
|
| Return a list of all objects found by searching criteria. | - | modifiers{{query= |
| Item info with basic metadata for the search results. Additionally return only |
| 200, 204, 400, 500 |
|
|
| Return a list of all objects that have been created, modified or withdrawn within specified time range. | - |
| - | Contains item info including id, name, handle, metadata, bitstreams according to |
| 200, 204, 400, 500 |
Statistical info
C | Verb | URL | Description | Mandatory parameters | Optional parameters | Sorting fields | Response Data | Formats | Response codes |
---|---|---|---|---|---|---|---|---|---|
|
|
| Return general statistics. | - | - | - | Cummulative list of statistics data for the system currently available. |
| 200, 400, 500 |
...
Info | ||
---|---|---|
| ||
This is considered as a experimental feature in the phase of being considered for compability with future versions of DSpace. Consider not important section; the status of the feature for upcoming release yet to be determined. |
C | Verb | URL | Description | Mandatory parameters | Optional parameters | Sorting fields | Response Data | Formats | Response codes |
---|---|---|---|---|---|---|---|---|---|
• | GET | /resource/{handle}/relations | Return entities according to relation and parameters specified |
|
| - | ontains entities selected and sorted in conformance to request parameters. For more details see description of |
|
Mandatory parameters
Parameter | Description | Values | Example | ||||||
---|---|---|---|---|---|---|---|---|---|
property | Return entities satisfying requested property relation | Structural properties |
| ||||||
rtype | restriction on type - only entity with specifed type(s) would be returned |
|
| ||||||
| restriction on fields - return only selected fields; by default all fields are returned | id | rfield=id,name - return only entity id and name in response |
Note: incomplete/orientative properties, for more info check [Vocabularies|http://code.google.com/p/dspace-sandbox/source/browse/#svn/modules/dspace-rdf/tags/dspace-rdf-1.5.1/src/main/java/org/dspace/adapters/rdf/vocabularies].
...
Here the visitors and stakeholders can insert their suggestions or describe the needs for their applications in detail.
Comment: In this case it is not clear how to treat recent
part of endpoint. If we stick to semantic mapping, then it should look like /resource/id/mapping
, but recent
in this case obviously do not represent a mapping, but the property.
Comment #2: Semantic mapping presented in this case should be probably hardcoded for 1.x branch, but on abstraction level which enables easy replacement with some auto-discovery method prepared for 2.x and eventually backported to 1.x. This way we would be able to call something similar to /communities/id
or communities/id/capabilities
in order to get supported mappings (amongst other data).
Suggesting new options:
Instead of changing wiki contents visitors can enter their suggestions as a comments.
...
It is planned to consult two external subjects for cooperation and the assistance during integration process (LMS and national library internal automation process). More information coming soon - awaiting approval of other parties.
Documentation tasks
Although provided software module exposes basic documentation automatically to the end user, in order to make it easier for other developers and users the documentation in the following forms is additionaly to be provided:
- Confluence pages, current location
- integrated documentation in PDF form (manual)
- short slides containing technology overview, advocacy/facts, configuration and usage guideliens and examples
- code will be additionally commented
Example of usage
At the end of the current stage of this project as a bonus task (if time constraints allow) the examples of usage will be provided for several languages, the use-cases will be presented (example of integration in other software, e.g. LMS) and optionally simple client system demonstrating UI customization will be demonstrated (e.g. Flex or JavaFX like).
...
Panel | |||
---|---|---|---|
Update: Current version includes this update (thanks Peter!). This explanation will be shortly removed. Note: The code for the REST API from the Google Summer of Code 2010 may be out of date with the latest version of dspace. It may help to import the latest stable version of DSpace through the REST-API pom.
|
For both approaches you should have Apache Maven installed. Then proceed using Subversion and check out the code from http://scm.dspace.org/svn/repo/modules/dspace-rest/trunk
1) This way assumes you are running DSpace under Tomcat. Locate src/main/webapp/WEB-INF/web.xml
(under directory you just downloaded DSpace REST API). Find variable named dspace-config
and alter it to point to current location of dspace.cfg
file of your DSpace instance. Navigate to the root directory of the REST API and type mvn package
. If everything goes well, in target
directory will be packaged dspace-rest-[version].war
. Deploy this file (changing the name to rest.war) to your current Tomcat webapp directory. The application will be available under http://localhost:8080/rest/ by default.
2) You can run REST API under Jetty container. Proceed with the same steps as under #1. Then instead to deploy .war file to Tomcat web server, from the root of REST API source tree issue command mvn jetty:run-war
. This will run REST support under Jetty and the web point will be available at http://localhost:8080/dspace-rest/ by default.
(Option 3) Install as a DSpace Module
If you have an existing instance of DSpace that you are developing, you can connect the rest api module to your existing code base by adding it as a module.
Modify [dspace-source]/dspace/pom.xml by adding the path to the checked out rest code.
Code Block |
---|
--- a/dspace/pom.xml +++ b/dspace/pom.xml @@ -505,6 +505,7 @@ --> <modules>< <module>modules</dependency> module> +<!-- |
For both approaches you should have Apache Maven installed. Then proceed using Subversion and check out the code from http://scm.dspace.org/svn/repo/modules/rest/branches/dspace-rest-gsoc10/
1) This way assumes you are running DSpace under Tomcat. Locate src/main/webapp/WEB-INF/web.xml
(under directory you just downloaded DSpace REST API). Find variable named dspace-config
and alter it to point to current location of dspace.cfg
file of your DSpace instance. Position into the root directory of the REST API and type maven package
. If everything goes well, in target
directory will be packaged dspace.war
. Use this file and deploy it to your current Tomcat instance. The application will be available under http://localhost:8080/rest/ by default.
<module>../../../dspace-rest-gsoc10</module>
</modules>
<build>
|
Once you rebuild your dspace-src code with mvn package and ant update, you will additionally need to copy the compiled .war file produced in the dspace-rest-gsoc10 target directory to tomcat's webapps directory.
Code Block |
---|
cp /path/to/dspace-rest-gsoc10/target/dspace.war /var/lib/tomcat6/webapps/rest.war
|
Afterwards you can restart tomcat and visit the rest api in action at: 2) You can run REST API under Jetty container. Proceed with the same steps as under #1. Then instead to deploy .war file to Tomcat web server, from the root of REST API source tree issue command mvn jetty:run-war
. This will run REST support under Jetty and the web point will be available at http://localhost:8080/dspace-rest/ by default.
(Option
...
3a) Install as a DSpace Module
...
in a source code installation
Its unlikely you will want to do this unless you are a committer or just nosey like me and like to play around with the code.
1) Create a new directory for the REST module source code - dspace-src/dspace-rest.
2) Checkout the source code from http://scm.dspace.org/svn/repo/modules/dspace-rest/trunk/ into the new directory.
3) Incorporate the new module into your project by adding a new <module> element for dspace-rest to the 'all' profile in dspace-src/pom.xml.
4) Tell Maven to use your new local module by adding a new <profile> to dspace-src/dspace/pom.xml. If you don't do this the project will build okay but won't be using your local source code for that module.
5) Create a new directory dspace-src/dspace/modules/rest.
5a) Add a sub-directory src/main/webapp and a pom.xml to the directory created in 5. (Copy the pom from any other modules/xxxx module).
6) Add a <profile> to dspace-src/dspace/modules/pom.xml.
7) Rebuild your project.
If you have an existing instance of DSpace that you are developing, you can connect the rest api module to your existing code base by adding it as a module.
Wiki Markup |
---|
Modify \[dspace-source\]/dspace/pom.xml by adding the path to the checked out rest code. |
Code Block |
---|
--- a/dspace/pom.xml
+++ b/dspace/pom.xml
@@ -505,6 +505,7 @@
-->
<modules>
<module>modules</module>
+ <module>../../../dspace-rest-gsoc10</module>
</modules>
<build>
|
Once you rebuild your dspace-src code with mvn package and ant update, you will additionally need to copy the compiled .war file produced in the dspace-rest-gsoc10 target directory to tomcat's webapps directory.
Code Block |
---|
cp /path/to/dspace-rest-gsoc10/target/dspace.war /var/lib/tomcat6/webapps/rest.war
|
Afterwards you can restart tomcat and visit the rest api in action at: http://localhost:8080/rest
Possible problems:
- If you have troubles trouble starting the application, try to check check the dspace-config
variable and make sure it to point to location dspace.cfg
using absolute addressing (take a look at commented line in configuration file) points to the location of the dspace.cfg
file. Use absolute addressing (see comment in src/main/webapp/WEB-INF/web.xml).
- If you receive HTTP 500 errors with a SQL exception indication *and* you are using Oracle, make sure you have ojdbc14.jar in your CLASSPATH when you start tomcat or jetty.
- If you are already run some other running another application on port 8080 try instead to start Jetty container with the following line: mvn jetty:run-war -Djetty.port=9090
for port 9090.
Please take a note that note this is still an experimental module so there may be bugs/errors in processing. You use Use it at your own risk.
I would highly appreciate user input. If you have comments or feature requests or anything else you can post it on this wiki in comments section. Additionally for the bugs/errors/issues found you can use JIRA at httpat https://jira.dspaceduraspace.org/browse/jiraDS/browse/GSOC?report=select to component/10190 to report or contact me directly via emalemail (bojan.suzic AT gmail _DOT _com - using subject line DSpace REST).
Information for developers
...