DSpace REST API - Bojan Suzic

Integration, testing, documentation and further development of DSpace REST services for 1.x and 2.0 versions. - Bojan Suzic

Not completed!

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

Naming convention for endpoints
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`	By default contains item count, identifier, handle and name and other referencing data, or 204 if none. Additionaly, based on parameter `idOnly=true` the method returns only identifiers.	`json` `xml`	200, 400, 500
•	`GET`	`/communities/{id`}	Return information about `id` community.	-	-	-	Contains information about community, including id, handle, name, collections, ancestors, subcommunities, administrators, metadata	`json` `xml`	200, 204, 400, 500
•	`GET`	`/communities/{id}/relations`	Return entities according to relation and parameters specified	`property`	`rtype` `rfield`	-	Contains entities selected and sorted in conformance to request parameters	`json` `xml`	200, 204, 400, 500
•	`GET`	`/communities/{id}/ancestors`	Return a list of all ancestor communities of the `id` community.	-	`idOnly=false` `immediateOnly=true`	`id` `name` `countitems`	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.	`json` `xml`	200, 204, 400, 500
•	`GET`	`/communities/{id}/children`	Returns a list of immediate sub-communities (children) of the `id` community.	-	`idOnly=false`	`id` `name` `countitems`	Contains item count, identifiers, handle and name or 204 if none. Additionaly, based on parameter `idOnly=true` the method returns only identifiers.	`json` `xml`	200, 204, 400, 500
•	`GET`	`/communities/{id}/collections`	Return a list of collections in the `id` community.	-	`idOnly=false`	`id` `name` `countitems`	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.	`json` `xml`	200, 204, 400, 500
•	`GET`	`/communities/{id}/recent`	Return a list of recent submissions to a community.	-	`idOnly=false`	`id` `name` `lastmodified` `submitterId` `submitterName`	Contains complete items from recent submissions in community. Additionaly, contains only identifiers when `idOnly=true` is used.	`json` `xml`	200, 204, 400, 500
•	`GET`	`/communities/{id}/logo`	Return a community logo	-	-	-	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	-	`idOnly=false`	`id` `name` `countitems`	Contains id, name, handle, members, member groups of submitters, licence, metadata, templateitem	`json` `xml`	200, 204, 400, 500
	`GET`	`/collections/{id}/ancestors`	Return a list of all ancestor communities a collection with `id` belongs to.	-	`idOnly=false` `immediateOnly=true`	`id\` `name` `countitems`	Contains item count, identifier, name and handle of collections, or 204 if there are none of them. Additionaly, when idOnly=true is used, return only identifiers. Contains item count, identifier, name and handle of collections, or 204 if there are none of them. Additionaly, when idOnly=true is used, return only identifiers.	`json` `xml`	200, 204, 400, 500
•	`GET`	`/collections/{id}/logo`	Return a collection logo	-	-	-	Contains collection logo (bitstream)	`binary`	200, 400

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 - contain only entity id and name in response |
Note: incomplete/orientative properties, for more info check Vocabularies.

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 |

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 |

Repository manipulation

|| C || Verb || URL || Description || Mandatory parameters || Optional parameters || Response Data || Formats || Response codes |

•	`PUT`	/communities/{id}	Change description of `id` community	name	-	TBD	`json` `xml`	200, 204, 400, 500
•	`POST`	`/communities`	Add community to the system	name	`logo` `parent` other metadata	TBD	`json` `xml`	200, 204, 400, 500

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

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`	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.	`json` `xml`	200, 204, 400, 500
`GET`	`/items/{id}/permissions`	Return status of user permissions on this item.	`id`	-	`id` `name` `lastmodified` `submitter`	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` `name` `countitems`	Communities listed.	`json` `xml`	200, 400, 500
`GET`	`/items/{id}/collections`	Return collections this item is part of.	-	-	`id` `name` `countitems`	Collections listed.	`json` `xml`	200, 400, 500
`GET`	`/bitstream/{id`}	Returns bitstream object - usually the library item file.	`id`	-	-	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).	`json` `xml`	200, 400, 401, 403, 404, 500
`GET`	`/bitstream/{id}/receive`	Returns checksum of bitstream.	`id`-	-	-	Checksum of bitstream.	`json` `xml`	200, 400, 401, 403, 404, 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

Items ingestion

Administrative tasks

Workflow related tasks

Visitors' suggestions or wishes

Here the visitors and stakeholders can insert their suggestions or describe the needs for their applications in detail.

REST API Methods - NEW

Endpoints redefined

Based on semantic mapping relationships the following is proposed for DSpace REST endpoints. The same would apply for 1.x and 2.x branches.

More info: DSpace SandBox

Repository browsing

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`	By default contains item count, identifier, handle and name and other referencing data, or 204 if none. Additionaly, based on parameter `idOnly=true` the method returns only identifiers. Order of communities is ???	`json` `xml`	200, 400, 500
	`GET`	`/communities/{id`}	Return information about `id` community.	-	-	-	TBD	`json` `xml`	200, 204, 400, 500
•	`PUT`	`/communities/{id`}	Change description of `id` community	`name`	-	-	TBD	`json` `xml`	200, 204, 500, 501
•	`POST`	`/communities`	Add community to the system	`name`	`logo` `parent` other metadata	-	TBD	`json` `xml`	200, 201, 204, 500, 501
	`GET`	`/communities/{id}/ds:isPartOfCommunity`	Return a list of all ancestor communities of the `id` community.	-	idOnly=false immediateOnly=true	`id` `name` `countitems`	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. Order of ancestors is ??? immediate first or most distant first?	`json` `xml`	200, 204, 400, 500
	`GET`	`/communities/{id}/ds:hasCommunity`	Returns a list of immediate sub-communities (children) of the `id` community.	-	idOnly=false	`id` `name` `countitems`	Contains item count, identifiers, handle and name or 204 if none. Additionaly, based on parameter `idOnly=true` the method returns only identifiers. Order of children is ???	`json` `xml`	200, 204, 400, 500
	`GET`	`/communities/{id}/ds:hasCollection`	Return a list of collections in the `id` community.	-	idOnly=false	`id` `name` `countitems`	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.	`json` `xml`	200, 204, 400, 500
	`GET`	`/collections`	Return a list of all collections in the system.	-	idOnly=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}/ds:isPartOfCommunity`	Return a list of all ancestor communities a collection with `id` belongs to.	-	idOnly=false immediateOnly=true	`id` `name` `countitems`	Contains item count, identifier, name and handle of collections, or 204 if there are none of them. Additionaly, when idOnly=true is used, return only identifiers.	`json` `xml`	200, 204, 400, 500
	`GET`	`/collections/{id}/ds:hasItem`	Returns a list of all items from the collection `id`.	-	idOnly=false in_archive=false	`id` `name` `lastmodified` `submitter`	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.	`json` `xml`	200, 204, 400, 500

C	Verb	URL	Description	Mandatory parameters	Optional parameters	Sorting fields	Response Data	Formats	Response codes
	`GET`	`/communities/{id}/recent`	Return a list of recent submissions to a community.	-	idOnly=false	`id` `name` `lastmodified` `submitter`	Contains complete items from recent submissions in community. Additionaly, contains only identifiers when `idOnly=true` is used.	`json` `xml`	200, 204, 400, 500

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).

Parameter	Description
`topLevelOnly`	returns only top level communities
`idOnly`	if true return only the identifiers for the record

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).

Page tree

GSOC10 - DSpace REST API

DSpace REST API - Bojan Suzic

Details

Project description

Detailed activities

REST API Methods

Repository browsing

Mandatory parameters

Optional parameters

Sorting fields:

Controlling results

Repository manipulation

Content searching

Item status and retrieval

User oriented functions

Statistical info

Items ingestion

Administrative tasks

Workflow related tasks

Visitors' suggestions or wishes

REST API Methods - NEW

Repository browsing

Integration in the system

Documentation tasks

Example of usage