Note | ||
---|---|---|
| ||
This is the page describing GSoC 2010 project ended officially in August 2010. The REST API project is continued after official GSoC date. The new address of wiki page is located at https://wiki.duraspace.org/display/DSPACE/REST+API. Please bookmark this page as all further development will be described there. Current GSoC page stays here for historical/documentation purposes. |
DSpace REST API - Bojan Suzic
...
In the following section listed are supported endpoints on the application level. The items market marked with dot (in C column) are in phase of implementation, while other items are considered already working.
Please note that additional tests should be made in order to ensure proper stability of the whole application.
...
C | Verb | URL | Description | Mandatory parameters | Optional parameters | Sorting fields | Response Data | Formats | Response codes | ||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
| | | Returns a list of all communities on the system or return just top level communities. | - | The list of communities containing DSPACE:respective fields . | | |||||||||
| | | Return detailed information about | | | - | DSPACE:Fields describing community. | | |||||||
| | | Return a particular data field found in the community
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 | | Respective field info | | |||||||||
| | | Return a community logo | | - | - | Contains community logo (bitstream) | | |||||||
| | | Return a list of all collections in the system. | - | The list of the collections containing DSPACE:respective fields. | | |||||||||
| | | Return detailed information about | | DSPACE:Fields of the collection entity. | | |||||||||
| | | Return a particular data field found in the collection
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 | | Respective field info | | |||||||||
| | | Return a list of the items in the system | - | - | - | The list of the items containing DSPACE:related fields . |
|
| ||||||
| | | Return detailed information about an item. | | - | | DSPACE:Fields of the item entity. | | 200, 204, 400, 500 | ||||||
| | | Return a particular data field fould in the item
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 | | - | - | Respective field info | | 200, 204, 400, 500 | ||||||
| | | Return bitstream object - usually the library item file. | | - | - | DSPACE:Fields of the bitstream entity. | | 200, 400, 401, 403, 404, 500 | ||||||
| | | Return a particular data field found in bitstream
Supported fields (for element ): mimeType - mime type of file bundles - bundles the bitstream is a part of checkSum - checksum of the file checkSumAlgorithm - checksum algorithm used description - bitstream description formatDescription - file format description sequenceId - sequence id of the file size - size of the file source - source (typically filename with path information) storeNumber - asset store number where the bitstream is stored userFormatDescription - user's format description name - bitstream name handle - unique id of the bitstream id - internal id of the bitstream type - type of the entity (referring to bitstream) | | - | - | Respective field info | | 200, 400, 401, 403, 404, 500 | ||||||
| | | Return bitstream | | - | - | Return bitstream | | 200, 400, 401, 403, 404, 500 | ||||||
| | | Return a list of the groups in the system | - | - | - | The list of the groups containing related DSPACE:fields . | | 200, 204, 400, 500 | ||||||
| | | Return a group object | | - | - | DSPACE:Fields of the group entity. | | 200, 204, 400, 500 | ||||||
| | | Return a particular data field found in the group entity
Supported fields (for element ): handle - unique id (external) id - internal id of the gruop isEmpty - is the group empty members - group members (as users) memberGroups - group members (as groups) name - group name type - entity type (referring to group) | | - | - | Respective field info | | 200, 204, 400, 500 | ||||||
| | | Return a list of the users in the system | - | - | - | The list of the users containing related DSPACE:fields . | | 200,204,400,500 | ||||||
| | | Return a user info | | - | - | DSPACE:Fields of the user entity. | | 200,204,400,500 | ||||||
| | | Return a particular data field found in the user
Supported fields (for element ): email - user's email firstName - first name fullName - full name handle - handle (unique, external) id - internal id of the user language - preferred language lastName - last name name - name netId - network id requireCertificate - requires certificate to login selfRegistered - is user self registered type - type of the object | | - | - | Respective field info | | 200,204,400,500 |
...
Sorting fields:
Info | ||
---|---|---|
| ||
The sorting of the fields / output results is currently partially supported. This part of the application is implemented independently of the endpoints and will be worked on after the most of endpoints are completed. |
Parameter | Description | Ordering supported | ||||||
---|---|---|---|---|---|---|---|---|
id | sort results by entity id | | ||||||
name | sort results by entity name | | ||||||
countitems | sort results by number of items contained | | ||||||
lastmodified | sort results by date of last item modification | | ||||||
submitterName | sort results by submitter name | | ||||||
submitterId | sort results by submitter id | |
...
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 |
---|---|---|---|---|---|---|---|---|
| | | Action to be done under community | | - | | | 200, 400, 401, 403, 500 |
| | /communities/{id}/{element} | Update the field | | - | Response code |
| 200, 400, 401, 403, 500 |
| | | Set the logo for community | | - | Response code | binary | 200, 400, 401, 403, 500 |
• | | | Delete community from the system | | - | Response code | | 200, 400, 401, 403, 500 |
• | | | Remove attribute/value | | - | Response code | |
|
| | Action to be done under collection | | - | Id ow newly created element | | 200, 400, 401, 403, 500 | |
| | Update field | | - | Response code | | 200, 400, 401, 403, 500 | |
• | | | Delete collection from the system | - | - | Response code | | 200, 400, 401, 403, 500 |
• | | | Remove attribute/value | | | Response code | | 200,400,401,403,500 |
• | | | Set the logo for collection | |
| Response code | binary | 200,400,401,403,500 |
• | | | Action to be done under item | |
| Id of newly created element | | 200,400,401,403,500 |
• | | | Update field | | - | Response code | | 200,400,401,403,500 |
• | | | Delete item from the system | | - | Response code | | 200,400,401,403,500 |
• | | | Delete element/attribute | | - | Response code | | 200,400,401,403,500 |
...
Info | ||
---|---|---|
| ||
This is considered as a experimental feature in the phase of being considered for compability with future versions of DSpace. Consider not important section; the status of the feature for upcoming release yet to be determined. |
C | Verb | URL | Description | Mandatory parameters | Optional parameters | Sorting fields | Response Data | Formats | Response codes |
---|---|---|---|---|---|---|---|---|---|
• | GET | /resource/{handle}/relations | Return entities according to relation and parameters specified | | | - | ontains entities selected and sorted in conformance to request parameters. For more details see description of | |
Mandatory parameters
Parameter | Description | Values | Example | ||||||
---|---|---|---|---|---|---|---|---|---|
property | Return entities satisfying requested property relation | Structural properties | | ||||||
rtype | restriction on type - only entity with specifed type(s) would be returned | | | ||||||
| restriction on fields - return only selected fields; by default all fields are returned | id | rfield=id,name - return only entity id and name in response |
Note: incomplete/orientative properties, for more info check [Vocabularies|http://code.google.com/p/dspace-sandbox/source/browse/#svn/modules/dspace-rdf/tags/dspace-rdf-1.5.1/src/main/java/org/dspace/adapters/rdf/vocabularies].
...
Here the visitors and stakeholders can insert their suggestions or describe the needs for their applications in detail.
Comment: In this case it is not clear how to treat recent
part of endpoint. If we stick to semantic mapping, then it should look like /resource/id/mapping
, but recent
in this case obviously do not represent a mapping, but the property.
Comment #2: Semantic mapping presented in this case should be probably hardcoded for 1.x branch, but on abstraction level which enables easy replacement with some auto-discovery method prepared for 2.x and eventually backported to 1.x. This way we would be able to call something similar to /communities/id
or communities/id/capabilities
in order to get supported mappings (amongst other data).
Suggesting new options:
Instead of changing wiki contents visitors can enter their suggestions as a comments.
...
- Confluence pages, current location
- integrated documentation in PDF form (manual)
- short slides containing technology overview, advocacy/facts, configuration and usage guideliens and examples
- code will be additionally commented
Example of usage
At the end of the current stage of this project as a bonus task (if time constraints allow) the examples of usage will be provided for several languages, the use-cases will be presented (example of integration in other software, e.g. LMS) and optionally simple client system demonstrating UI customization will be demonstrated (e.g. Flex or JavaFX like).
...