Citesphere Documentation
API Documentation
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 https://diging.atlassian.net/wiki/spaces/CITED/pages/2081718281 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: