Integration, testing, documentation and further development of DSpace REST services for 1.x and 2.0 versions. - Bojan Suzic |
This page is not completed. The work on specifications is ongoing. Everyone is welcome to comment or contribute! |
Project Title: |
DSpace REST API |
Student: |
Bojan Suzic, University of Technology Graz |
Mentors: |
Aaron Zeckoski, Mark Diggory |
Contacting author: |
bojan AT student . tugraz DOT at - using subject line DSpace |
SCM Location for Project: |
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:
This project is continuation of last year's activities, supported by Google as part of GSoC 2009. In the first stage the basic support for REST for DSpace is provided, exposing many parts of DSpace functionality to the clients.
In this year's GSoC the following activities should be primarily addressed:
In the following sections main activities are elaborated in detail.
Changes in comparison to existing support are marked with red color. Please note that changes may appear as:
DSpace 1.x and 2.x are treating the resources on different way. 2.x is more generalized, suggesting the use of RDF-like interrelation notations. The necessity to follow this approach for 1.x is to be discussed in the list or on the following page. |
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. |
- |
|
|
By default contains item count, identifier, handle and name and other referencing data, or 204 if none. Additionaly, based on parameter |
|
200, 400, 500 |
|
|
|
Return information about |
- |
- |
- |
TBD |
|
200, 204, 400, 500 |
• |
|
|
Change description of |
|
- |
- |
TBD |
|
200, 204, 500, 501 |
• |
|
|
Add community to the system |
|
|
- |
TBD |
|
200, 201, 204, 500, 501 |
|
|
|
Return a list of all parent communities of the |
- |
idOnly=false |
|
Contains item count, identifiers, handle and name or 204 if id is already top-level. Additionaly, based on parameter idOnly=true the method returns only identifiers. |
|
200, 204, 400, 500 |
|
|
|
Returns a list of immediate sub-communities (children) of the |
- |
idOnly=false |
|
Contains item count, identifiers, handle and name or 204 if none. Additionaly, based on parameter |
|
200, 204, 400, 500 |
|
|
|
Return a list of collections in the |
- |
idOnly=false |
|
Contains item count, identifiers, name, archival status, last modification and handle of collections, or 204 if there are none of them. Additionaly with idOnly=true only identifiers are returned. |
|
200, 204, 400, 500 |
|
|
|
Return a list of recent submissions to a community. |
- |
idOnly=false |
|
Contains complete items from recent submissions in community. |
|
200, 204, 400, 500 |
|
|
|
Return a list of all collections in the system. |
- |
idOnly=false |
|
Contains item count, identifiers, name and handle of collections, or 204 if |
|
200, 204, 400, 500 |
|
|
|
Return a list of all communities a collection with |
- |
idOnly=false |
|
Contains item count, identifier, name and handle of collections, or 204 if |
|
200, 204, 400, 500 |
|
|
|
Returns a list of all items from the collection |
- |
idOnly=false |
|
Contains full information info including name, submitter, collections related or 204 if there are none of them. In the case idOnly=true is used, return only identifiers of results. |
|
200, 204, 400, 500 |
Parameter |
Description |
---|---|
|
returns only top level communities |
|
if true return only the identifiers for the record |
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. |
- |
TBD 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 |
C |
Verb |
URL |
Description |
Mandatory parameters |
Optional parameters |
Sorting fields |
Response Data |
Formats |
Response codes |
---|---|---|---|---|---|---|---|---|---|
|
|
|
Return detailed information about an item. |
|
- |
|
Contains an information about an item including resource name, metadata, owning collection, collections stored in, communities stored in, bundle ids, last modified date, archival/withdrawn status and submitter of an item. |
|
200, 204, 400, 500 |
|
|
|
Return status of user permissions on this item. |
|
- |
|
Boolean variable, stating can user edit the listed item . |
|
200, 400, 500 |
|
|
|
Return communities this item is part of. |
- |
- |
|
Communities listed. |
|
200, 400, 500 |
|
|
|
Return collections this item is part of. |
- |
- |
|
Collections listed. |
|
200, 400, 500 |
|
|
|
Returns bitstream object - usually the library item file. |
|
- |
- |
Includes all information about referenced bitstream, including file name, licence, corresponding ittem etc. It is possible only to get information for particular bitstreams. When the request is made without parameters/references, the blank list is presented (there is no list of all bitstreams in the system available). |
|
200, 400, 401, 403, 404, 500 |
|
|
|
Returns checksum of bitstream. |
|
- |
- |
Checksum of bitstream. |
|
200, 400, 401, 403, 404, 500 |
Name and description |
Value and notes |
---|---|
Base URI: |
/users?query= |
Description: |
Returns list containing id, name and email of persons (optionally matching a query) |
HTTP method: |
|
Optional parameters: |
|
Sorting fields supported: |
|
Response formats: |
|
Status codes |
200: OK |
Response details |
List with information on particular user. Additionaly only identifiers are sent if idOnly is true. |
Name and description |
Value and notes |
---|---|
Base URI: |
|
Description: |
Returns general statistics |
HTTP method: |
|
Response formats: |
|
Status codes |
200: OK |
Response details |
Returns cummulative list of statistics data for the system currently available |
Here the visitors and stakeholders can insert their suggestions or describe the needs for their applications in detail.
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.
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:
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).