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 –
Targetssuccessfully 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 –
Targetsuccessfully retrieved404 Not Found – Invalid
Targetname
Resource Endpoints¶
Resource Collection¶
-
GET/api_v1/targets/(str: target_name)/resources/¶ Retrieve details of all top level resources for a given
TargetandUser TokenExample 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 –
Resourcessuccessfully retrieved400 Bad Request – The
Targetdoes not support the actionresource_collection400 Bad Request –
presqt-source-tokenmissing in the request headers400 Bad Request – The
search queryis not formatted correctly.401 Unauthorized –
Tokenis invalid404 Not Found – Invalid
Targetname
Resource Detail¶
-
GET/api_v1/targets/(str: target_name)/resources/(str: resource_id).json/¶ Retrieve details of a
Resourcein 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 –
Resourcesuccessfully retrieved400 Bad Request – The
Targetdoes not support the actionresource_detail400 Bad Request –
presqt-source-tokenmissing in the request headers400 Bad Request – Invalid format given. Must be
json401 Unauthorized –
Tokenis invalid403 Forbidden – User does not have access to this
Resource404 Not Found – Invalid
Targetname404 Not Found –
Resourcewith thisIDnot found for this user410 Gone –
Resourceno 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 Statusendpoint 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 –
Resourcehas begun downloading400 Bad Request – The
Targetdoes not support the actionresource_download400 Bad Request – User currently has processes in progress.
400 Bad Request –
presqt-source-tokenmissing in the request headers400 Bad Request –
presqt-email-opt-inmissing in the request headers400 Bad Request – Invalid format given. Must be
zip404 Not Found – Invalid
Targetname
Resource Download Job Status¶
-
GET/api_v1/job_status/download.json/¶ Use the
Job Statusendpoint to check in on theDownload Process. Provide thepresqt-source-tokenin 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
Tokenfor the source target
- Status Codes
200 OK –
Downloadhas finished successfully202 Accepted –
Downloadis being processed on the server400 Bad Request –
presqt-source-tokenmissing in the request headers400 Bad Request – Invalid format given. Must be json or zip.
404 Not Found – Invalid
Ticket Number500 Internal Server Error –
Downloadfailed on the server
-
GET/api_v1/job_status/download.zip/¶ Check on the
Download Processfor 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
Tokenfor the source target
- Status Codes
200 OK –
Downloadhas finished successfully202 Accepted –
Downloadis being processed on the server400 Bad Request –
presqt-source-tokenmissing in the request headers400 Bad Request – Invalid format given. Must be json or zip.
404 Not Found – Invalid
Ticket Number500 Internal Server Error –
Downloadfailed on the server
-
PATCH/api_v1/job_status/upload/¶ Cancel the
Download Processfor 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
Tokenfor the source target
- Status Codes
200 OK –
Downloadcancelled406 Not Acceptable –
Downloadfinished before cancellation400 Bad Request –
presqt-source-tokenmissing 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
Uploadprocess. It returns a link which can be used to the hit theJob Statusendpoint 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
Tokenfor the destination targetpresqt-file-duplicate-action – Action to be taken if a duplicate file is found (Either
updateorignore)
- Form Parameters
presqt-file – The
ResourcetoUpload. Must be a BagIt file in ZIP format.
- Status Codes
202 Accepted –
Resourcehas begun uploading400 Bad Request – The
Targetdoes not support the actionresource_upload400 Bad Request –
presqt-destination-tokenmissing 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-actionmissing in the request headers400 Bad Request –
presqt-email-opt-inmissing in the request headers400 Bad Request – Invalid
file_duplicate_actionheader give. The options areignoreorupdate400 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 –
Tokenis invalid404 Not Found – Invalid
Targetname
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
Uploadprocess. It returns a link which can be used to the hit theJob Statusendpoint 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
Tokenfor the destination targetpresqt-file-duplicate-action – Action to be taken if a duplicate file is found (Either
updateorignore)
- Form Parameters
presqt-file – The
ResourcetoUpload. Must be a BagIt file in ZIP format.
- Status Codes
202 Accepted –
Resourcehas begun uploading400 Bad Request – The
Targetdoes not support the actionresource_upload400 Bad Request –
presqt-destination-tokenmissing in the request headers400 Bad Request –
presqt-email-opt-inmissing 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-actionmissing in the request headers400 Bad Request – Invalid
file_duplicate_actionheader give. The options areignoreorupdate400 Bad Request – User currently has processes in progress.
401 Unauthorized –
Tokenis invalid403 Forbidden – User does not have access to this
Resource404 Not Found – Invalid
Targetname410 Gone –
Resourceno longer available
Resource Upload Job Status¶
-
GET/api_v1/job_status/upload/¶ Check on the
Upload Processfor 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
Tokenfor the destination target
- Status Codes
200 OK –
Uploadhas finished successfully202 Accepted –
Uploadis being processed on the server400 Bad Request –
presqt-destination-tokenmissing in the request headers404 Not Found – Invalid
Ticket Number500 Internal Server Error –
Uploadfailed on the server
-
PATCH/api_v1/job_status/upload/¶ Cancel the
Upload Processfor 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
Tokenfor the destination target
- Status Codes
200 OK –
Uploadcancelled406 Not Acceptable –
Uploadfinished before cancellation400 Bad Request –
presqt-destination-tokenmissing 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
Transferprocess. It returns a link which can be used to the hit theJob Statusendpoint 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
Tokenfor the destination targetpresqt-source-token – User’s
Tokenfor the source targetpresqt-file-duplicate-action – Action to be taken if a duplicate file is found (Either
updateorignore)presqt-keyword-action – Type of keyword action to perform (Either
automatic,manualornone)
- JSON Parameters
source_target_name (string) – The
Source Targetwhere theResourcebeingTransferredexistssource_resource_id (string) – The ID of the
ResourcetoTransfer
- Status Codes
202 Accepted –
Resourcehas begun transferring400 Bad Request – The
Source Targetdoes not support the actionresource_transfer_out400 Bad Request – The
Destination Targetdoes not support the actionresource_transfer_in400 Bad Request –
presqt-source-tokenmissing in the request headers400 Bad Request –
presqt-destination-tokenmissing in the request headers400 Bad Request –
presqt-file-duplicate-actionmissing in the request headers400 Bad Request –
presqt-email-opt-inmissing in the request headers400 Bad Request – Invalid
file-duplicate-actionheader give. The options areignoreorupdate400 Bad Request –
source_resource_idcan’t be none or blank400 Bad Request –
source_resource_idwas not found in the request body400 Bad Request –
source_target_namewas not found in the request body400 Bad Request –
keywordswas not found in the request body.400 Bad Request –
keywordsmust 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-actionheader given. The options areautomatic,manual, ornone400 Bad Request –
presqt-keyword-actionmissing in the request headers400 Bad Request – User currently has processes in progress.
401 Unauthorized –
Source Tokenis invalid401 Unauthorized –
Destination Tokenis invalid403 Forbidden – User does not have access to the
Resourceto transfer404 Not Found – Invalid
Source Targetname404 Not Found – Invalid
Destination Targetname410 Gone –
Resourceto 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
Transferprocess. It returns a link which can be used to the hit theJob Statusendpoint 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
Tokenfor the destination targetpresqt-source-token – User’s
Tokenfor the source targetpresqt-file-duplicate-action – Action to be taken if a duplicate file is found (Either
updateorignore)presqt-keyword-action – Type of keyword action to perform (Either
automatic,manual, ornone)
- JSON Parameters
source_target_name (string) – The
Source Targetwhere theResourcebeingTransferredexistssource_resource_id (string) – The ID of the
ResourcetoTransfer
- Status Codes
202 Accepted –
Resourcehas begun transferring400 Bad Request – The
Source Targetdoes not support the actionresource_transfer_out400 Bad Request – The
Destination Targetdoes not support the actionresource_transfer_in400 Bad Request –
presqt-source-tokenmissing in the request headers400 Bad Request –
presqt-destination-tokenmissing in the request headers400 Bad Request –
presqt-file-duplicate-actionmissing in the request headers400 Bad Request –
presqt-email-opt-inmissing in the request headers400 Bad Request – Invalid
file_duplicate_actionheader give. The options areignoreorupdate400 Bad Request –
source_resource_idcan’t be none or blank400 Bad Request –
source_resource_idwas not found in the request body400 Bad Request –
source_target_namewas not found in the request body400 Bad Request –
keywordswas not found in the request body.400 Bad Request –
keywordsmust 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-actionheader given. The options areautomatic,manualornone400 Bad Request –
presqt-keyword-actionmissing in the request headers400 Bad Request – User currently has processes in progress.
401 Unauthorized –
Source Tokenis invalid401 Unauthorized –
Destination Tokenis invalid403 Forbidden – User does not have access to the
Resourceto transfer403 Forbidden – User does not have access to the
Resourceto transfer to404 Not Found – Invalid
Source Targetname404 Not Found – Invalid
Destination Targetname410 Gone –
Resourceto transfer is no longer available410 Gone –
Resourceto transfer to is longer available
Resource Transfer Job Status¶
-
GET/api_v1/job_status/transfer/¶ Check on the
Transfer Processfor 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
Tokenfor the destination targetpresqt-source-token – User’s
Tokenfor the source target
- Status Codes
200 OK –
Transferhas finished successfully202 Accepted –
Transferis being processed on the server400 Bad Request –
presqt-destination-tokenmissing in the request headers400 Bad Request –
presqt-source-tokenmissing in the request headers404 Not Found – Invalid
Ticket Number500 Internal Server Error –
Transferfailed on the server
-
PATCH/api_v1/job_status/transfer/¶ Cancel the
Transfer Processfor 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
Tokenfor the destination targetpresqt-source-token – User’s
Tokenfor the source target
- Status Codes
200 OK –
Transfercancelled406 Not Acceptable –
Transferfinished before cancellation400 Bad Request –
presqt-destination-tokenmissing in the request headers400 Bad Request –
presqt-source-tokenmissing 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 KeywordsandEnhanced Keywordsin 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
Tokenfor the source target
- Status Codes
200 OK – Keywords successfully fetched
400 Bad Request – The
Source Targetdoes not support the actionkeywords400 Bad Request – The
resource typedoes not supportkeywords401 Unauthorized –
Source Tokenis 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
Tokenfor the source target
- JSON Parameters
keywords (array) – An array of the
keywordsto upload
- Status Codes
202 Accepted –
Keywords successfully uploaded400 Bad Request – The
Source Targetdoes not support the actionkeywords400 Bad Request – The
Source Targetdoes not support the actionkeywords_upload400 Bad Request – The
resource typedoes not supportkeywords400 Bad Request –
keywordsis missing from the request body400 Bad Request –
keywordsmust be in list format401 Unauthorized –
Source Tokenis invalid