-
Notifications
You must be signed in to change notification settings - Fork 0
ARCore API 0.0.1
As of 4/16/2021, here's the AR Core API/functionality with examples:
A server running at http://172.30.8.231:11111/ is configured to interact with the https://dv.dev-aws.qdr.org/ Dataverse server.
Parse a Word document (.docx only) or a PDF with 'Highlight' -style comments to create a PDF version w/o comments to and extract all comments as json ~annotations.
PUT /api/documents/<id>
<id> is the internal ID of the source DataFile in Dataverse
Requires an 'X-Dataverse-key' header with a valid Dataverse API key for someone who can access/edit that Datafile/Dataset.
Example:
curl -H "X-Dataverse-key:74cc5072-a157-4141-b94e-2fe6a0c93638" -X PUT http://172.30.8.231:11111/api/documents/6853
Responses:
- 200/OK with the file ID as the response - depending on file size, this would be slow as the call returns after the processing is complete.
- 409/Conflict if the pdf and annotations have already been created
- 404 if the Datafile itself can't be found
- 403 if the api key is invalid
Delete is primary for use in testing right now, as the original word file in Dataverse can't change. (If you replace it, the replacement has a new id.)
DELETE /api/documents/<id>
<id> is the internal ID of the source DataFile in Dataverse
Requires an 'X-Dataverse-key' header with a valid Dataverse API key for someone who can access/edit that Datafile/Dataset.
Example:
curl -H "X-Dataverse-key:74cc5072-a157-4141-b94e-2fe6a0c93638" -X DELETE http://172.30.8.231:11111/api/documents/6853
Responses:
- 204/NO CONTENT
- 403/404 as above
- 500 - the pdf and ann file are deleted in two separate calls to Dataverse, 500 indicates that they came back with different statuses, which shouldn't happen if the client is only using this API
GET /api/documents/<id>/pdf
<id> is the internal ID of the source DataFile in Dataverse
No 'X-Dataverse-key' header is required. However, the key will be needed to retrieve the file from Dataverse so if you use a library that can follow redirects (as when using -L with curl) you can add the header when retrieving the initial URL.
Example:
curl -L -H "X-Dataverse-key:74cc5072-a157-4141-b94e-2fe6a0c93638" http://172.30.8.231:11111/api/documents/6853/pdf
Reponses:
- 302 - this call just returns a redirect, the URL redirected to should send the pdf file,
- 403/404 after the redirect, i.e. if you have a bad key or the pdf file hasn't been generated yet.
GET /api/documents/<id>/ann
<id> is the internal ID of the source DataFile in Dataverse
No 'X-Dataverse-key' header is required. However, the key will be needed to retrieve the file from Dataverse so if you use a library that can follow redirects (as when using -L with curl) you can add the header when retrieving the initial URL.
Example:
curl -L -H "X-Dataverse-key:74cc5072-a157-4141-b94e-2fe6a0c93638" http://172.30.8.231:11111/api/documents/6853/ann
Reponses:
- 302 - this call just returns a redirect, the URL redirected to should send the json annotation file,
- 403/404 after the redirect if you have a bad key or the ann file hasn't been generated yet.
These should follow the Hypothesis format for annotations but the structure differs slightly since these haven't been submitted to Hypothesis so there's no update date, no group, etc. (See one of our test files from Hypothesis for comparison.)
At present, they use a TextQuoteSelector, and A TextPositionSelector. (If we want others, let me know.)
Text quote selectors should have 32 chars from before and after the comment anchor, the exact text of the anchor, and the text in the comment.
Text position selectors just have the start and end offsets in the doc text represented as a string.
Overlapping comments should be handled correctly. (Paragraph boundaries are shown as \n\n - have to verify this is valid.)
[
{
"target": [
{
"source": "https://dv.dev-aws.qdr.org/api/access/datafile/6853/metadata/ingestPDF/v1.0",
"selector": [
{
"type": "TextQuoteSelector",
"exact": "data",
"prefix": "\nThis is a test file about some ",
"suffix": ".\n\n\n\nOne could have a much more "
},
{
"type": "TextPositionSelector",
"start": 50,
"end": 54
}
]
}
],
"text": "doi:10.33564/FK2VCFQWP/FFEUOF – the data in this file is most random!",
"uri": "https://dv.dev-aws.qdr.org/api/access/datafile/6853/metadata/ingestPDF/v1.0",
"document": {
"title": [
"A Sample Document"
]
}
},
{
"target": [
{
"source": "https://dv.dev-aws.qdr.org/api/access/datafile/6853/metadata/ingestPDF/v1.0",
"selector": [
{
"type": "TextQuoteSelector",
"exact": "more complex test file than ",
"prefix": " data.\n\n\n\nOne could have a much ",
"suffix": "this.\n\nHowever, this one will do"
},
{
"type": "TextPositionSelector",
"start": 81,
"end": 109
}
]
}
],
"text": "yikes",
"uri": "https://dv.dev-aws.qdr.org/api/access/datafile/6853/metadata/ingestPDF/v1.0",
"document": {
"title": [
"A Sample Document"
]
}
},
{
"target": [
{
"source": "https://dv.dev-aws.qdr.org/api/access/datafile/6853/metadata/ingestPDF/v1.0",
"selector": [
{
"type": "TextQuoteSelector",
"exact": "than this",
"prefix": "e a much more complex test file ",
"suffix": ".\n\nHowever, this one will do for"
},
{
"type": "TextPositionSelector",
"start": 104,
"end": 113
}
]
}
],
"text": "i.e. one referencing more than just three datafiles, including doi:10.33564/FK2VCFQWP/ODSQXX and doi:10.33564/FK2VCFQWP/2HZXBE",
"uri": "https://dv.dev-aws.qdr.org/api/access/datafile/6853/metadata/ingestPDF/v1.0",
"document": {
"title": [
"A Sample Document"
]
}
}
]
These examples come from a test file at https://dv.dev-aws.qdr.org/file.xhtml?persistentId=doi:10.33564/FK2VCFQWP/I9YXOU&version=DRAFT
which results in a document string:
A Sample Document This is a test file about some data . One could have a much more complex test file than this . However, this one will do for now. Exceptt it would be nice to know about this case.