...
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 id - entity identifier, internal to the system
name - entity name
countItems - number of items under community community
handle - handle of the community (unique persistent resource identifier)
id - entity identifier, internal to the system
name - entity name
type - entity entity type (object type in the system)
collections - collections collections contained in the community, ordered by id
ancestors - ancestors of the community, ordered by id
children id
canedit - states user persmission on the item (editing)
anchestor - anchestors of the community
children - subcommunities, ordered by id id
admins administrators - group administrators, ordered by id
metadata - community metadata
administrators - default group of administrators id
recent - recent items in the community
shortDescription - short description
copyrightText - copyright text
sidebarText - sidebar text
introductoryText - introductory text
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 | - | id - entity identifier, internal to the system
name - entity name
countitems countItems - number of items under community 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 type - entity type (object type in the system)
collections - collections collections contained in the community, ordered by id
ancestors - ancestors of the community, ordered by id
children id
canedit - states user persmission on the item (editing)
anchestor - anchestors of the community
children - subcommunities, ordered by id id
admins administrators - group administrators, ordered by id id
metadata - community metadata
administrators - default group of administrators
recent - recent items in the community
shortDescription - short description
copyrightText - copyright text
sidebarText - sidebar text
introductoryText - introductory text
| json
json
xml | 200, 400, 404, 500 |
• | GET | /communities/{id}/}{element} | Return a particular data field found in the community {id}
Fields supported:
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 item (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 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 | 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 | 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 | /communitiescollections/{id} /logo | Return a community logo information about id collection | id - | idOnly=false | - | 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. | 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}/{element}
| Return information about id collection 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 collection community
items - items present in the collection
id - entity (collection) handle - handle of the community (unique persistent resource identifier)
id - entity identifier, internal to the system
handle - handle of the collection
licence - collection licence
name - collection name
type system
name - entity 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 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 , if there is one
templateitem - template item for collection, if there is one
| json
xml | 200, 204, 400, 500 |
• | GET | /collections/{id}/{element}
| 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 |
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
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 |
|---|
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
...
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 |
|---|
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
|
...
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 |
|---|
• | 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 | 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 | | |
| | | | | | | | |
...