Citesphere Documentation
API Documentation
- Navaneesh Kumar Bajakudlu (Unlicensed)
- Pradnya Chaudhari
- Julia Damerow
This documentations documents version 1 of the Citesphere API. All endpoints are prefixed with /api/v1.
Authentication
Citesphere requires OAuth2 token for accessing the endpoints. Checkout OAuth2 Documentation to know more about retrieving the access_token (a.k.a Bearer token). You should add the below header for accessing any endpoint.
Header Name: Authorization
Header Value: Bearer <access_token>, example: Bearer 05fa6b64-a5ee-4cce-78bb-cc492e1d73a7
Test Endpoint
This endpoint returns all the available REST endpoints.
ENDPOINT Url GET /test
Example response:
[
{
"user": "myusername"
},
{
"info": "{ /api/v1/test}"
},
{
"info": "{ /api/v1/upload}"
},
...
}Groups Endpoint
The groups endpoint returns all the groups the authenticating user has access to.
ENDPOINT Url GET /groups
Example Response:
[
{
"id": 1234,
"name": "dataset",
"version": 2,
"created": "2020-06-02T18:40:57Z",
"lastModified": "2020-06-10T18:30:24Z",
"numItems": 345,
"owner": 111,
"type": "Private",
"description": "",
"url": "",
"syncInfo": null
},
{
"id": 56789,
"name": "Shared Group",
"version": 3,
"created": "2019-08-15T18:02:36Z",
"lastModified": "2019-08-15T18:12:40Z",
"numItems": 5555,
"owner": 1123,
"type": "Private",
"description": "",
"url": "",
"syncInfo": null
}
]Group Endpoint
This endpoint returns information about a specific group. The returned information will also include sync information for a group.
ENDPOINT Url GET /groups/{groupId}
Example Response:
{
"id": 1234,
"name": "dataset",
"version": 18,
"created": "2018-11-19T21:34:21Z",
"lastModified": "2020-09-22T21:11:07Z",
"numItems": 37,
"owner": 1111,
"type": "Private",
"description": "<p>This is for testing Citesphere.</p>",
"url": "",
"syncInfo": {
"createdOn": "2020-09-30T13:17:26-04:00",
"status": "DONE"
}
}Groups have sync information, which contains a status. The status should be used to determine if the another request should be made to get updated data. Only when the status is DONE syncing is complete. If sync is anything, the client should make a follow up request to get updated data until the status is DONE.
Collections Endpoint
The collections endpoint returns all collections in a group or in a collection.
ENDPOINT Url GET /groups/{groupId}/collections, /groups/{groupId}/collections/{collectionId}/collections
Parameters
maxCollectionNumber The returned number of collections can be limited using this parameter.
Example Response:
Groups have sync information, which contains a status. The status should be used to determine if the another request should be made to get updated data. Only when the status is DONE syncing is complete. If sync is anything, the client should make a follow up request to get updated data until the status is DONE.
Items Endpoint
The items endpoint returns the items in a group or collection.
ENDPOINT Url GET /groups/{groupId}/items, /groups/{groupId}/collections/{collectionId}/items
Parameters
page The page to be returned. A page has at most 50 items.
sort Experimental How the items should be sorted. Default is title. This feature is experimental.
Example Response:
Item Endpoint
The items endpoint returns the item in a group or collection.
ENDPOINT Url GET /groups/{groupId}/items/{itemkey}
Example Response:
Create Item Endpoint
The create items endpoint creates the item in mentioned group and collection returns the created item in a group or collection.
ENDPOINT Url POST /groups/{groupId}/items/create
Accecpted MediaType MULTIPART_FORM_DATA_VALUE
Parameters
collectionId The collection ID to which the item should be added in the group
title Title of the item
itemType REQUIRED Mention the type of item eg. book, journalArticle, etc. (Refer to enum values of ItemType mentioned on https://github.com/diging/citesphere-model/blob/develop/citesphere-model/src/main/java/edu/asu/diging/citesphere/model/bib/ItemType.java )
publicationTitle Title of the publication of the item.
volume The Volume number of the journal or series
issue the issue number of the journal or series.
pages the page range in the publication.
dateFreetext Free-text format of the publication date.
series The series number of the publication.
seriesTitle The title of the series.
url The URL link to the online source or publication.
abstractNote The abstract or summary of the publication (if available).
seriesText Additional text or details about the series.
journalAbbreviation Abbreviation of the journal title.
language The language in which the document is written.
doi The DOI (Digital Object Identifier) of the publication.
issn The ISSN (International Standard Serial Number) for the journal.
shortTitle A shortened version of the title.
authors List of authors of the document. (Refer to example value given below)
editors List of editors of the document. (Refer to example value given below)
otherCreators Any other contributors to the publication. (Refer to example value given below)
archive The name of the archive where the document is stored.
archiveLocation The specific location within the archive.
libraryCatalog The catalog or system used by the library to list the publication.
callNumber The call number for locating the document in the library.
rights Information about the rights and permissions of the publication.
files Item files that will be processed by Giles.
Example value for authors/editors/otherCreators:
Role in below example can be any value mentioned on https://github.com/diging/citesphere/blob/develop/citesphere/src/main/resources/creators.properties Mentioning role for author & editor is optional.
Example Response for 200 OK:
Example Response for 400 BAD REQUEST (For invalid itemType):
Example Response for 401 Unauthorized (Citesphere token missing/expired)
Example Response for 400 Bad Request (For missing itemType)