Citesphere Documentation
API Documentation
- Navaneesh Kumar Bajakudlu (Unlicensed)
- Julia Damerow
- Pradnya Chaudhari
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.
status:ENDPOINT Url status: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.
status:ENDPOINT Url status: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.
status:ENDPOINT Url status: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.
status:ENDPOINT Url status:GET /groups/{groupId}/collections
status:ENDPOINT Url status:GET /groups/{groupId}/collections/{collectionId}/collections
status:Parameters
maxCollectionNumber The returned number of collections can be limited using this parameter.
Example Response:
{
"group": {
"id": 1234,
"name": "test",
"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"
}
},
"collections": [
{
"id": {
"timestamp": 1601486250,
"date": 1601486250000
},
"key": "FG78888",
"version": 291,
"contentVersion": 0,
"numberOfCollections": 0,
"numberOfItems": 0,
"name": "hello",
"parentCollectionKey": "AAA4444",
"lastModified": null,
"groupId": "1234"
}
]
}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.
status:ENDPOINT Url status:GET /groups/{groupId}/items
status:ENDPOINT Url status:GET /groups/{groupId}/collections/{collectionId}/items
status:Parameters
page The page to be returned. A page has at most 50 items.
sort status:Experimental How the items should be sorted. Default is title. This feature is experimental.
Example Response:
{
"group": {
"id": 1123,
"name": "My Group",
"version": 4,
"created": "2018-09-10T20:04:46Z",
"lastModified": "2019-06-20T12:01:29Z",
"numItems": 2172,
"owner": 1111,
"type": "Private",
"description": "",
"url": "",
"syncInfo": {
"createdOn": "2020-09-30T15:55:18-04:00",
"status": "DONE"
}
},
"items": [
{
"key": "CXCXX",
"group": "1123",
"version": 4873,
"title": "THE EFFECTS OF A DIET OF POLISHED AND OF UNPOLISHED RICE UPON THE METABOLIC ACTIVITY OF PARAMECIUM",
"authors": [
{
"@type": "Person",
"name": "Mary Drusilla Flather",
"uri": null,
"localAuthorityId": null,
"firstName": "Mary Drusilla",
"lastName": "Flather",
"positionInList": 0,
"affiliations": null
}
],
"editors": [],
"otherCreators": [],
"itemType": "JOURNAL_ARTICLE",
"publicationTitle": "",
"volume": "36",
"issue": "",
"pages": "",
"date": "1919-01-01T00:00Z",
"dateFreetext": "1919",
"series": "",
"seriesTitle": "",
"url": "",
"abstractNote": "",
"accessDate": "",
"seriesText": "",
"journalAbbreviation": "",
"language": "",
"doi": null,
"issn": null,
"shortTitle": "",
"archive": "",
"archiveLocation": "",
"libraryCatalog": "",
"callNumber": "",
"rights": "",
"collections": [
"V5B7E56T"
],
"dateAdded": "2020-07-09T21:20:03Z",
"dateModified": null,
"conceptTagIds": null,
"conceptTags": null,
"references": null,
"extra": "Bryn Mawr",
"otherCreatorRoles": []
},
...
}
]
}Item Endpoint
The items endpoint returns the item in a group or collection.
status:ENDPOINT Url status:GET /groups/{groupId}/items/{itemkey}
Example Response:
{
"item": {
"key": "QXW9QRID",
"group": "2256709",
"version": 3128,
"title": "Alvin and Chipmunks",
"parentItem": null,
"authors": [],
"editors": [],
"otherCreators": [],
"itemType": "FILM",
"publicationTitle": null,
"volume": null,
"issue": null,
"pages": null,
"date": "2012-01-01T00:00Z",
"dateFreetext": "2012",
"series": null,
"seriesTitle": null,
"url": "",
"note": null,
"abstractNote": "",
"accessDate": "",
"seriesText": null,
"journalAbbreviation": null,
"language": "",
"doi": null,
"issn": null,
"shortTitle": "Alvin and Chipmunks",
"archive": "",
"archiveLocation": "",
"libraryCatalog": "",
"callNumber": "",
"rights": "",
"collections": [
"SU742HVM",
"S9UZ98XH"
],
"deleted": 0,
"tags": [],
"metaDataItemKey": "EDG5CWSZ",
"metaDataItemVersion": 3131,
"dateAdded": "2021-08-23T20:09:35Z",
"dateModified": null,
"conceptTagIds": [],
"conceptTags": [],
"references": [],
"gilesUploads": [
{
"@type": "GilesUpload",
"progressId": "PROGfd7typ",
"documentId": "DOCNCP8o76Auxc6",
"uploadId": "UPLXpv09WZx0US",
"uploadedDate": "2023-10-05T18:43:01.228659Z",
"uploadedFile": {
"@type": "GilesFile",
"id": "FILEfItViY7iUgLM",
"filename": "2023ââ?¬â??24 Arizona Wildcats men_s basketball team - Wikipedia.pdf",
"url": "https://diging.asu.edu/geco-giles-staging/rest/files/FILEfItViY7iUgLM/content",
"size": 1285219,
"processor": null,
"content-type": "application/pdf"
},
"extractedText": null,
"additionaFiles": null,
"pages": null,
"documentStatus": "FAILED",
"uploadingUser": null
}
],
"extra": null,
"hidden": 0,
"otherCreatorRoles": [],
"metaDataNote": false
},
"attachments": []
}Create Item Endpoint
The create items endpoint creates the item in mentioned group and collection returns the created item in a group or collection.
status:ENDPOINT Url status:POST /groups/{groupId}/items/create
status:Accecpted MediaType MULTIPART_FORM_DATA_VALUE
status:Parameters
collectionId The collection ID to which the item should be added in the group
title Title of the item
itemType status:REQUIRED Mention the type of item eg. book, journalArticle, etc. (Refer to enum values of ItemType mentioned on citesphere-model/citesphere-model/src/main/java/edu/asu/diging/citesphere/model/bib/ItemType.java at develop · diging/citesphere-model )
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 citesphere/citesphere/src/main/resources/creators.properties at develop · diging/citesphere Mentioning role for author & editor is optional.
[{
"firstName": "first_name",
"lastName": "last_name",
"uri": "uri,
"localAuthorityId": "local_authority_id",
"position": 0,
"role": "role",
"affiliations": { "name": "affiliation_name",
"uri": "affiliation_uri"}
}]Example Response for 200 OK:
{
"key": "BNMB288F",
"group": "5470074",
"version": 341,
"title": "Test 4",
"parentItem": null,
"authors": [],
"editors": [],
"otherCreators": [],
"itemType": "BOOK",
"publicationTitle": null,
"volume": "",
"issue": null,
"pages": null,
"date": null,
"dateFreetext": "",
"series": "",
"seriesTitle": null,
"url": "",
"note": null,
"abstractNote": "",
"accessDate": "",
"seriesText": null,
"journalAbbreviation": null,
"language": "",
"doi": null,
"issn": null,
"shortTitle": "",
"archive": "",
"archiveLocation": "",
"libraryCatalog": "",
"callNumber": "",
"rights": "",
"collections": [],
"deleted": 0,
"tags": [],
"metaDataItemKey": "CUXSR4EC",
"metaDataItemVersion": 342,
"dateAdded": "2024-09-13T17:19:21Z",
"dateModified": null,
"conceptTagIds": [],
"conceptTags": [],
"references": [],
"gilesUploads": [],
"extra": null,
"hidden": 0,
"otherCreatorRoles": [],
"metaDataNote": false
}Example Response for 400 BAD REQUEST (For invalid itemType):
{
"itemType": "Failed to convert property value of type 'java.lang.String' to required type 'edu.asu.diging.citesphere.model.bib.ItemType' for property 'itemType'; nested exception is org.springframework.core.convert.ConversionFailedException: Failed to convert from type [java.lang.String] to type [edu.asu.diging.citesphere.model.bib.ItemType] for value 'BOOK2'; nested exception is java.lang.IllegalArgumentException: No enum constant edu.asu.diging.citesphere.model.bib.ItemType.BOOK2",
}Example Response for 401 Unauthorized (Citesphere token missing/expired)
{
"error": "unauthorized",
"error_description": "Full authentication is required to access this resource"
}Example Response for 400 Bad Request (For missing itemType)
Error: Missing Item Type