Suzic

\\
{excerpt}Integration, testing, documentation and further development of DSpace REST services for 1.x and 2.0 versions. - Bojan

 Suzic{excerpt}\\
{info:title=Not completed!}This page is not completed. The work on specifications is ongoing. Everyone is welcome to comment or contribute\!
{info}\\
{panel}
{toc:style=none|separator=newline|outline=true}
{panel}\\


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

] |
\\

h3. 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|http://wiki.dspace.org/confluence/display/DSPACE/Google+Summer+of+Code+2009+DSpace+REST+Webapp]. 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|http://fedora-commons.org/confluence/display/DSPACE/GSOC10+-+Add+Unit+Testing+to+Dspace]
* promotion of DSpace REST interaction (by taking part in integration with other systems)


h1. Detailed activities

\\
In the following sections main activities are elaborated in detail.

h3. 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
\\
{note:title=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.
{note}\\


h4. Repository browsing

[Earlier Implementation Description - GSoC09|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}}|#toplevelonly]\\  {{[idOnly=false|#idonly]}} | {{[id|#sort_id]}}  \\  [name|#sort_name] \\  {{[countitems|#sort_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|#rcodes] |
| • | {{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|#rcodes] |
| • | {{GET}} | {{/communities/\{id\}/}}{color:#000000}{{{}ancestors{}}}{color} | Return a list of all ancestor communities of the {{id}} community. | {{id}} | {{[idOnly=false|#idonly]}}   \\
{{[immediateOnly=true|#immediateonly]}} | {{[id|#sort_id]}} \\  {{[name|#sort_name]}} \\  {{[countitems|#sort_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|#rcodes] |
| • | {{GET}} | {{/communities/\{id\}/children}} | Returns a list of immediate sub-communities (children) of the {{id}} community. | {{id}} | {{[idOnly=false|#idonly]}} | {{[id|#sort_id]}} \\  {{[name|#sort_name]}} \\  {{[countitems|#sort_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|#rcodes] |
| • | {{GET}} | {{/communities/\{id\}/collections}} | Return a list of collections in the {{id}} community. | {{id}} | {{[idOnly=false|#idonly]}} | [id|#sort_id]\\
{{[name|#sort_name]}} \\
{{[countitems|#sort_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|#rcodes] |
| • | {{GET}} | {{/communities/\{id\}/recent}} | Return a list of recent submissions to a community. | {{id}} | {{[idOnly=false|#idonly]}} | {{[id|#sort_id]}} \\  {{[name|#sort_name]}} \\  {{[lastmodified|#sort_lastmodified]}} \\  {{[submitterId|#sort_submitterid]}} \\
{{[submitterName|#sort_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|#rcodes] |
| • | {{GET}} | {{/communities/\{id\}/logo}} | Return a community logo | {{id}} | \- | \- | Contains community logo (bitstream) | {{binary}} | [200, 400|#rcodes] |
| • | {{GET}} | {{/collections}} | Return a list of all collections in the system. | \- | {{[idOnly=false|#idonly]}} \\
{{[isAuthorized=false|#isauthorized]}} | {{[id|#sort_id]}}{{ }} \\
{{[name|#sort_name]}}{{ }} \\
{{[countitems|#sort_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|#rcodes] |
| • | {{GET}} | {{/collections/\{id\}}} | Return information about {{id}} collection | {{id}} | {{[idOnly=false|#idonly]}} | {{[id|#sort_id]}} \\
{{[name|#sort_name]}} \\
{{[countitems|#sort_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|#rcodes] |
| • | {{GET}} | {{/collections/\{id\}/ancestors}} \\ | Return a list of all ancestor communities a collection with {{id}} belongs to. \\ | {{id}} | {{[idOnly=false|#idonly]}} \\
{{[immediateOnly=true|#immediateonly]}} \\ | {{[id|#sort_id]}}  \\
{{[name|#sort_name]}} \\
{{[countitems|#sort_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|#rcodes] |
| • | {{GET}} | {{/collections/\{id\}/items}} \\ | Returns a list of all items from the collection {{id}}. \\ | {{id}} | {{[idOnly=false|#idonly]}} \\
{{[inArchive=false|#inarchive]}} \\ | {{[id|#sort_id]}} \\
{{[name|#sort_name]}} \\
{{[lastmodified|#sort_lastmodified]}} \\
{{[submitterId|#sort_submitterid]}} \\
{{[submitterName|#sort_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|#rcodes] \\ |
| • | {{GET}} | {{/collections/\{id\}/logo}} | Return a collection logo | {{id}} | \- | \- | Contains collection logo (bitstream) | {{binary}} | [200, 400|#rcodes] |


*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

.




\\

h5. Optional parameters\\


|| Parameter || Description ||
| {anchor:toplevelonly}{{{}topLevelOnly}} | returns only top level communities |
| {anchor:idonly} {{idOnly}} | if true return only the identifiers for the record |
| {anchor:immediateonly} {{immediateOnly}} | return only direct parent community |
| {anchor:isauthorized}{{{}isAuthorized}} | return only collections user has permission to work on |
| {anchor:inarchive}{{{}inArchive}} | return archived items for respective collection |
\\
\\

h5. Sorting fields:\\


|| Parameter || Description || Ordering supported ||
| {anchor:sort_id} {{id}} | sort results by entity id | {{asc}} \| {{ascending}} \\
{{desc}} \| {{descending}} |
| {anchor:sort_name} {{name}} | sort results by entity name | {{asc}} \| {{ascending}}  \\
{{desc}} \| {{descending}} \\ |
| {anchor:sort_countitems}{{{}countitems}} | sort results by number of items contained | {{asc}} \| {{ascending}}  \\
{{desc}} \| {{descending}} \\ |
| {anchor:sort_lastmodified}{color:#000000}{{{}lastmodified{}}}{color} | sort results by date of last item modification | {{asc}} \| {{ascending}}  \\
{{desc}} \| {{descending}} \\ |
| {anchor:sort_submittername}{{{}submitterName}} | sort results by submitter name | {{asc}} \| {{ascending}}  \\
{{desc}} \| {{descending}} \\ |
| {anchor:sort_submitterid}{{{}submitterId}} | sort results by submitter id | {{asc}} \| {{ascending}}  \\
{{desc}} \| {{descending}} \\ |
\\

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

}} |

\\
{anchor:rcodes}

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

h4. Repository manipulation


|| C || {color:#003366}Verb{color} || {color:#003366}URL{color} || {color:#003366}Description{color} || {color:#003366}Mandatory parameters{color} || {color:#003366}Optional parameters{color} || {color:#003366}Response Data{color} || {color:#003366}Formats{color} || {color:#003366}Response codes{color} ||
| {color:#000000}•{color} | {color:#000000}{{{}PUT{}}}{color} | {{/communities/\{id\}}} | {color:#000000}Change description of {color}{color:#000000}{{{}id{}}}{color}{color:#000000} community{color}\\ | {{id}} | {{name}} \\
{{metadata}} \\
{{logo}} | {color:#000000}Response code{color} | {color:#000000}{{{}json{}}}{color}{color:#000000} {color}\\  {color:#000000}{{{}xml{}}}{color} | {color:#000000}200, 400, 401, 403, 500{color} |
| {color:#000000}•{color} | {color:#000000}{{{}POST{}}}{color} | {color:#000000}{{/communities{}}}{color} | {color:#000000}Add community to the system{color}\\ | {color:#000000}{{{}name{}}}{color} | {color:#000000}{{{}logo{}}}{color}{color:#000000} {color}\\  {color:#000000}{{{}parent{}}}{color}{color:#000000} {color}\\  {color:#000000}other metadata{color}\\ | {color:#000000}{{{}Id{}}}{color} {color:#000000}of newly created community{color} | {color:#000000}{{{}json{}}}{color}{color:#000000} {color}\\  {color:#000000}{{{}xml{}}}{color} | {color:#000000}200, 400, 401, 403, 500{color} |
| • \\ | {{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 | | |
| | | | | | | | | |


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



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


h4. Item manipulation

|| {color:#003366}C{color} || {color:#003366}Verb{color} || {color:#003366}URL{color} || {color:#003366}Description{color} || {color:#003366}Mandatory parameters{color} || {color:#003366}Optional parameters{color} || {color:#003366}Response Data{color} || {color:#003366}Formats{color} || {color:#003366}Response codes{color} ||
| {color:#000000}•{color} | {color:#000000}{{{}POST{}}}{color} | {color:#000000}{{/items/\{id\}/action{}}}{color} | {color:#000000}Change parameters of item{color} {color:#000000}{{{}id{}}}{color}\\ | {color:#000000}{{{}id{}}}{color} | {{createBundle}} \\  {color:#000000}{{{}createSingleBitstream{}}}{color}\\
{color:#000000}{{{}removeLicenses{}}}{color}\\
{color:#000000}{{removeDspaceLicense}}{color}\\
{{licenseGranted}} | {color:#000000}Response code{color} | {color:#000000}{{{}json{}}}{color}{color:#000000} {color}\\  {color:#000000}{{{}xml{}}}{color} | {color:#000000}200, 400, 401, 403, 500{color} |
| | {{PUT}}\\ | {{/items/\{id\}}}\\ | Change parameters of item {id} | \- | {{isArchived}}\\
 {{isWithdrawn}}\\
 {{owningCollection}}\\
 {{submitter}}\\
 {{owningCollection}} | | | |
| | {{PUT}} | {{/items/\{id\}/bundles/}} | Add an existing bundle {{bid}} to item {{id}} | {{id}} \\
{{bid}} | | | | |
| | {{DELETE}} | {{/items/\{id\}/bundles/}} | Remove bundle {{bid}} from item {{id}} | {{id}} \\
{{bid}} | | | | |
| | | | Set archival status of an item {id} | | | | | |
| | | | | | | | | |
| | {{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}} | | | | | | |
| {color:#000000}•{color} | {color:#000000}{{{}POST{}}}{color} | {color:#000000}{{/communities{}}}{color} | {color:#000000}Add community to the system{color}\\ | {color:#000000}{{{}name{}}}{color} | {color:#000000}{{{}logo{}}}{color}{color:#000000} {color}\\  {color:#000000}{{{}parent{}}}{color}{color:#000000} {color}\\  {color:#000000}other metadata{color}\\ | {color:#000000}{{{}Id{}}}{color}{color:#000000} of newly created community{color} | {color:#000000}{{{}json{}}}{color}{color:#000000} {color}\\  {color:#000000}{{{}xml{}}}{color} | {color:#000000}200, 400, 401, 403, 500{color} |
| {color:#000000}• {color}\\ | {color:#000000}{{{}DELETE{}}}{color} | {color:#000000}{{/communities/\{id\}{}}}{color} | {color:#000000}Delete community from the system{color} | {color:#000000}{{{}id{}}}{color} | {color:#000000}\-{color} | {color:#000000}Response code{color} | {color:#000000}{color}{color:#000000}{{{}json{}}}{color}{color:#000000} {color}\\  {color:#000000}{{{}xml{}}}{color} | {color:#000000}200, 400, 401, 403, 500{color} |
| {color:#000000}• {color}\\ | {color:#000000}{{{}PUT{}}}{color} | {color:#000000}{{/collections/\{id\}{}}}{color} | {color:#000000}Change description of {color}{color:#000000}{{{}id{}}}{color}{color:#000000} collection{color} | {color:#000000}{{{}id{}}}{color} | {color:#000000} {color} | {color:#000000}Response code{color} | {color:#000000}{{{}json{}}}{color}{color:#000000} {color}\\  {color:#000000}{{{}xml{}}}{color} | {color:#000000}200, 400, 401, 403, 500{color} |
| {color:#000000}• {color}\\ | {color:#000000}{{{}POST{}}}{color} | {color:#000000}{{/collections{}}}{color} | {color:#000000}Add collection to the system{color} | {color:#000000}{{{}name{}}}{color}{color:#000000} {color}\\  {color:#000000}{{{}communityId{}}}{color} | {color:#000000} {color} | {color:#000000}{{{}Id{}}}{color}{color:#000000} of newly created collection{color} | {color:#000000}{{{}json{}}}{color}{color:#000000} {color}\\  {color:#000000}{{{}xml{}}}{color} | {color:#000000}200, 400, 401, 403, 500{color} |
| {color:#000000}• {color}\\ | {color:#000000}{{{}DELETE{}}}{color} | {color:#000000}{{/collections/\{id\}{}}}{color} | {color:#000000}Delete collection from the system{color} | {color:#000000}\-{color} | {color:#000000}\-{color} | {color:#000000}Response code{color} | {color:#000000}{{{}json{}}}{color}{color:#000000} {color}\\  {color:#000000}{{{}xml{}}}{color} | {color:#000000}200, 400, 401, 403, 500{color}\\
\\ |


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



\\

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


\\


\\

\\

h4. Administrative tasks

\\


\\

h4. Workflow related tasks

h4. Relationships interface

|| {color:#003366}C{color} || {color:#003366}Verb{color} || {color:#003366}URL{color} || {color:#003366}Description{color} || {color:#003366}Mandatory parameters{color} || {color:#003366}Optional parameters{color} || {color:#003366}Sorting fields{color} || {color:#003366}Response Data{color} || {color:#003366}Formats{color} || {color:#003366}Response codes{color} ||
| {color:#000000}•{color}\\ | {color:#000000}GET{color}\\ | {color:#000000}/resource/\{handle\}/relations{color}\\ | {color:#000000}Return entities according to relation and parameters specified{color}\\ | {color:#000000}{{{}handle{}}}{color}{color:#000000} {color}\\
{color:#000000}{{[property|#property]}}{color} \\ | {color:#000000}{{[rtype|#rtype]}}{color} \\
rfield | {color:#000000}\-{color} | {color:#000000}ontains entities selected and sorted in conformance to request parameters. For more details see description of {color}{color:#000000}{{{}rtype{}}}{color}{color:#000000} and{color}{color:#000000}{{{}rfield{}}}{color}{color:#000000}.{color}\\ | {color:#000000}{{{}json{}}}{color}{color:#000000} {color}\\
{color:#000000}{{{}xml{}}}{color}\\ | [200, 204, 400, 401, 403, 500|#rcodes] |


h5. *Mandatory parameters*

|| {color:#003366}Parameter{color} || {color:#003366}Description{color} || {color:#003366}Values{color} || {color:#003366}Example{color} ||
| {anchor:property}{color:#000000}{{{}property{}}}{color} | {color:#000000}Return entities satisfying requested property relation{color} | {color:#000000}Structural properties {color}\\
{color:#000000}{{{}ds:isPartOfSite{}}}{color}{color:#000000} {color}\\
{color:#000000}{{{}ds:isPartOfCommunity{}}}{color}{color:#000000} {color}\\
{color:#000000}{{{}ds:isPartOfCollection{}}}{color}{color:#000000} {color}\\
{color:#000000}{{{}ds:isPartOfItem{}}}{color}{color:#000000} {color}\\
{color:#000000}{{{}ds:isPartOfBundle{}}}{color}{color:#000000} {color}\\
{color:#000000}{{{}ds:hasCommunity{}}}{color}{color:#000000} {color}\\
{color:#000000}{{{}ds:hasCollection{}}}{color}{color:#000000} {color}\\
{color:#000000}{{{}ds:hasItem{}}}{color}{color:#000000} {color}\\
{color:#000000}{{{}ds:hasBundle{}}}{color}{color:#000000} {color}\\
{color:#000000}{{{}ds:hasBitstream{}}}{color}{color:#000000} {color}\\
{color:#000000}{{{}ds:hasBitstreamFormat{}}}{color}{color:#000000} {color}\\
\\
{color:#000000}Communities and collections {color}\\
{color:#000000}{{{}ds:logo{}}}{color}{color:#000000} {color}\\
\\
{color:#000000}Bistream format {color}\\
{color:#000000}{{{}ds:support{}}}{color}{color:#000000} {color}\\
{color:#000000}{{{}ds:fileExtension{}}}{color}{color:#000000} {color}\\
{color:#000000}{{{}ds:mimeType{}}}{color}{color:#000000} {color}\\
\\
{color:#000000}Bitstream {color}\\
{color:#000000}{{{}ds:messageDigest{}}}{color}{color:#000000} {color}\\
{color:#000000}{{{}ds:messageDigestAlgorithm{}}}{color}{color:#000000} {color}\\
{color:#000000}{{{}ds:messageDigestOriginator{}}}{color}{color:#000000} {color}\\
{color:#000000}{{{}ds:size{}}}{color}{color:#000000} {color}\\
\\
{color:#000000}Eperson {color}\\
{color:#000000}{{{}ds:language{}}}{color}{color:#000000} {color}\\ | {color:#000000}{{{}property=ds:hasCommunity{}}}{color}{color:#000000} \- return subcommunities of a community {color}\\
{color:#000000}{{{}property=ds:isPartOfCommunity{}}}{color}{color:#000000} \- return communities current community is part of (children) {color}\\
{color:#000000}{{{}property=ds:hasCollection{}}}{color}{color:#000000} \- return collections belonging to community {color}\\
{color:#000000}{{{}property=ds:hasItem{}}}{color}{color:#000000} \- return Items belonging to community{color} |
| {anchor:rtype}{color:#000000}{{{}rtype{}}}{color} | {color:#000000}restriction on type - only entity with specifed type(s) would be returned{color} | {color:#000000}{{{}ds:Bitstream{}}}{color}{color:#000000}  {color}\\
{color:#000000}{{{}ds:Bundle{}}}{color}{color:#000000}  {color}\\
{color:#000000}{{{}ds:Collection{}}}{color}{color:#000000}  {color}\\
{color:#000000}{{{}ds:Community{}}}{color}{color:#000000}  {color}\\
{color:#000000}{{{}ds:EPerson{}}}{color}{color:#000000}  {color}\\
{color:#000000}{{{}ds:Group{}}}{color}{color:#000000}  {color}\\
{color:#000000}{{{}ds:Item{}}}{color}{color:#000000}  {color}\\
{color:#000000}{{{}ds:DSpaceObject{}}}{color}{color:#000000}  {color}\\
{color:#000000}{{{}ds:Policy{}}}{color}{color:#000000}  {color}\\
{color:#000000}{{{}ds:Site{}}}{color}{color:#000000}  {color}\\
{color:#000000}{{{}ds:BitstreamFormat{}}}{color}{color:#000000}\|{color} | {color:#000000}{{{}rtype=ds:Collection{}}}{color}{color:#000000} \- return entities of Collection type{color} |
| {anchor: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 |
{color:#000000}Note: incomplete/orientative properties, for more info check {color}{color:#003366}\[{color}{color:#003366}Vocabularies{color}\|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\].

 





h4. Visitors' suggestions or wishes

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

{color:#ff0000}Comment:{color} {color:#000000}In this case it is not clear how to treat{color} {color:#000000}{{{}recent{}}}{color} {color:#000000}part of endpoint. If we stick to semantic mapping, then it should look like{color} {color:#000000}{{/resource/id/mapping

{}}}{color}{color:#000000}, but{color} {color:#000000}{{{}recent{}}}{color} {color:#000000}in this case obviously do not represent a mapping, but the property. {color}

 {color:#ff0000}Comment #2:{color} 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).

h3. *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.
\\

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

\\

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