Integration, testing, documentation and further development of DSpace REST services for 1.x and 2.0 versions. - Bojan Suzic |
Aligning with the current status of the project! Takes 1-2 days to refresh |
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. |
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 information about |
|
|
- |
Fields describing community. |
|
|
• |
|
|
Return a particular data field found in the community |
|
Respective field info |
|
|||
• |
|
|
Return a community logo |
|
- |
- |
Contains community logo (bitstream) |
|
|
• |
|
|
Return a list of all collections in the system. |
- |
The list of the collections containing respective fields. |
|
|||
• |
|
|
Return information about |
|
Fields of the collection entity. |
|
|||
• |
|
|
Return a particular data field found in the collection |
|
Respective field info |
|
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.
Parameter |
Description |
---|---|
|
returns only top level communities |
|
if true return only the identifiers for the record |
|
return only direct parent community |
|
return only collections user has permission to work on |
|
return archived items for respective collection |
Parameter |
Description |
Ordering supported |
---|---|---|
|
sort results by entity id |
|
|
sort results by entity name |
|
|
sort results by number of items contained |
|
|
sort results by date of last item modification |
|
|
sort results by submitter name |
|
|
sort results by submitter id |
|
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 |
|
Code |
Description |
---|---|
200 |
OK |
201 |
Created |
204 |
No content |
400 |
Bad request |
401 |
Unauthorized |
403 |
Forbidden |
404 |
Not found |
405 |
Method not allowed |
500 |
Internal server error |
503 |
Service unavailable |
Currently only standard authentication is supported. The authentication data is provided in the request or header body.
Example:
/rest/communities.json?user=user@email.com&pass=userpassword
The same elements user
and pass
are used for header based authentication.
Authorization is done on underlying api level; in the case of error the proper message and error code are returned to the user.
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 |
id |
- |
Response code |
|
200, 400, 401, 403, 500 |
• |
|
|
Delete collection from the system |
- |
- |
Response code |
|
200, 400, 401, 403, 500 |
|
|
|
Remove attribute/value |
|
|
Response code |
|
|
|
|
|
Set the logo for collection |
|
|
Response code |
binary |
|
|
|
|
|
|
|
|
|
|
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. |
|
- |
|
|
|
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. |
|
idOnly=false |
|
|
|
200, 400, 500 |
|
|
|
Return collections this item is part of. |
|
idOnly=false |
|
|
|
200, 400, 500 |
|
|
|
Return bitstream object - usually the library item file. |
|
- |
- |
|
|
200, 400, 401, 403, 404, 500 |
|
|
|
Return bitstream |
|
- |
- |
Return bitstream |
|
200, 400, 401, 403, 404, 500 |
C |
Verb |
URL |
Description |
Mandatory parameters |
Optional parameters |
Response Data |
Formats |
Response codes |
|
---|---|---|---|---|---|---|---|---|---|
• |
|
|
Change parameters of item |
|
|
Response code |
|
200, 400, 401, 403, 500 |
|
|
|
|
Change parameters of an item |
- |
|
|
|
|
|
|
|
|
Add an existing bundle |
|
|
|
|
|
|
|
|
|
Remove bundle |
|
|
|
|
|
|
|
|
|
Set archival status of an item |
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
Add a single metadata field |
|
|
|
|
|
|
|
|
|
Remove a single metadata field |
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
• |
|
|
Add community to the system |
|
|
|
|
200, 400, 401, 403, 500 |
|
• |
|
|
Delete community from the system |
|
- |
Response code |
|
200, 400, 401, 403, 500 |
|
• |
|
|
Change description of |
|
|
Response code |
|
200, 400, 401, 403, 500 |
|
• |
|
|
Add collection to the system |
|
|
|
|
200, 400, 401, 403, 500 |
|
• |
|
|
Delete collection from the system |
- |
- |
Response code |
|
200, 400, 401, 403, 500 |
C |
Verb |
URL |
Description |
Mandatory parameters |
Optional parameters |
Sorting fields |
Response Data |
Formats |
Response codes |
---|---|---|---|---|---|---|---|---|---|
|
|
|
Return a list containing id, name and email of persons. |
- |
|
|
List with information on particular user. Additionaly only identifiers are sent if idOnly is true. |
|
200, 204, 400, 500 |
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 |
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 |
|
Parameter |
Description |
Values |
Example |
---|---|---|---|
|
Return entities satisfying requested property relation |
Structural properties |
|
|
restriction on type - only entity with specifed type(s) would be returned |
|
|
rfield |
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).
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).