API Endpoints¶
Authentication¶
Refer to the authentication details here.
Duplicate File Handling¶
When Uploading
or Transferring
resources a header, presqt-file-duplicate-action
, must be
included. The options are ignore
or update
. This header tells the target uploading the
resource what to do when a file being uploaded already exists in the source target.
Ignore
will not update the duplicate file, even if the contents of the files don’t match.
Update
will only update the duplicate file if the contents of the files don’t match.
Searching Resource Collections¶
Search results are ordered by date modified unless the target does not support it.
Only a single search filter can be used at a time.
Search Filters¶
General search across all available target search parameters: resources/?general=search_value
Search by project ‘title’: resources/?title=Project+Title
Search by project ‘id’: resources/?id=123456
Search by project ‘author’: resources/?author=bfox6
Search by project ‘keywords’: resources/?keywords=cat
Paginating Resource Collections¶
Pagination has been added at the collection level to improve load times. Targets now return Pagination information for users resources, as well as searched resources.
Page Parameter¶
Pagination across all available targets: resources/?page=page_number
Target Endpoints¶
Target Collection¶
-
GET
/api_v1/targets/
¶ Retrieve details of all
Targets
.Example request:
GET /api_v1/targets/ HTTP/1.1 Host: presqt-prod.crc.nd.edu Accept: application/json
Example response:
HTTP/1.1 200 OK Content-Type: application/json [ { "name": "osf", "readable_name": "OSF", "status_url": "https://api.osf.io/v2/nodes/", "token_url": "https://osf.io/settings/tokens", "supported_actions": { "resource_collection": true, "resource_detail": true, "resource_download": true, "resource_upload": true, "resource_transfer_in": true, "resource_transfer_out": true "keywords": true, "keywords_upload": true, }, "supported_transfer_partners": { "transfer_in": [ "github", "curate_nd" ], "transfer_out": [ "github" ] }, "supported_hash_algorithms": [ "sha256", "md5" ], "infinite_depth": true "links": [ { "name": "Detail", "link": "https://presqt-prod.crc.nd.edu/api_v1/targets/osf/", "method": "GET" } ] }, { "name": "curate_nd", "readable_name": "CurateND", "status_url": "https://curate.nd.edu/api/items", "token_url": "https://curate.nd.edu/api/access_tokens", "supported_actions": { "resource_collection": true, "resource_detail": true, "resource_download": true, "resource_upload": false, "resource_transfer_in": false, "resource_transfer_out": true, "keywords": true, "keywords_upload": false, }, "supported_transfer_partners": { "transfer_in": [], "transfer_out": [ "osf", "github" ] }, "supported_hash_algorithms": [ "md5" ], "infinite_depth": false "links": [ { "name": "Detail", "link": "https://presqt-prod.crc.nd.edu/api_v1/targets/curate_nd/", "method": "GET" } ] } ]
- Status Codes
200 OK –
Targets
successfully retrieved
Target Details¶
-
GET
/api_v1/targets/(str: target_name)/
¶ Retrieve details of a single
Target
.Example request:
GET /api_v1/targets/OSF/ HTTP/1.1 Host: presqt-prod.crc.nd.edu Accept: application/json
Example response:
HTTP/1.1 200 OK Content-Type: application/json { "name": "osf", "readable_name": "OSF", "status_url": "https://api.osf.io/v2/nodes/", "token_url": "https://osf.io/settings/tokens", "supported_actions": { "resource_collection": true, "resource_detail": true, "resource_download": true, "resource_upload": true, "resource_transfer_in": true, "resource_transfer_out": true, "keywords": true, "keywords_upload": true, }, "supported_transfer_partners": { "transfer_in": [ "github", "curate_nd" ], "transfer_out": [ "github" ] }, "supported_hash_algorithms": [ "sha256", "md5" ], "infinite_depth": true "links": [ { "name": "Collection", "link": "https://presqt-prod.crc.nd.edu/api_v1/targets/osf/resources/", "method": "GET" }, { "name": "Upload", "link": "https://presqt-prod.crc.nd.edu/api_v1/targets/osf/resources/", "method": "POST" }, { "name": "Transfer", "link": "https://presqt-prod.crc.nd.edu/api_v1/targets/osf/resources/", "method": "POST" } ] }
- Status Codes
200 OK –
Target
successfully retrieved404 Not Found – Invalid
Target
name
Resource Endpoints¶
Resource Collection¶
-
GET
/api_v1/targets/(str: target_name)/resources/
¶ Retrieve details of all top level resources for a given
Target
andUser Token
Example request:
GET /api_v1/targets/OSF/resources/ HTTP/1.1 Host: presqt-prod.crc.nd.edu Accept: application/json
Example response:
HTTP/1.1 200 OK Content-Type: application/json { "resources": [ { "kind": "container", "kind_name": "project", "id": "cmn5z", "container": null, "title": "Test Project", "links": [ { "name": "Detail", "link": "https://presqt-prod.crc.nd.edu/api_v1/targets/osf/resources/cmn5z/", "method": "GET" } ] }, { "kind": "container", "kind_name": "project", "id": "12345", "container": null, "title": "Egg Project", "links": [ { "name": "Detail", "link": "https://presqt-prod.crc.nd.edu/api_v1/targets/osf/resources/12345/", "method": "GET" } ] } ], "pages": { "first_page": "https://presqt-prod.crc.nd.edu/api_v1/targets/osf/resources?page=1", "previous_page": "https://presqt-prod.crc.nd.edu/api_v1/targets/osf/resources?page=5", "next_page": "https://presqt-prod.crc.nd.edu/api_v1/targets/osf/resources?page=7", "last_page": "https://presqt-prod.crc.nd.edu/api_v1/targets/osf/resources?page=30", "total_pages": 1, "per_page": 10, "base_page": "https://presqt-prod.crc.nd.edu/api_v1/targets/osf/resources?page=" } }
Example request w/ search parameter:
GET /api_v1/targets/OSF/resources?title=egg/ HTTP/1.1 Host: presqt-prod.crc.nd.edu Accept: application/json
Example request w/ search parameter and page parameter:
GET /api_v1/targets/OSF/resources?title=egg&page=3/ HTTP/1.1 Host: presqt-prod.crc.nd.edu Accept: application/json
Search filtering rules can be found here.
- Request Headers
presqt-source-token – User’s token for the source target
- Status Codes
200 OK –
Resources
successfully retrieved400 Bad Request – The
Target
does not support the actionresource_collection
400 Bad Request –
presqt-source-token
missing in the request headers400 Bad Request – The
search query
is not formatted correctly.401 Unauthorized –
Token
is invalid404 Not Found – Invalid
Target
name
Resource Detail¶
-
GET
/api_v1/targets/(str: target_name)/resources/(str: resource_id).json/
¶ Retrieve details of a
Resource
in JSON formatExample request:
GET /api_v1/targets/OSF/resources/1234.json/ HTTP/1.1 Host: presqt-prod.crc.nd.edu Accept: application/json
Example response:
HTTP/1.1 200 OK Content-Type: application/json { "kind": "container", "kind_name": "project", "id": "cmn5z", "title": "Test Project", "date_created": "2019-05-13T15:06:34.521000Z", "date_modified": "2019-05-13T15:06:34.521000Z", "hashes": { "md5": null, "sha256": null }, "extra": { "last_touched": "2019-11-07T17:00:51.680957", "materialized_path": "/Test Project", "current_version": 1, "provider": "googledrive", "path": "/Test Project", "current_user_can_comment": true, "guid": "byz93", "checkout": null, "tags": [], "size": null }, "children": [ { "kind": "container", "kind_name": "storage", "id": "cmn5z:osfstorage", "container": "cmn5z", "title": "osfstorage", "links": [ { "name": "Detail", "link": "https://presqt-prod.crc.nd.edu/api_v1/targets/osf/resources/cmn5z:osfstorage/", "method": "GET" } ] }, { "kind": "container", "kind_name": "folder", "id": "5cd9832cf244ec0021e5f245", "container": "cmn5z:osfstorage", "title": "Images", "links": [ { "name": "Detail", "link": "https://presqt-prod.crc.nd.edu/api_v1/targets/osf/resources/5cd9832cf244ec0021e5f245/", "method": "GET" } ] }, { "kind": "item", "kind_name": "file", "id": "5cd98510f244ec001fe5632f", "container": "5cd9832cf244ec0021e5f245", "title": "22776439564_7edbed7e10_o.jpg", "links": [ { "name": "Detail", "link": "https://presqt-prod.crc.nd.edu/api_v1/targets/osf/resources/5cd98510f244ec001fe5632f/", "method": "GET" } ] } ], "links": [ { "name": "Download", "link": "https://presqt-prod.crc.nd.edu/api_v1/targets/osf/resources/cmn5z.zip/", "method": "GET" }, { "name": "Upload", "link": "https://presqt-prod.crc.nd.edu/api_v1/targets/osf/resources/cmn5z/", "method": "POST" }, { "name": "Transfer", "link": "https://presqt-prod.crc.nd.edu/api_v1/targets/osf/resources/cmn5z/", "method": "POST" } ], "actions": [ "Transfer" ] }
- Request Headers
presqt-source-token – User’s token for the source target
- Status Codes
200 OK –
Resource
successfully retrieved400 Bad Request – The
Target
does not support the actionresource_detail
400 Bad Request –
presqt-source-token
missing in the request headers400 Bad Request – Invalid format given. Must be
json
401 Unauthorized –
Token
is invalid403 Forbidden – User does not have access to this
Resource
404 Not Found – Invalid
Target
name404 Not Found –
Resource
with thisID
not found for this user410 Gone –
Resource
no longer available
Resource Download Endpoints¶
Download Resource¶
-
GET
/api_v1/targets/(str: target_name)/resources/(str: resource_id).zip/
¶ Retrieve a Resource as a ZIP file. This endpoint begins the download process but does not return the zip file. Rather, it returns a link which can be used to the hit the
Job Status
endpoint to check in on the process.Example request:
GET /api_v1/targets/OSF/resources/1234.zip/ HTTP/1.1 Host: presqt-prod.crc.nd.edu Accept: application/json
Example response:
HTTP/1.1 202 Accepted Content-Type: application/json { "message": "The server is processing the request.", "download_job_zip": "https://presqt-prod.crc.nd.edu/api_v1/job_status/download.zip/", "download_job_json": "https://presqt-prod.crc.nd.edu/api_v1/job_status/download.json/" }
- Request Headers
presqt-source-token – User’s token for the source target
- Status Codes
202 Accepted –
Resource
has begun downloading400 Bad Request – The
Target
does not support the actionresource_download
400 Bad Request – User currently has processes in progress.
400 Bad Request –
presqt-source-token
missing in the request headers400 Bad Request –
presqt-email-opt-in
missing in the request headers400 Bad Request – Invalid format given. Must be
zip
404 Not Found – Invalid
Target
name
Resource Download Job Status¶
-
GET
/api_v1/job_status/download.json/
¶ Use the
Job Status
endpoint to check in on theDownload Process
. Provide thepresqt-source-token
in the headers.Example request
GET /api_v1/job_status/download/ HTTP/1.1 Host: presqt-prod.crc.nd.edu Accept: application/json
Example response if the download request is still in progress:
HTTP/1.1 202 Accepted Content-Type: application/json { "job_percentage": 27, "status": "in_progress", "status_code": null, "message": "Downloading files from OSF..." }
Example response if the download request finished successfully:
HTTP/1.1 200 OK Content-Type: application/json { "status_code": "200", "message": "Download successful. See PRESQT_FTS_METADATA.json for more details.", "zip_name": "osf_download_cmn5z.zip", "failed_fixity": [ "/Test Project/googledrive/PresQT Swimlane Activity Diagram 03_21_19 (2).pdf", "/Test Project/googledrive/module_responses.csv", "/Test Project/googledrive/Google Images/IMG_4740.jpg", "/Test Project/googledrive/Character Sheet - Alternative - Print Version.pdf" ], "job_percentage": 100, "status": "finished" }
Example response if the download failed:
HTTP/1.1 500 Internal Server Error Content-Type: application/json { "job_percentage": 0, "status": "failed", "status_code": 404, "message": "Resource with id 'bad_id' not found for this user." }
- Request Headers
presqt-source-token – User’s
Token
for the source target
- Status Codes
200 OK –
Download
has finished successfully202 Accepted –
Download
is being processed on the server400 Bad Request –
presqt-source-token
missing in the request headers400 Bad Request – Invalid format given. Must be json or zip.
404 Not Found – Invalid
Ticket Number
500 Internal Server Error –
Download
failed on the server
-
GET
/api_v1/job_status/download.zip/
¶ Check on the
Download Process
for the given user. If download has failed or is in progress this endpoint will return a JSON payload detailing this. If download has completed this endpoint will return the zip file of the resource originally requested.Example request:
GET /api_v1/job_status/download.zip/ HTTP/1.1 Host: presqt-prod.crc.nd.edu Accept: application/json
Example response if the download request is still in progress:
HTTP/1.1 202 Accepted Content-Type: application/json { "job_percentage": 27, "status": "in_progress", "status_code": null, "message": "Downloading files from OSF..." }
Example response if download finished successfully:
HTTP/1.1 200 OK Content-Type: application/zip Payload is ZIP file
Example response if the download failed:
HTTP/1.1 500 Internal Server Error Content-Type: application/json { "job_percentage": 0, "status": "failed", "status_code": 404, "message": "Resource with id 'bad_id' not found for this user." }
- Request Headers
presqt-source-token – User’s
Token
for the source target
- Status Codes
200 OK –
Download
has finished successfully202 Accepted –
Download
is being processed on the server400 Bad Request –
presqt-source-token
missing in the request headers400 Bad Request – Invalid format given. Must be json or zip.
404 Not Found – Invalid
Ticket Number
500 Internal Server Error –
Download
failed on the server
-
PATCH
/api_v1/job_status/upload/
¶ Cancel the
Download Process
for the given user.`.If the download has finished before it can be cancelled it will return the finished info from process_info.json.
If the download was successfully cancelled then it will return the cancelled info from process_info.json.
Example request:
PATCH /api_v1/job_status/download/ HTTP/1.1 Host: presqt-prod.crc.nd.edu Accept: application/json
Example response if download cancelled successfully:
HTTP/1.1 200 OK Content-Type: application/json { "status_code": "499", "message": "Download was cancelled by the user" }
Example response if download finished before endpoint was able to cancel:
HTTP/1.1 406 OK Content-Type: application/json { "status_code": "200", "message": "Download successful." }
- Request Headers
presqt-source-token – User’s
Token
for the source target
- Status Codes
200 OK –
Download
cancelled406 Not Acceptable –
Download
finished before cancellation400 Bad Request –
presqt-source-token
missing in the request headers404 Not Found – Invalid
Ticket Number
Resource Upload Endpoints¶
Upload New Top Level Resource¶
-
POST
/api_v1/targets/(str: target_name)/resources/
¶ Upload a new top level resource, for instance a Project. This endpoint begins the
Upload
process. It returns a link which can be used to the hit theJob Status
endpoint to check in on the process.Example request:
POST /api_v1/targets/OSF/resources/ HTTP/1.1 Host: presqt-prod.crc.nd.edu Accept: application/json
Example response:
HTTP/1.1 202 Accepted Content-Type: application/json { "message": "The server is processing the request.", "upload_job": "https://presqt-prod.crc.nd.edu/api_v1/job_status/upload/" }
- Request Headers
presqt-destination-token – User’s
Token
for the destination targetpresqt-file-duplicate-action – Action to be taken if a duplicate file is found (Either
update
orignore
)
- Form Parameters
presqt-file – The
Resource
toUpload
. Must be a BagIt file in ZIP format.
- Status Codes
202 Accepted –
Resource
has begun uploading400 Bad Request – The
Target
does not support the actionresource_upload
400 Bad Request –
presqt-destination-token
missing in the request headers400 Bad Request – The file,
presqt-file
, is not found in the body of the request400 Bad Request – The file provided is not a zip file
400 Bad Request – The file provided is not in BagIt format
400 Bad Request – Checksums failed to validate
400 Bad Request –
presqt-file-duplicate-action
missing in the request headers400 Bad Request –
presqt-email-opt-in
missing in the request headers400 Bad Request – Invalid
file_duplicate_action
header give. The options areignore
orupdate
400 Bad Request – Repository is not formatted correctly. Multiple directories exist at the top level
400 Bad Request – Repository is not formatted correctly. Files exist at the top level
400 Bad Request – User currently has processes in progress.
401 Unauthorized –
Token
is invalid404 Not Found – Invalid
Target
name
Upload To Existing Resource¶
-
POST
/api_v1/targets/(str: target_name)/resources/(str: resource_id)/
¶ Upload a resource to an existing container. This endpoint begins the
Upload
process. It returns a link which can be used to the hit theJob Status
endpoint to check in on the process.Example request:
POST /api_v1/targets/OSF/resources/1234/ HTTP/1.1 Host: presqt-prod.crc.nd.edu Accept: application/json
Example response:
HTTP/1.1 202 Accepted Content-Type: application/json { "message": "The server is processing the request.", "upload_job": "https://presqt-prod.crc.nd.edu/api_v1/job_status/upload/" }
- Request Headers
presqt-destination-token – User’s
Token
for the destination targetpresqt-file-duplicate-action – Action to be taken if a duplicate file is found (Either
update
orignore
)
- Form Parameters
presqt-file – The
Resource
toUpload
. Must be a BagIt file in ZIP format.
- Status Codes
202 Accepted –
Resource
has begun uploading400 Bad Request – The
Target
does not support the actionresource_upload
400 Bad Request –
presqt-destination-token
missing in the request headers400 Bad Request –
presqt-email-opt-in
missing in the request headers400 Bad Request – The file,
presqt-file
, is not found in the body of the request400 Bad Request – The file provided is not a zip file
400 Bad Request – The file provided is not in BagIt format
400 Bad Request – Checksums failed to validate
400 Bad Request –
presqt-file-duplicate-action
missing in the request headers400 Bad Request – Invalid
file_duplicate_action
header give. The options areignore
orupdate
400 Bad Request – User currently has processes in progress.
401 Unauthorized –
Token
is invalid403 Forbidden – User does not have access to this
Resource
404 Not Found – Invalid
Target
name410 Gone –
Resource
no longer available
Resource Upload Job Status¶
-
GET
/api_v1/job_status/upload/
¶ Check on the
Upload Process
for the given user.Example request:
GET /api_v1/job_status/upload/ HTTP/1.1 Host: presqt-prod.crc.nd.edu Accept: application/json
Example response if the upload is in progress:
HTTP/1.1 200 OK Content-Type: application/json { "status_code": null, "message": "Uploading files to OSF...", "status": "in_progress", "job_percentage": 0 }
Example response if upload finished successfully:
HTTP/1.1 200 OK Content-Type: application/json { "status_code": "200", "message": "Upload successful.", "status": "finished", "failed_fixity": [], "resources_ignored": [], "resources_updated": [], "job_percentage": 99 }
Example response if upload failed:
HTTP/1.1 500 Internal Server Error Content-Type: application/json { "job_percentage": 0, "status": "failed", "status_code": 404, "message": "Resource with id 'bad_id' not found for this user." }
- Request Headers
presqt-destination-token – User’s
Token
for the destination target
- Status Codes
200 OK –
Upload
has finished successfully202 Accepted –
Upload
is being processed on the server400 Bad Request –
presqt-destination-token
missing in the request headers404 Not Found – Invalid
Ticket Number
500 Internal Server Error –
Upload
failed on the server
-
PATCH
/api_v1/job_status/upload/
¶ Cancel the
Upload Process
for the given user. If the upload has finished before it can be cancelled it will return the finished info from process_info.json. If the upload was successfully cancelled then it will return the cancelled info from process_info.json.Example request:
PATCH /api_v1/job_status/upload/ HTTP/1.1 Host: presqt-prod.crc.nd.edu Accept: application/json
Example response if upload cancelled successfully:
HTTP/1.1 200 OK Content-Type: application/json { "status_code": "499", "message": "Upload was cancelled by the user" }
Example response if upload finished before endpoint was able to cancel:
HTTP/1.1 406 OK Content-Type: application/json { "status_code": "200", "message": "Upload successful." }
- Request Headers
presqt-destination-token – User’s
Token
for the destination target
- Status Codes
200 OK –
Upload
cancelled406 Not Acceptable –
Upload
finished before cancellation400 Bad Request –
presqt-destination-token
missing in the request headers404 Not Found – Invalid
Ticket Number
Resource Transfer Endpoints¶
Note
The Upload and Transfer endpoints are the same POST endpoints except the specification of where the source resource is coming from.
For Uploads
the resource will be a file provided as form-data
For Transfers
the location of resource (source_target and resource_id) will be specified in the body as JSON
Transfer New Top Level Resource¶
-
POST
/api_v1/targets/(str: target_name)/resources/
¶ Transfer a resource from a source target to a destination target. Make the resource a new top level resource, for instance a Project. This endpoint begins the
Transfer
process. It returns a link which can be used to the hit theJob Status
endpoint to check in on the process.Example request:
POST /api_v1/targets/OSF/resources/ HTTP/1.1 Host: presqt-prod.crc.nd.edu Accept: application/json Example body json: { "source_target_name":"github", "source_resource_id": "209372336", "keywords": ["keywords", "to", "add"] }
Example response:
HTTP/1.1 202 Accepted Content-Type: application/json { "message": "The server is processing the request.", "transfer_job": "https://presqt-prod.crc.nd.edu/api_v1/job_status/transfer/" }
- Request Headers
presqt-destination-token – User’s
Token
for the destination targetpresqt-source-token – User’s
Token
for the source targetpresqt-file-duplicate-action – Action to be taken if a duplicate file is found (Either
update
orignore
)presqt-keyword-action – Type of keyword action to perform (Either
automatic
,manual
ornone
)
- JSON Parameters
source_target_name (string) – The
Source Target
where theResource
beingTransferred
existssource_resource_id (string) – The ID of the
Resource
toTransfer
- Status Codes
202 Accepted –
Resource
has begun transferring400 Bad Request – The
Source Target
does not support the actionresource_transfer_out
400 Bad Request – The
Destination Target
does not support the actionresource_transfer_in
400 Bad Request –
presqt-source-token
missing in the request headers400 Bad Request –
presqt-destination-token
missing in the request headers400 Bad Request –
presqt-file-duplicate-action
missing in the request headers400 Bad Request –
presqt-email-opt-in
missing in the request headers400 Bad Request – Invalid
file-duplicate-action
header give. The options areignore
orupdate
400 Bad Request –
source_resource_id
can’t be none or blank400 Bad Request –
source_resource_id
was not found in the request body400 Bad Request –
source_target_name
was not found in the request body400 Bad Request –
keywords
was not found in the request body.400 Bad Request –
keywords
must be in list format.400 Bad Request – Source target does not allow transfer to the destination target
400 Bad Request – Destination target does not allow transfer to the source target
400 Bad Request – Invalid
presqt-keyword-action
header given. The options areautomatic
,manual
, ornone
400 Bad Request –
presqt-keyword-action
missing in the request headers400 Bad Request – User currently has processes in progress.
401 Unauthorized –
Source Token
is invalid401 Unauthorized –
Destination Token
is invalid403 Forbidden – User does not have access to the
Resource
to transfer404 Not Found – Invalid
Source Target
name404 Not Found – Invalid
Destination Target
name410 Gone –
Resource
to transfer is no longer available
Transfer To Existing Resource¶
-
POST
/api_v1/targets/(str: target_name)/resources/(str: resource_id)/
¶ Transfer a resource from a source target to a destination target. Transfer to an existing resource. This endpoint begins the
Transfer
process. It returns a link which can be used to the hit theJob Status
endpoint to check in on the process.Example request:
POST /api_v1/targets/OSF/resources/1234/ HTTP/1.1 Host: presqt-prod.crc.nd.edu Accept: application/json Example body json: { "source_target_name":"github", "source_resource_id": "209372336", "keywords": ["keywords", "to", "add"] }
Example response:
HTTP/1.1 202 Accepted Content-Type: application/json { "message": "The server is processing the request.", "transfer_job": "https://presqt-prod.crc.nd.edu/api_v1/job_status/transfer/" }
- Request Headers
presqt-destination-token – User’s
Token
for the destination targetpresqt-source-token – User’s
Token
for the source targetpresqt-file-duplicate-action – Action to be taken if a duplicate file is found (Either
update
orignore
)presqt-keyword-action – Type of keyword action to perform (Either
automatic
,manual
, ornone
)
- JSON Parameters
source_target_name (string) – The
Source Target
where theResource
beingTransferred
existssource_resource_id (string) – The ID of the
Resource
toTransfer
- Status Codes
202 Accepted –
Resource
has begun transferring400 Bad Request – The
Source Target
does not support the actionresource_transfer_out
400 Bad Request – The
Destination Target
does not support the actionresource_transfer_in
400 Bad Request –
presqt-source-token
missing in the request headers400 Bad Request –
presqt-destination-token
missing in the request headers400 Bad Request –
presqt-file-duplicate-action
missing in the request headers400 Bad Request –
presqt-email-opt-in
missing in the request headers400 Bad Request – Invalid
file_duplicate_action
header give. The options areignore
orupdate
400 Bad Request –
source_resource_id
can’t be none or blank400 Bad Request –
source_resource_id
was not found in the request body400 Bad Request –
source_target_name
was not found in the request body400 Bad Request –
keywords
was not found in the request body.400 Bad Request –
keywords
must be in list format.400 Bad Request – Source target does not allow transfer to the destination target
400 Bad Request – Destination target does not allow transfer to the source target
400 Bad Request – Invalid
presqt-keyword-action
header given. The options areautomatic
,manual
ornone
400 Bad Request –
presqt-keyword-action
missing in the request headers400 Bad Request – User currently has processes in progress.
401 Unauthorized –
Source Token
is invalid401 Unauthorized –
Destination Token
is invalid403 Forbidden – User does not have access to the
Resource
to transfer403 Forbidden – User does not have access to the
Resource
to transfer to404 Not Found – Invalid
Source Target
name404 Not Found – Invalid
Destination Target
name410 Gone –
Resource
to transfer is no longer available410 Gone –
Resource
to transfer to is longer available
Resource Transfer Job Status¶
-
GET
/api_v1/job_status/transfer/
¶ Check on the
Transfer Process
for the given user.Example request:
GET /api_v1/job_status/transfer/ HTTP/1.1 Host: presqt-prod.crc.nd.edu Accept: application/json
Example response if transfer is in progress:
HTTP/1.1 202 Accepted Content-Type: application/json { "status_code": null, "message": "Creating PRESQT_FTS_METADATA...", "job_percentage": 50 }
Example response if transfer finished successfully:
HTTP/1.1 200 OK Content-Type: application/json { "status_code": "200", "message": "Transfer successful.", "job_percentage": 99, "failed_fixity": [ "/PrivateProject/README.md" ], "resources_ignored": [], "resources_updated": [], "enhanced_keywords": [ "EGG", "DISORDERED SOLVENT", "Electrostatic Gravity Gradiometer", "animal house", "aqua", "Wasser", ], "initial_keywords": [ "animals", "eggs", "water" ], "source_resource_id": "209372336", "destination_resource_id": "qadt3" }
Example response if transfer failed:
HTTP/1.1 500 Internal Server Error Content-Type: application/json { "status_code": 404, "message": "The resource with id, 20938989898989872336, does not exist for this user.", "job_percentage": 0, "status": "failed" }
- Request Headers
presqt-destination-token – User’s
Token
for the destination targetpresqt-source-token – User’s
Token
for the source target
- Status Codes
200 OK –
Transfer
has finished successfully202 Accepted –
Transfer
is being processed on the server400 Bad Request –
presqt-destination-token
missing in the request headers400 Bad Request –
presqt-source-token
missing in the request headers404 Not Found – Invalid
Ticket Number
500 Internal Server Error –
Transfer
failed on the server
-
PATCH
/api_v1/job_status/transfer/
¶ Cancel the
Transfer Process
for the given user. If the transfer has finished before it can be cancelled it will return the finished info from process_info.json. If the transfer was successfully cancelled then it will return the cancelled info from process_info.json.Example request:
PATCH /api_v1/job_status/transfer/ HTTP/1.1 Host: presqt-prod.crc.nd.edu Accept: application/json
Example response if transfer cancelled successfully:
HTTP/1.1 200 OK Content-Type: application/json { "status_code": "499", "message": "Transfer was cancelled by the user" }
Example response if transfer finished before endpoint was able to cancel:
HTTP/1.1 406 OK Content-Type: application/json { "status_code": "200", "message": "Transfer successful." }
- Request Headers
presqt-destination-token – User’s
Token
for the destination targetpresqt-source-token – User’s
Token
for the source target
- Status Codes
200 OK –
Transfer
cancelled406 Not Acceptable –
Transfer
finished before cancellation400 Bad Request –
presqt-destination-token
missing in the request headers400 Bad Request –
presqt-source-token
missing in the request headers404 Not Found – Invalid
Ticket Number
Keyword Enhancement Endpoints¶
Get a Resource’s Keywords And Keyword Enhancements¶
-
GET
/api_v1/targets/(str: target_name)/resources/(str: resource_id)/keywords/
¶ Retrieve a resource’s keywords that are both stored in the target and in the PresQT Metadata File (if one exists). Send the keywords to a keyword enhancer. Return both the
Target Keywords
andEnhanced Keywords
in the payload.Example request:
GET /api_v1/targets/OSF/resources/1234/keywords/ HTTP/1.1 Host: presqt-prod.crc.nd.edu Accept: application/json
Example response:
HTTP/1.1 200 OK Content-Type: application/json { "keywords": [ "eggs", "animal", "water" ], "enhanced_keywords": [ "animals", "Animals", "EGG", "Electrostatic Gravity Gradiometer", "water", "Water", "DISORDERED SOLVENT", "aqua", "Wasser", "dihydrogen oxide", "OXYGEN ATOM", "oxidane", ], "all_keywords": [ "animals", "Animals", "EGG", "Electrostatic Gravity Gradiometer", "water", "Water", "DISORDERED SOLVENT", "aqua", "Wasser", "dihydrogen oxide", "OXYGEN ATOM", "oxidane", "eggs", "animal", "water" ] }
- Request Headers
presqt-source-token – User’s
Token
for the source target
- Status Codes
200 OK – Keywords successfully fetched
400 Bad Request – The
Source Target
does not support the actionkeywords
400 Bad Request – The
resource type
does not supportkeywords
401 Unauthorized –
Source Token
is invalid
Upload Keywords to a Resource¶
-
POST
/api_v1/targets/(str: target_name)/resources/(str: resource_id)/keywords/
¶ Take a list of keywords and add them to the Resource’s keywords both in the target and in the PresQT FTS Metadata file. The returned payload will contain both the new keywords added and the final full list of keywords in the target.
Example request:
POST /api_v1/targets/OSF/resources/1234/keywords/ HTTP/1.1 Host: presqt-prod.crc.nd.edu Accept: application/json Example body json: { "keywords": ["cat", "water"] }
Example response:
HTTP/1.1 202 Accepted Content-Type: application/json { "keywords_added": [ "feline", "aqua", "dihydrogen oxide", "DISORDERED SOLVENT", "EGG", "Electrostatic Gravity Gradiometer", "oxidane", "OXYGEN ATOM", "Wasser", "Water" ], "final_keywords": [ "feline", "aqua", "dihydrogen oxide", "DISORDERED SOLVENT", "EGG", "eggs", "Electrostatic Gravity Gradiometer", "oxidane", "OXYGEN ATOM", "Wasser", "water", "Water" ] }
- Request Headers
presqt-source-token – User’s
Token
for the source target
- JSON Parameters
keywords (array) – An array of the
keywords
to upload
- Status Codes
202 Accepted –
Keywords successfully uploaded
400 Bad Request – The
Source Target
does not support the actionkeywords
400 Bad Request – The
Source Target
does not support the actionkeywords_upload
400 Bad Request – The
resource type
does not supportkeywords
400 Bad Request –
keywords
is missing from the request body400 Bad Request –
keywords
must be in list format401 Unauthorized –
Source Token
is invalid