Page History

Versions Compared

Key

This line was added.
This line was removed.
Formatting was changed.

Comment: Migrated to Confluence 4.0

...

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.

...

Sorting fields:

Info

title	Not completed!

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

Anchor

	sort_id
	sort_id

id

sort results by entity id

asc | ascending
desc | descending

Anchor

	sort_name
	sort_name

name

sort results by entity name

asc | ascending
desc | descending

Anchor

	sort_countitems
	sort_countitems

countitems

sort results by number of items contained

asc | ascending
desc | descending

Anchor

	sort_lastmodified
	sort_lastmodified

lastmodified

sort results by date of last item modification

asc | ascending
desc | descending

Anchor

	sort_submittername
	sort_submittername

submitterName

sort results by submitter name

asc | ascending
desc | descending

Anchor

	sort_submitterid
	sort_submitterid

submitterId

sort results by submitter id

asc | ascending
desc | descending

...

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
	`POST`	`/communities`	Action to be done under community `id`, adding new content or values. Supported actions: `createAdministrators` `createCollection` `createSubcommunity`	`id, action` - `name` `name`	-	`Id` of newly created entity, depending on the action selected: id of group of administrators id of collection id of subcommunity	`json` `xml`	200, 400, 401, 403, 500
	`PUT`	/communities/{id}/{element}	Update the field `element` of the community `id`. Supported fields: `name` - change name `shortDescription` - change short description `copyrightText` - change copyright text `sidebarText` - change sidebar text `introductoryText` - change introductory text `collections` - add existing collection `children` - add existing subcommunity	`id` `value` `value` `value` `value` `value` `cid` `cid`	-	Response code		200, 400, 401, 403, 500
	`PUT`	`/communities/{id}/logo`	Set the logo for community `id`	`id`	-	Response code	binary	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}/{element}/{eid`}	Remove attribute/value `eid` of element `element` from the community `id`. Suported elements: `collections` `children` `administrators`	`id, eid` `cid` `cid` -	-	Response code	`json` `xml`
	`POST`	`/collections`	Action to be done under collection `id`, adding new content or values. Supported actions: `createAdministrators` `createSubmitters` `createTemplateItem` `createWorkflowGroup`	`id, action` - - - `step`	-	Id ow newly created element	`json` `xml`	200, 400, 401, 403, 500
	`PUT`	`/collections/{id}/{element`}	Update field `element` of the collection `id`. Supported elements: `shortDescription` - short description `introText` - introductory text `copyrightText` - copyright text `sidebarText` - sidebar text `provenance` - provenance `licence` - collection licence `name` - collection name	`id` `value` `value` `value` `value` `value` `value` `value`	-	Response code	`json` `xml`	200, 400, 401, 403, 500
	`DELETE`	`/collections/{id`}	Delete collection from the system - CANNOT BE DONE DIRECTLY	-	-	Response code	`json` `xml`	200, 400, 401, 403, 500
	`DELETE`	`/collections/{id}/{element}/{cid`}	Remove attribute/value `cid` from collection `id` Supported attributes: `administrators` `item` `submitters` `templateItem`	`id, cid`	`-`	Response code	`json` `xml`	200,400,401,403,500
•	`PUT`	`/collections/{id}/logo`	Set the logo for collection `id`	`id`		Response code	binary	200,400,401,403,500
•	`POST`	`/items`	Action to be done under item `id`, adding content or value. Supported actions: `createBundle` `createBitstream`	`id`, `action` `name` `name`, `input`		Id of newly created element	`json`,`xml`, `binary`	200,400,401,403,500
•	`PUT`	`/items/{id}/{element`}	Update field `element` of the item `id` Supported fields: `isArchived` `isWithdrawn` `owningCollection` `submitter`	`id`,`element`	-	Response code	`json`,`xml`	200,400,401,403,500
•	`DELETE`	`/items/{id`}	Delete item from the system	`id`	-	Response code	`json`,`xml`	200,400,401,403,500
•	`DELETE`	`/items/{id}/{element}/{eid`}	Delete element/attribute `eid` from the item `id` Supported fields for `element`: `bundle` `licences`	`id`,`element`,`eid`	-	Response code	`json`,`xml`	200,400,401,403,500

...

Info

title	Experimental feature

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	`handle` `property`	`rtype` rfield	-	ontains entities selected and sorted in conformance to request parameters. For more details see description of `rtype` and`rfield`.	`json` `xml`	200, 204, 400, 401, 403, 500

Mandatory parameters

Parameter

Description

Values

Example

Anchor

	property
	property

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

Anchor

	rtype
	rtype

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

Anchor

	rfield
	rfield

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

...

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.

...

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

...

-To do so, modify \modify [dspace-rest-api-source\]/pom.xml-

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.

Wiki Markup

Code Block

Index: pom.xml
===================================================================
--- pom.xml	(revision 6356)
+++ pom.xml	(working copy)
@@ -18,7 +18,7 @@
     <parent>
         <artifactId>dspace-parent</artifactId>
         <groupId>org.dspace</groupId>
-        <version>1.6.0-SNAPSHOT</version><!--dspace2.version-->
+        <version>1.7.1</version><!--dspace2.version-->
     </parent>

     <repositories>
@@ -100,7 +100,7 @@
             <groupId>org.dspace</groupId>
             <artifactId>dspace-api</artifactId>
             <scope>compile</scope>
-            <version>1.6.2-SNAPSHOT</version>
+            <version>1.7.1</version>
         </dependency>

         <dependency>
@@ -121,7 +121,7 @@
             <groupId>org.dspace</groupId>
             <artifactId>dspace-jspui-api</artifactId>
             <scope>compile</scope>
-            <version>1.6.2-SNAPSHOT</version>
+            <version>1.7.1</version>
             <exclusions>
                 <exclusion>
                     <groupId>org.dspace</groupId>
@@ -133,7 +133,7 @@
             <groupId>org.dspace</groupId>
             <artifactId>dspace-api-lang</artifactId>
             <scope>compile</scope>
-            <version>1.5.2.2-SNAPSHOT</version>
+            <version>1.7.1.0</version>
         </dependency>

         <!--

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

Wiki Markup1) 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 [ to your current Tomcat webapp directory. The application will be available under http://localhost:8080/rest/|http://localhost:8080/rest/] by 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.

...

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 MarkupModify \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>

...

6) Add a <profile> to dspace-src/dspace/modules/pom.xml.

7) Rebuild your project.

Possible problems:

- If you have trouble starting the application, check the dspace-config variable and make sure it points to the location of the dspace.cfg file. Use absolute addressing (see comment in src/main/webapp/WEB-INF/web.xml).

...

- If you are already 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.

...