DSpace REST API - Bojan Suzic
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! |
Details
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: |
http://scm.dspace.org/svn/repo/modules/rest |
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 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:
- integration of existing code in the system
- alignment of REST API with currently available DSpace features/functionality, e.g. adding of new features
- extending of existing code, in order to provide better handling of management and injection functions
- providing more detailed documentation and examples for end users
- testing activities, e.g. cooperation/coordination with other GSoC 10 project Unit testing
- promotion of DSpace REST interaction (by taking part in integration with other systems)
Detailed activities
In the following sections main activities are elaborated in detail.
REST API Methods
Changes in comparison to existing support are marked with red color. Please note that changes may appear as:
- introduction of new method
- extending of existing method, by implementing new functionality (e.g. GET/PUT/DELETE)
- extending of existing method, by changing its parameters, output etc
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. |
Repository browsing
Earlier Implementation Description - GSoC09
C |
Verb |
URL |
Description |
Mandatory parameters |
Optional parameters |
Sorting fields |
Response Data |
Formats |
Response codes |
|
GET |
/communities |
Returns a list of all communities on the system or return just top level communities. |
- |
topLevelOnly=true idOnly=false |
id name countitems |
countitems - number of items under community
handle - handle of the community (unique persistent resource identifier)
id - entity identifier, internal to the system
name - entity name
type - entity type (object type in the system)
collections - collections contained in the community, ordered by id
ancestors - ancestors of the community, ordered by id
children - subcommunities, ordered by id
admins - group administrators, ordered by id
metadata - community metadata
administrators - default group of administrators
Response code details:
204 - if there are no communities on the system |
json xml |
200, 204, 400, 500 |
• |
GET |
/communities/{id } |
Return information about id community. |
id |
idOnly=false |
- |
countitems - number of items under community
handle - handle of the community (unique persistent resource identifier)
id - entity identifier, internal to the system
name - entity name
type - entity type (object type in the system)
collections - collections contained in the community, ordered by id
ancestors - ancestors of the community, ordered by id
children - subcommunities, ordered by id
admins - group administrators, ordered by id
metadata - community metadata
administrators - default group of administrators |
json xml |
200, 400, 404, 500 |
• |
GET |
/communities/{id}/ ancestors |
Return a list of all ancestor communities of the id community. |
id |
idOnly=false
immediateOnly=true |
id name countitems |
countitems - number of items under community
handle - handle of the community (unique persistent resource identifier)
id - entity identifier, internal to the system
name - entity name
type - entity type (object type in the system)
collections - collections contained in the community, ordered by id
ancestors - ancestors of the community, ordered by id
children - subcommunities, ordered by id
admins - group administrators, ordered by id
metadata - community metadata |
json xml |
200, 204, 400, 500 |
• |
GET |
/communities/{id}/children |
Returns a list of immediate sub-communities (children) of the id community. |
id |
idOnly=false |
id name countitems |
countitems - number of items under community
handle - handle of the community (unique persistent resource identifier)
id - entity identifier, internal to the system
name - entity name
type - entity type (object type in the system)
collections - collections contained in the community, ordered by id
ancestors - ancestors of the community, ordered by id
children - subcommunities, ordered by id
admins - group administrators, ordered by id
metadata - community metadata
administrators - default group of administrators |
json xml |
200, 204, 400, 500 |
• |
GET |
/communities/{id}/collections |
Return a list of collections in the id community. |
id |
idOnly=false |
id
name
countitems |
countitems - number of items under collection
handle - handle of the collection
id - entity identifier, internal to the system
name - entity name
type - entity type (object type in the system)
items - items contained in the collection, ordered by id
communities - owners of the collection, ordered by id
admins - group administrators, ordered by id
licence - collection licence
templateItem - template item
Response code details:
204 - if there are no collections |
json xml |
200, 204, 400, 500 |
• |
GET |
/communities/{id}/recent |
Return a list of recent submissions to a community. |
id |
idOnly=false |
id name lastmodified submitterId
submitterName |
id - entity (item) identifier, internal to the system
handle - handle of the item
isArchived - archival status of the item
isWithdrawn - withdrawal status of the item
lastModified - timestamp of last modification
metadata - item metadata
name - item name
submitter - submiter entity
type - entity type (object type in the system, item in this case)
bitstreams - bitstreams related to the item
bundles - bundles related to the item
collections - collections related item appear in
communities - communities related item appear in
Response details:
204 - if there are no recently submitted items |
json xml |
200, 204, 400, 500 |
• |
GET |
/communities/{id}/logo |
Return a community logo |
id |
- |
- |
Contains community logo (bitstream) |
binary |
200, 400 |
• |
GET |
/collections |
Return a list of all collections in the system. |
- |
idOnly=false
isAuthorized=false |
id
name
countitems |
Contains item count, identifiers, name and handle of collections, or 204 if
there are none of them. In the case idOnly=true is used, returns only
identifiers of collections. |
json
xml |
200, 204, 400, 500 |
• |
GET |
/collections/{id } |
Return information about id collection |
id |
idOnly=false |
id
name
countitems |
countitems - number of items under collection
items - items present in the collection
id - entity (collection) identifier, internal to the system
handle - handle of the collection
licence - collection licence
name - collection name
type - entity type (object type in the system, item in this case)
communities - communities related collection appear in
submiters - default group of submitters, if there is one
administrators - default group of administrators, if there is one
templateitem - template item for collection, if there is one |
json xml |
200, 204, 400, 500 |
• |
GET |
/collections/{id}/ancestors |
Return a list of all ancestor communities a collection with id belongs to. |
id |
idOnly=false
immediateOnly=true |
id
name
countitems |
countitems - number of items under community
handle - handle of the community (unique persistent resource identifier)
id - entity identifier, internal to the system
name - entity name
type - entity type (object type in the system)
collections - collections contained in the community, ordered by id
ancestors - ancestors of the community, ordered by id
children - subcommunities, ordered by id
admins - group administrators, ordered by id
metadata - community metadata
administrators - default group of administrators |
json
xml |
200, 204, 400, 500 |
• |
GET |
/collections/{id}/items |
Returns a list of all items from the collection id . |
id |
idOnly=false
inArchive=false |
id
name
lastmodified
submitterId
submitterName |
id - entity (item) identifier, internal to the system
handle - handle of the item
isArchived - archival status of the item
isWithdrawn - withdrawal status of the item
lastModified - timestamp of last modification
metadata - item metadata
name - item name
submitter - submiter entity
type - entity type (object type in the system, item in this case)
bitstreams - bitstreams related to the item
bundles - bundles related to the item
collections - collections related item appear in
communities - communities related item appear in
Response details:
204 - if there are no items |
json
xml |
200, 204, 400, 500 |
• |
GET |
/collections/{id}/logo |
Return a collection logo |
id |
- |
- |
Contains collection logo (bitstream) |
binary |
200, 400 |
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 |
Sorting fields:
Parameter |
Description |
Ordering supported |
id |
sort results by entity id |
asc | ascending
desc | descending |
name |
sort results by entity name |
asc | ascending
desc | descending |
countitems |
sort results by number of items contained |
asc | ascending
desc | descending |
lastmodified |
sort results by date of last item modification |
asc | ascending
desc | descending |
submitterName |
sort results by submitter name |
asc | ascending
desc | descending |
submitterId |
sort results by submitter id |
asc | ascending
desc | descending |
Controlling results
Parameter |
Description |
Default |
Example |
_start |
position of the first entity to return |
0 (first) |
_start=5 to list 6th item and onwards |
_page |
page of data to display |
0 (first) |
_page=2 , to display second page with query results |
_perpage |
number of results to show on each page |
0 (all) |
_perpage=10 to display 10 results per page |
_limit |
maximum number of entities to return |
0 (all) |
_limit=50 |
_sort |
|
the sort order to return entities in
should be comma separated list of field names
suffix determines ordering
suffixes: _asc , _ascending , _desc , _descending
ascending default |
sort=name
_sort=name,email_desc,lastname_desc |
Response codes
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 |
Repository manipulation
C |
Verb |
URL |
Description |
Mandatory parameters |
Optional parameters |
Response Data |
Formats |
Response codes |
• |
PUT |
/communities/{id } |
Change description of id community |
id |
name
metadata
logo |
Response code |
json xml |
200, 400, 401, 403, 500 |
• |
POST |
/communities |
Add community to the system |
name |
logo parent other metadata |
Id of newly created community |
json xml |
200, 400, 401, 403, 500 |
• |
DELETE |
/communities/{id } |
Delete community from the system |
id |
- |
Response code |
json
xml |
200, 400, 401, 403, 500 |
• |
DELETE |
/communities/{id}/administrators |
Remove the administrators group from the community |
id |
- |
Response code |
json
xml |
|
• |
DELETE |
/communities/{id}/collections/{cid } |
Remove collection cid from community id |
id
|
cid |
Response code |
|
|
• |
DELETE |
/communities/{id}/children/{cid } |
Remove subcommunity cid from community id |
id |
cid |
Response code |
|
|
• |
POST |
/communities/{id}/administrators |
Create a default administrators group if one does not already exists |
id |
- |
Id of newly created group |
|
|
• |
POST |
/communities/{id}/collections |
Create a new collection within community id |
id |
- |
Id of newly created collection |
|
|
• |
PUT |
/communities/{id}/collections/{cid } |
Add an existing collection cid to community id |
id
cid |
-- |
Response code |
|
|
• |
POST |
/communities/{id}/children |
Create a new subcommunity within community id |
id |
- |
Id of newly created subcommunity |
|
|
• |
PUT |
/communities/{id}/children/{cid } |
Add an existing community cid as a subcommunity of community id |
id
cid |
- |
Response code |
|
|
|
PUT |
/communities/{id}/metadata |
Set metadata value |
id |
metadataField
metadataValue |
Response code |
|
|
• |
PUT |
/collections/{id } |
Change description of id collection |
id |
|
Response code |
json
xml |
200, 400, 401, 403, 500 |
• |
POST |
/collections |
Add collection to the system |
name
communityId |
|
Id of newly created collection |
json
xml |
200, 400, 401, 403, 500 |
• |
DELETE |
/collections/{id } |
Delete collection from the system |
- |
- |
Response code |
json
xml |
200, 400, 401, 403, 500 |
|
DELETE |
/collections/{id}/items/{cid } |
Delete item cid from collection id |
id |
cid |
Response code |
json
xml |
|
|
PUT |
/collections/{id}/logo |
Set the logo for collection id |
id |
|
Response code |
|
|
|
POST |
/collections/{id}/administrators |
Create a default administrators group if one does not already exists |
id |
- |
Response code |
|
|
|
DELETE |
/collections/{id}/administrators |
Remove the administrators group from the collection |
id |
- |
Response code |
|
|
|
PUT |
/collections/{id}/submitters |
Create a default submitters group if one does not already exists |
id |
- |
Response code |
|
|
|
DELETE |
/collections/{id}/submitters |
Remove the submitters group |
id |
- |
Response code |
|
|
|
PUT |
/collections/{id}/templateitem |
Create an empty template item for this collection |
id |
- |
Response code |
|
|
|
DELETE |
/collections/{id}/templateitem |
Remove the template item from the collection |
id |
- |
Response code |
|
|
|
POST |
/collections/{id}/items |
Add an item to the collection |
id |
itemId |
Response code |
|
|
|
PUT |
/collections/{id}/metadata |
Set metadata value |
id |
metadataField
metadataValue |
Response code |
|
|
|
PUT |
/collections/{\id}/licence |
Set collection licence |
id |
licence |
Response code |
|
|
|
|
|
|
|
|
|
|
|
Content searching
C |
Verb |
URL |
Description |
Mandatory parameters |
Optional parameters |
Sorting fields |
Response Data |
Formats |
Response codes |
|
GET |
/search |
Return a list of all objects found by searching criteria.
Notice: community and collection are mutually exclusive options. |
- |
TBD modifiers{{query=query }}&(community=id or
collection={{id }}
idOnly=false |
id name lastmodified submitter |
Item info with basic metadata for the search results. Additionally return only
identifiers when idOnly=true is used. |
json xml |
200, 204, 400, 500 |
|
GET |
/harvest |
Return a list of all objects that have been created, modified or withdrawn within specified time range. |
- |
startdate
{enddate}} community collection idOnly=false withdrawn=false
Notice: community and collection are mutually exclusive options |
- |
Contains item info including id, name, handle, metadata, bitstreams according to
the defined requirements. Additionally when idOnly=true only identifiers of
results are returned. If the date is in incompatible format, error 400 is returned. |
json xml |
200, 204, 400, 500 |
Item status and retrieval
C |
Verb |
URL |
Description |
Mandatory parameters |
Optional parameters |
Sorting fields |
Response Data |
Formats |
Response codes |
|
GET |
/items/{id } |
Return detailed information about an item. |
id |
- |
id name lastmodified submitter |
id - entity (item) identifier, internal to the system
handle - handle of the item
isArchived - archival status of the item
isWithdrawn - withdrawal status of the item
lastModified - timestamp of last modification
metadata - item metadata
name - item name
submitter - submiter entity
type - entity type (object type in the system, item in this case)
bitstreams - bitstreams related to the item
bundles - bundles related to the item
collections - collections related item appear in
owningCollection - get the owning collection of the item
communities - communities related item appear in |
json xml |
200, 204, 400, 500 |
|
GET |
/items/{id}/permissions |
Return status of user permissions on this item. |
id |
- |
- |
Boolean variable, stating can user edit the listed item. |
json xml |
200, 400, 500 |
|
GET |
/items/{id}/communities |
Return communities this item is part of. |
id |
idOnly=false |
id name countitems |
countitems - number of items under community
handle - handle of the community (unique persistent resource identifier)
id - entity identifier, internal to the system
name - entity name
type - entity type (object type in the system)
collections - collections contained in the community, ordered by id
ancestors - ancestors of the community, ordered by id
children - subcommunities, ordered by id
admins - group administrators, ordered by id
metadata - community metadata
administrators - default group of administrators |
json xml |
200, 400, 500 |
|
GET |
/items/{id}/collections |
Return collections this item is part of. |
id |
idOnly=false |
id name countitems |
countitems - number of items under collection
items - items present in the collection
id - entity (collection) identifier, internal to the system
handle - handle of the collection
licence - collection licence
name - collection name
type - entity type (object type in the system, item in this case)
communities - communities related collection appear in
submiters - default group of submitters, if there is one
administrators - default group of administrators, if there is one
templateitem - template item for collection, if there is one |
json xml |
200, 400, 500 |
|
GET |
/bitstream/{id } |
Return bitstream object - usually the library item file. |
id |
- |
- |
id - id of bitstream
name - name of the bitstream
bundles - bundles the related bitstream appears in
checksum - checksum of bitstream
checksumAlgorithm - checksum algorithm used
description - bitstream description
formatDescription - format description of bitstream
handle - bitstream handle
mimeType - mime type of bitstream
sequenceId - sequence id
size - bitstream size in bytes
source - bitstream source, local
storeNumber - store number
type - object type
userFormatDescription - description of user format |
json xml |
200, 400, 401, 403, 404, 500 |
|
GET |
/bitstream/{id}/receive |
Return bitstream |
id |
- |
- |
Return bitstream |
binary |
200, 400, 401, 403, 404, 500 |
Item manipulation
C |
Verb |
URL |
Description |
Mandatory parameters |
Optional parameters |
Response Data |
Formats |
Response codes |
• |
POST |
/items/{id}/action |
Change parameters of item id |
id |
addBundle addMetadata
createBundle createSingleBitstream removeBundle removeLicenses setArchived setOwningCollection setSubmitter withdraw |
Response code |
json xml |
200, 400, 401, 403, 500 |
|
PUT |
/items/{id}/bundle/{{bid }} |
Add an existing bundle bid to item id |
id
bid |
|
|
|
|
|
DELETE |
/items/{id}/bundle/{{bid }} |
Remove bundle bid from item id |
id
bid |
|
|
|
|
|
PUT |
/items/{id}/metadata |
Add a single metadata field |
id
element
value
schema
qualifier
lang
|
|
|
|
|
|
DELETE |
/items/{id}metadata |
Remove a single metadata field |
schema
element
qualifier
lang |
|
|
|
|
|
DELETE |
/items/{id}/metadata |
|
|
|
|
|
|
• |
POST |
/communities |
Add community to the system |
name |
logo parent other metadata |
Id of newly created community |
json xml |
200, 400, 401, 403, 500 |
• |
DELETE |
/communities/{id}{ } |
Delete community from the system |
id |
- |
Response code |
json xml |
200, 400, 401, 403, 500 |
• |
PUT |
/collections/{id}{ } |
Change description of id collection |
id |
|
Response code |
json xml |
200, 400, 401, 403, 500 |
• |
POST |
/collections |
Add collection to the system |
name communityId |
|
Id of newly created collection |
json xml |
200, 400, 401, 403, 500 |
• |
DELETE |
/collections/{id}{ } |
Delete collection from the system |
- |
- |
Response code |
json xml |
200, 400, 401, 403, 500
|
User oriented functions
C |
Verb |
URL |
Description |
Mandatory parameters |
Optional parameters |
Sorting fields |
Response Data |
Formats |
Response codes |
|
GET |
/users |
Return a list containing id, name and email of persons. |
- |
query idOnly=false |
id name lastname fullname language |
List with information on particular user. Additionaly only identifiers are sent if idOnly is true. |
json xml |
200, 204, 400, 500 |
Statistical info
C |
Verb |
URL |
Description |
Mandatory parameters |
Optional parameters |
Sorting fields |
Response Data |
Formats |
Response codes |
|
GET |
/stats |
Return general statistics. |
- |
- |
- |
Cummulative list of statistics data for the system currently available. |
json xml |
200, 400, 500 |
Administrative tasks
Workflow related tasks
Relationships interface
C |
Verb |
URL |
Description |
Mandatory parameters |
Optional parameters |
Sorting fields |
Response Data |
Formats |
Response codes |
• |
GET |
/communities/{id}/relations |
Return entities according to relation and parameters specified |
id
property |
rtype
rfield |
- |
ontains entities selected and sorted in conformance to request parameters. For more details see description of rtype andrfield . |
json
xml |
200, 204, 400, 401, 403, 500 |
Mandatory parameters
Parameter |
Description |
Values |
Example |
property |
Return entities satisfying requested property relation |
Structural properties
ds:isPartOfSite
ds:isPartOfCommunity
ds:isPartOfCollection
ds:isPartOfItem
ds:isPartOfBundle
ds:hasCommunity
ds:hasCollection
ds:hasItem
ds:hasBundle
ds:hasBitstream
ds:hasBitstreamFormat
Communities and collections
ds:logo
Bistream format
ds:support
ds:fileExtension
ds:mimeType
Bitstream
ds:messageDigest
ds:messageDigestAlgorithm
ds:messageDigestOriginator
ds:size
Eperson
ds:language |
property=ds:hasCommunity - return subcommunities of a community
property=ds:isPartOfCommunity - return communities current community is part of (children)
property=ds:hasCollection - return collections belonging to community
property=ds:hasItem - return Items belonging to community |
rtype |
restriction on type - only entity with specifed type(s) would be returned |
ds:Bitstream
ds:Bundle
ds:Collection
ds:Community
ds:EPerson
ds:Group
ds:Item
ds:DSpaceObject
ds:Policy
ds:Site
ds:BitstreamFormat | |
rtype=ds:Collection - return entities of Collection type |
rfield |
restriction on fields - return only selected fields; by default all fields are returned |
id
name
countitems
metadata
subcommunities
ancestors
owner
other (depending on object type, will be documented later) |
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].
Visitors' suggestions or wishes
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).
Integration in the system
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).