...
C | Verb | URL | Description | Mandatory parameters | Optional parameters | Sorting fields | Response Data | Formats | Response codes |
|---|
| GET | /communities | Returns a list of all communities on the system or return just top level communities. | - | topLevelOnly=true
idOnly=false | id
name
countitems | countitems - number of items under community
handle - handle of the community (unique persistent resource identifier)
id - entity identifier, internal to the system
name - entity name
type - entity type (object type in the system)
collections - collections contained in the community, ordered by id
ancestors - ancestors of the community, ordered by id
children - subcommunities, ordered by id
admins - group administrators, ordered by id
metadata - community metadata
administrators - default group of administrators
Response code details:
204 - if there are no communities on the system | json
xml | 200, 204, 400, 500 |
• | GET | /communities/{id} | Return information about id community. | id | idOnly=false | - | countitems - number of items under community
handle - handle of the community (unique persistent resource identifier)
id - entity identifier, internal to the system
name - entity name
type - entity type (object type in the system)
collections - collections contained in the community, ordered by id
ancestors - ancestors of the community, ordered by id
children - subcommunities, ordered by id
admins - group administrators, ordered by id
metadata - community metadata
administrators - default group of administrators
| json
xml | 200, 400, 404, 500 |
• | GET | /communities/{id}/relations
| Return entities according to relation and parameters specified | id
property
| rtype
rfield | - | Contains entities selected and sorted in conformance to request parameters. For more details see description of rtype and rfield. | json
xml | 200, 204, 400, 500 | • | GET | /communities/{id}/ancestors | Return a list of all ancestor communities of the id community. | id | idOnly=false
immediateOnly=true | id
name
countitems | countitems - number of items under community
handle - handle of the community (unique persistent resource identifier)
id - entity identifier, internal to the system
name - entity name
type - entity type (object type in the system)
collections - collections contained in the community, ordered by id
ancestors - ancestors of the community, ordered by id
children - subcommunities, ordered by id
admins - group administrators, ordered by id
metadata - community metadata
| json
xml | 200, 204, 400, 500 |
• | GET | /communities/{id}/children | Returns a list of immediate sub-communities (children) of the id community. | id | idOnly=false | id
name
countitems | countitems - number of items under community
handle - handle of the community (unique persistent resource identifier)
id - entity identifier, internal to the system
name - entity name
type - entity type (object type in the system)
collections - collections contained in the community, ordered by id
ancestors - ancestors of the community, ordered by id
children - subcommunities, ordered by id
admins - group administrators, ordered by id
metadata - community metadata
administrators - default group of administrators
| json
xml | 200, 204, 400, 500 |
• | GET | /communities/{id}/collections | Return a list of collections in the id community. | id | idOnly=false | id
name
countitems | countitems - number of items under collection
handle - handle of the collection
id - entity identifier, internal to the system
name - entity name
type - entity type (object type in the system)
items - items contained in the collection, ordered by id
communities - owners of the collection, ordered by id
admins - group administrators, ordered by id
licence - collection licence
templateItem - template item
Response code details:
204 - if there are no collections | json
xml | 200, 204, 400, 500 |
• | GET | /communities/{id}/recent | Return a list of recent submissions to a community. | id | idOnly=false | id
name
lastmodified
submitterId
submitterName | id - entity (item) identifier, internal to the system
handle - handle of the item
isArchived - archival status of the item
isWithdrawn - withdrawal status of the item
lastModified - timestamp of last modification
metadata - item metadata
name - item name
submitter - submiter entity
type - entity type (object type in the system, item in this case)
bitstreams - bitstreams related to the item
bundles - bundles related to the item
collections - collections related item appear in
communities - communities related item appear in
Response details:
204 - if there are no recently submitted items | json
xml | 200, 204, 400, 500 |
• | GET | /communities/{id}/logo | Return a community logo | id | - | - | Contains community logo (bitstream) | binary | 200, 400 |
• | GET | /collections | Return a list of all collections in the system. | - | idOnly=false
isAuthorized=false | id
name
countitems | Contains item count, identifiers, name and handle of collections, or 204 if
there are none of them. In the case idOnly=true is used, returns only
identifiers of collections. | json
xml | 200, 204, 400, 500 |
• | GET | /collections/{id} | Return information about id collection | id | idOnly=false | id
name
countitems | countitems - number of items under collection
items - items present in the collection
id - entity (collection) identifier, internal to the system
handle - handle of the collection
licence - collection licence
name - collection name
type - entity type (object type in the system, item in this case)
communities - communities related collection appear in
submiters - default group of submitters, if there is one
administrators - default group of administrators, if there is one
templateitem - template item for collection, if there is one
| json
xml | 200, 204, 400, 500 |
• | GET | /collections/{id}/ancestors
| Return a list of all ancestor communities a collection with id belongs to.
| id | idOnly=false
immediateOnly=true
| id
name
countitems
| countitems - number of items under community
handle - handle of the community (unique persistent resource identifier)
id - entity identifier, internal to the system
name - entity name
type - entity type (object type in the system)
collections - collections contained in the community, ordered by id
ancestors - ancestors of the community, ordered by id
children - subcommunities, ordered by id
admins - group administrators, ordered by id
metadata - community metadata
administrators - default group of administrators
| json
xml | 200, 204, 400, 500 |
• | GET | /collections/{id}/items
| Returns a list of all items from the collection id.
| id | idOnly=false
inArchive=false
| id
name
lastmodified
submitterId
submitterName | id - entity (item) identifier, internal to the system
handle - handle of the item
isArchived - archival status of the item
isWithdrawn - withdrawal status of the item
lastModified - timestamp of last modification
metadata - item metadata
name - item name
submitter - submiter entity
type - entity type (object type in the system, item in this case)
bitstreams - bitstreams related to the item
bundles - bundles related to the item
collections - collections related item appear in
communities - communities related item appear in
Response details:
204 - if there are no items
| json
xml
| 200, 204, 400, 500
|
• | GET | /collections/{id}/logo | Return a collection logo | id | - | - | Contains collection logo (bitstream) | binary | 200, 400 |
Note: modifier idOnly is referred only to first layer of the results. For all other layers (e.g. nested results) only ids are returned in some cases, due to possible loops. Example: for community containing collections, on second level the response contains only ids for some elements where multiple loops may be created (community->has_collection->has_community....). Other data is modified according to idOnly flag.
...
Optional parameters
Parameter | Description Values |
|---|
| Example | anchor | toplevelonly | 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.
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
topLevelOnly
| returns only top level communities |
idOnly | if true return only the identifiers for the record |
| Anchor |
|---|
| immediateonly |
|---|
| immediateonly |
|---|
|
immediateOnly | return only direct parent community |
isAuthorized | return only collections user has permission to work on |
inArchive | return archived items for respective collection |
Sorting fields:
Parameter | Description | Ordering supported |
|---|
id | sort results by entity id | asc | ascending
desc | descending |
name | sort results by entity name | asc | ascending
desc | descending
|
| 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 |
Response codes
Code | Description |
|---|
200 | OK |
201 | Created |
204 | No content |
400 | Bad request |
401 | Unauthorized |
403 | Forbidden |
404 | Not found |
405 | Method not allowed |
500 | Internal server error |
503 | Service unavailable |
Repository manipulation
C | Verb | URL | Description | Mandatory parameters | Optional parameters | Response Data | Formats | Response codes |
|---|
• | PUT | /communities/{id} | Change description of id community
| id | name
metadata
logo | Response code | json
xml | 200, 400, 401, 403, 500 |
• | POST | /communities | Add community to the system
| name | logo
parent
other metadata
| Id of newly created community | json
xml | 200, 400, 401, 403, 500 |
•
| DELETE | /communities/{id} | Delete community from the system | id | - | Response code | json
xml | 200, 400, 401, 403, 500 |
•
| DELETE | /communities/{id}/administrators
| Remove the administrators group from the community | id | - | Response code | json
xml | |
•
| DELETE | /communities/{id}/collections/{cid}
| Remove collection cid from community id | id
| cid | Response code | | |
•
| DELETE
| /communities/{id}/children/{cid}
| Remove subcommunity cid from community id | id | cid | Response code | | |
•
| POST | /communities/{id}/administrators
| Create a default administrators group if one does not already exists | id | - | Id of newly created group
| | |
•
| POST | /communities/{id}/collections
| Create a new collection within community id | id | - | Id of newly created collection
| | |
•
| PUT | /communities/{id}/collections/{cid}
| Add an existing collection cid to community id | id
cid | -- | Response code | | |
•
| POST | /communities/{id}/children
| Create a new subcommunity within community id | id | - | Id of newly created subcommunity | | |
•
| PUT | /communities/{id}/children/{cid}
| Add an existing community cid as a subcommunity of community id | id
cid | - | Response code | | |
| PUT | /communities/{id}/metadata | Set metadata value | id | metadataField
metadataValue |
...
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 |
Repository manipulation
C | Verb | URL | Description | Mandatory parameters | Optional parameters | Response Data | Formats | Response codes |
|---|
• | PUT | /communities/{id} | Change description of id community
| id | name
metadata
logo | Response code | json
xml | 200, 400, 401, 403, 500 |
• | POST | /communities | Add community to the system
| name | logo
parent
other metadata
| Id of newly created community | json
xml | 200, 400, 401, 403, 500 |
•
| DELETE | /communities/{id} | Delete community from the system | id | - | Response code | json
xml | 200, 400, 401, 403, 500 |
•
| DELETE | /communities/{id}/administrators
| Remove the administrators group from the community | id | - | Response code | json
xml | |
•
| DELETE | /communities/{id}/collections/{cid}
| Remove collection cid from community id | id
cid | Response code | | | •
| DELETE
| /communities/{id}/children/{cid}
| Remove subcommunity cid from community id | id | cid | Response code | | |
•
| POST PUT | /communitiescollections/{id} /administrators
| Create a default administrators group if one does not already exists | id | - | Id of newly created group
| | | Change description of id collection | id | | Response code | json
xml | 200, 400, 401, 403, 500 |
•
| POST | /communities/{id}/collections
| Create a new collection within community id | id | collections
| Add collection to the system | name
communityId | - | Id of newly created collection | json
| | xml | 200, 400, 401, 403, 500 |
•
| PUT DELETE | /communitiescollections/{id}/collections/{cid} | Add an existing collection cid to community id | id
cid | Delete collection from the system | - | - -- | Response code | json
xml | 200, 400, 401, 403, 500 |
| • DELETE | POST | /communitiescollections/{id}/children
| Create a new subcommunity within community id | id | - | Id of newly created subcommunity | | | items/{cid}
| Delete item cid from collection | •
| PUT | /communities/{id}/children/{cid}
| Add an existing community cid as a subcommunity of community id | id | cid -
| Response code | json
xml | |
| PUT | /communitiescollections/{id}/metadatalogo | Set metadata value the logo for collection id | id | metadataField metadataValue | Response code | | |
• | PUT POST | /collections/{id} Change description of id collection /administrators
| Create a default administrators group if one does not already exists | 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}/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 | •
| 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 submitters
| Remove the submitters group | id | cid - | Response code | json xml | |
| PUT | /collections/{id}/logotemplateitem
| Create an empty template item for this collection Set the logo for collection id | id | - | Response code | | |
| POST DELETE | /collections/{id}/administrators Create a default administrators group if one does not already exists templateitem
| Remove the template item from the collection | id | - | Response code | | |
| DELETE POST | /collections/{id}/administrators
items
| Add an item to the Remove the administrators group from the collection | id
| - itemId | Response code | | |
| PUT | /collections/{id}/submitters Create metadata
| Set metadata value a default submitters group if one does not already exists | id
- | metadataField
metadataValue
| Response code | | |
| DELETE PUT | /collections/{\id}/submitters Remove the submitters group licence
| Set collection licence | id | - licence | Response code | | |
| PUT | /collections/{id}/templateitem | Create an empty template item for this collection | id | - | | | | | | Response code | | |
| DELETE | /collections/{id}/templateitem | Remove the template item from the collection | id | - | Response code | | |
| POST | /collections/{id}/items | Add an item to the collection | id
| itemId | Response code | | |
| PUT | /collections/{id}/metadata | Set metadata value | id
| metadataField
metadataValue
| Response code | | |
| PUT | /collections/{\id}/licence | Set collection licence | id | licence | Response code | | |
| | | | | | | | |
Content searching
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
|
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 |
| - | 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 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
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 |
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 |
...
Administrative tasks
Workflow related tasks
Relationships interface
C | Verb | URL | Description | Mandatory parameters | Optional parameters | Sorting fields | Response Data | Formats | Response codes |
|---|
•
| GET
| /communities/{id}/relations
| Return entities according to relation and parameters specified
| id
property
| rtype
rfield | - | ontains entities selected and sorted in conformance to request parameters. For more details see description of rtype andrfield.
| json
xml
| [200, 204, 400, 500 | #rcodes]
|
h5. Mandatory parameters |
Parameter | Description | Values | Example |
|---|
property | Return entities satisfying requested property relation | Structural properties
ds:isPartOfSite
ds:isPartOfCommunity
ds:isPartOfCollection
ds:isPartOfItem
ds:isPartOfBundle
ds:hasCommunity
ds:hasCollection
ds:hasItem
ds:hasBundle
ds:hasBitstream
ds:hasBitstreamFormat
Communities and collections
ds:logo
Bistream format
ds:support
ds:fileExtension
ds:mimeType
Bitstream
ds:messageDigest
ds:messageDigestAlgorithm
ds:messageDigestOriginator
ds:size
Eperson
ds:language
| property=ds:hasCommunity - return subcommunities of a community
property=ds:isPartOfCommunity - return communities current community is part of (children)
property=ds:hasCollection - return collections belonging to community
property=ds:hasItem - return Items belonging to community |
rtype | restriction on type - only entity with specifed type(s) would be returned | ds:Bitstream
ds:Bundle
ds:Collection
ds:Community
ds:EPerson
ds:Group
ds:Item
ds:DSpaceObject
ds:Policy
ds:Site
ds:BitstreamFormat| | rtype=ds:Collection - return entities of Collection type |
rfield | restriction on fields - return only selected fields; by default all fields are returned | id
name
countitems
metadata
subcommunities
ancestors
owner
other (depending on object type, will be documented later) | rfield=id,name - return only entity id and name in response |
Note: incomplete/orientative properties, for more info check [Vocabularies|http://code.google.com/p/dspace-sandbox/source/browse/#svn/modules/dspace-rdf/tags/dspace-rdf-1.5.1/src/main/java/org/dspace/adapters/rdf/vocabularies].
Visitors' suggestions or wishes
...