Page History

...

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

The list of communities containing respective fields .

Response code details:
204 - if there are no communities on the system

json
xml

200, 204, 400, 500

•

GET

/communities/{id}

Return detailed information about id community.

id

idOnly=false

-

Fields describing community.

json
xml

200, 400, 404, 500

•

GET

/communities/{id}/{element}

Return a particular data field found in the community id

Anchor

	com_elements
	com_elements

Fields supported (for element):
id - entity identifier, internal to the system
name - entity name
countItems - number of items under community
handle - handle of the community (unique persistent resource identifier)
type - entity type (object type in the system)
collections - collections contained in the community, ordered by id
canedit - states user persmission on the community (editing)
anchestor - anchestors of the community
children - subcommunities, ordered by id
administrators - group administrators, ordered by id
recent - recent items in the community
shortDescription - short description
copyrightText - copyright text
sidebarText - sidebar text
introductoryText - introductory text

id

idOnly=false
immediateOnly=true

id
name
countitems

Respective field info

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

The list of the collections containing respective fields.

Response code details:
204 - if there are no communities on the system

json
xml

200, 204, 400, 500

•

GET

/collections/{id}

Return detailed information about id collection

id

idOnly=false

id
name
countitems

Fields of the collection entity.

json
xml

200, 204, 400, 500

•

GET

/collections/{id}/{element}

Return a particular data field found in the collection id.

Anchor

	col_elements
	col_elements

Fields supported (for element):
id - entity identifier, internal to the system
name - collection name
licence - collection licence
items - items contained in collection
handle - handle of the collection (unique persistent resource identifier)
canedit - states user permission on the collection (edit)
communities - communities collection is a part of
countItems - number of the items in the collection
type - entity type (object type in the system)
shortDescription - short description of the collection
introText - introductory text for the collection
copyrightText - copyright text for the collection
sidebarText - sidebar text for the collection
provenance - provenance

id

idOnly=false
immediateOnly=true

id
name
countitems

Respective field info

json
xml

200, 204, 400, 500

GET

/items

Return a list of the items in the system

-

The list of the items containing related fields .

Response code details:
204 - if there are no communities on the system

GET

/items/{id}

Return detailed information about an item.

id

-

id
name
lastmodified
submitter

- Fields of the item entity.

json
xml

200, 204, 400, 500

GET

/items/{id}/{element}

Return a particular data field fould in the item id

Anchor

	ite_elements
	ite_elements

Fields supported (for element):
metadata - item metadata
submitter - submitter group
isArchived - archival status of the item
isWithdrawn - states if the item is withdrawn
owningCollection - owning collection of the item
lastModified - last modified time
collections - collections the item appears in
communities - communities the item appears is
name - name of the item
bitstreams - bitstreams related to the item
handle - item handle (unique identified)
canedit - states can user edit the item
id - item id
type - element type
bundles - bundles related to the item

id, element

-

- -

Respective field info

json
xml

200, 204, 400, 500

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

...

returns only top level communities

...

if true return only the identifiers for the record

...

return only direct parent community

...

return only collections user has permission to work on

...

return archived items for respective collection

Sorting fields:

...

Parameter

...

Description

...

Ordering supported

	`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

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

Anchor

	toplevelonly
	toplevelonly

topLevelOnly

returns only top level communities

Anchor

	idonly
	idonly

idOnly

if true return only the identifiers for the record

Anchor

	immediateonly
	immediateonly

immediateOnly

return only direct parent community

Anchor

	isauthorized
	isauthorized

isAuthorized

return only collections user has permission to work on

Anchor

	inarchive
	inarchive

inArchive

return archived items for respective collection

Sorting fields:

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

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
	rcodes

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

Authentication/Authorization

Currently only standard authentication is supported. The authentication data is provided in the request or header body.

Example:

/rest/communities.json?user=user@email.com&pass=userpassword

The same elements user and pass are used for header based authentication.

Authorization is done on underlying api level; in the case of error the proper message and error code are returned to the user.

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`

...

sort results by entity id

...

asc | ascending
desc | descending

...

sort results by entity name

...

asc | ascending
desc | descending

...

sort results by number of items contained

...

asc | ascending
desc | descending

...

sort results by date of last item modification

...

asc | ascending
desc | descending

...

sort results by submitter name

...

asc | ascending
desc | descending

...

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

Authentication/Authorization

Currently only standard authentication is supported. The authentication data is provided in the request or header body.

Example:

/rest/communities.json?user=user@email.com&pass=userpassword

The same elements user and pass are used for header based authentication.

Authorization is done on underlying api level; in the case of error the proper message and error code are returned to the user.

Repository manipulation

Action to be done under community id, adding new content or values.
Supported actions:
createAdministrators
createCollection
createSubcommunity id, action
-
name
name 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 Remove attribute/value eid of element element from the community id.
Suported elements:
collections
children
administrators id, eid
cid
cid
- Action to be done under collection id, adding new content or values.
Supported actions:
createAdministrators
createSubmitters
createTemplateItem
createWorkflowGroup
id, action

-
-
-
step 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

C	Verb	URL	Description	Mandatory parameters	Optional parameters	Response Data	Formats	Response codes
•	`POST`	`/communities`	-	`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}	-	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`}	-	Response code	`json` `xml`		•	`POST`	`/collections`	-	Id ow newly created element	`json` `xml`	200, 400, 401, 403, 500	•	`PUT`	`/collections/{id}/{element`}	-	Response code	`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` `PUT`	/collectionscommunities/{id}/{element}/{cid}	Remove attribute/value `cid` from collection `id` Supported attributes: `administrators` `item` `submitters` `templateItem`	`id, cid`	`-`	Response code	`json` `xml`
	`PUT`	`/collections/{id}/logo`	Set the logo for collection `id`	`id`		Response code	binary

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
}	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	-	-	Response code
	`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, 401, 403, 500
	`GET` `DELETE`	`/itemscollections/{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	`{element}/{cid`}	Remove attribute/value `cid` from collection `id` Supported attributes: `administrators` `item` `submitters` `templateItem`	`id, cid`	`-`	Response code	`json` `xml`
	`PUT`	`/collections/{id}/logo`	Set the logo for collection `id`	`id`		Response code	binary

Content searching

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
`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`	`createBundle` `createSingleBitstream` `removeLicenses` `removeDspaceLicense` `licenseGranted`	Response code	`json` `xml`	200, 400, 401, 403, 500
	`PUT`	`/items/{id`}	Change parameters of an 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`
•	`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

...

Page tree

Versions Compared

Old Version 128

New Version 129

Key

Optional parameters

Sorting fields:

Optional parameters

Sorting fields:

Controlling results

Response codes

Authentication/Authorization

Repository manipulation

Controlling results

Response codes

Authentication/Authorization

Repository manipulation

Content searching

Item status and retrieval

Content searching

Item manipulation