Upload Data

This document contains documentation for the web services for uploading data to spectr.

Uploading a scan file to spectr us a multi-step affair. The steps are:

  1. Initiate upload of scan file with /update/uploadScanFile_Init_XML

  2. Use the returned key to send data to spectr. Use /update/uploadScanFile_uploadScanFile_XML to send data from a local file or /update/uploadScanFile_addScanFileInS3Bucket_XML to send data from S3.

  3. Commit the submission for processing with /update/uploadScanFile_Submit_XML

  4. Use the returned key from 3 to query status and retrieve final hash key for uploaded file with /update/uploadedScanFile_Status_API_Key_XML.

Web Services Details:

Initiate upload of scan file

URI

/update/uploadScanFile_Init_XML

Method

POST

URL Params (GET)

None

POST data

 
<uploadScanFile_Init_Request></uploadScanFile_Init_Request>

Success Response

Success (200 OK)

Error Response

Unauthorized (401)

Sample Response

 
<uploadScanFile_Init_Response>
  <statusSuccess>true</statusSuccess>
  <uploadScanFileTempKey>aekd838dkd</uploadScanFileTempKey>
  <maxUploadFileSize>10000000000</maxUploadFileSize>
  <maxUploadFileSizeFormatted>10,000,000,000</maxUploadFileSizeFormatted>
</uploadScanFile_Init_Response>

Response Elements

  • <statusSuccess> - contains “true” or “false”

  • <uploadScanFileTempKey> - String, identifier to use when submitting new file

  • <maxUploadFileSize> - Integer, maximum allowed upload scan file size in bytes

  • <maxUploadFileSizeFormatted> - String, number above, but with commas

Submit Data from Scan File

Send the contents of a scan file, byte for byte.

URI

/update/uploadScanFile_uploadScanFile_XML

Method

POST

URL Params (GET)

  • uploadScanFileTempKey - Value returned in <uploadScanFileTempKey> from call to /update/uploadScanFile_Init_XML

  • scan_filename_suffix - (Optional) The suffix of the scan filename - Allowed values are “.mzML” and “.mzXML”

POST data

  • POST headers: Content Length must be set

  • POST body is the scan file contents. Chunked data is not allowed

Success Response

Success (200 OK)

Error Response

Bad Request (400), Unauthorized (401)

Sample Response

 
<UploadScanFile_UploadScanFile_Response>
   <statusSuccess>true</statusSuccess>
   <uploadScanFileTempKey_NotFound>false</uploadScanFileTempKey_NotFound>
   <uploadedFileHasNoFilename>false</uploadedFileHasNoFilename>
   <uploadedFileSuffixNotValid>false</uploadedFileSuffixNotValid>
</UploadScanFile_UploadScanFile_Response>

Response Elements

  • statusSuccess - true if successful, false if not

  • uploadScanFileTempKey_NotFound - Scan file temp key was not valid

  • objectKeyOrFilenameSuffixNotValid - Could not determine data file was a valid type (mzML or mzXML)

  • uploadedFileHasNoFilename - Uploaded file has no file name

  • fileSizeLimitExceeded - (Optional) true if file size limit was exceeded

  • maxSize - (Optional) Integer, maximum allowed upload scan file size in bytes

  • maxSizeFormatted - (Optional) Number above, but with commas

Add Scan file in S3 Bucket

Submit a file to spectr, if that file is already on Amazon S3 and spectr has read access to that object. Prevents needlessly sending file.

URI

/update/uploadScanFile_addScanFileInS3Bucket_XML

Method

POST

URL Params (GET)

None

POST data

 
<uploadScanFile_AddScanFileInS3Bucket_Request
    uploadScanFileTempKey=""
    s3Bucket=""
    s3ObjectKey=""
    scanFilenameSuffix=""
    s3Region=""
 />

Post attributes

  • uploadScanFileTempKey - Value returned in <uploadScanFileTempKey> from call to /update/uploadScanFile_Init_XML

  • s3Bucket - S3 bucket name

  • s3ObjectKey - S3 object key

  • scanFilenameSuffix - (Optional) Suffix of scan file (e.g., mzML or mzXML)

  • s3Region - (Optional) AWS region of object

Success Response

Success (200 OK)

Error Response

Bad Request (400), Unauthorized (401)

Sample Response

 
<uploadScanFile_AddScanFileInS3Bucket_Response
  statusSuccess="true"
  uploadScanFileTempKey_NotFound="false"
  objectKeyOrFilenameSuffixNotValid="false"
  uploadScanFileS3BucketOrObjectKey_NotFound="false"
  uploadScanFileS3BucketOrObjectKey_PermissionError="false" />

Response attributes

  • statusSuccess - true if successful, false if not

  • uploadScanFileTempKey_NotFound - Scan file temp key was not valid

  • objectKeyOrFilenameSuffixNotValid - Could not determine data file was a valid type (mzML or mzXML)

  • uploadScanFileS3BucketOrObjectKey_NotFound - S3 object was not found

  • uploadScanFileS3BucketOrObjectKey_PermissionError - No permissions to read S3 object

  • fileSizeLimitExceeded - (Optional) true if file size limit was exceeded

  • maxSize - (Optional) Integer, maximum allowed upload scan file size in bytes

  • maxSizeFormatted - (Optional) Number above, but with commas

Commit the upload of a scan file

After the scan data have been sent (or a S3 object designated), this must be called to complete processing of the file

URI

/update/uploadScanFile_Submit_XML

Method

POST

URL Params (GET)

None

POST data

 
<uploadScanFile_Submit_Request
   uploadScanFileTempKey=""
/>

Post attributes

  • uploadScanFileTempKey - Value returned in <uploadScanFileTempKey> from call to /update/uploadScanFile_Init_XML

Success Response

Success (200 OK)

Error Response

Bad Request (400), Unauthorized (401)

Sample Response

 
<uploadScanFile_Submit_Response
  statusSuccess="true"
  uploadScanFileTempKey_NotFound="false"
  noUploadedScanFile="false"
  scanProcessStatusKey="dkdk39dkd93kdkd"
/>

Response attributes

  • statusSuccess - true if successful, false if not

  • uploadScanFileTempKey_NotFound - Scan file temp key was not valid

  • noUploadedScanFile - Commit called without submitting scan file first

  • scanProcessStatusKey - Key to use to query the status of processing and obtain final key

Get the final key (API key)

Get the final key for the uploaded scan file (used to query data from file later).

URI

/update/uploadedScanFile_Status_API_Key_XML

Method

POST

URL Params (GET)

None

POST data

 
<get_UploadedScanFileInfo_Request
   scanProcessStatusKey=""
/>

Post attributes

  • scanProcessStatusKey - Key to use to query the status of processing and obtain final key

Success Response

Success (200 OK)

Error Response

Bad Request (400), Unauthorized (401)

Sample Response

 
<get_UploadedScanFileInfo_Response
  scanFileAPIKey="98c11ffdfdd540676b1a137cb1a22b2a70350c9a44171d6b1180c6be5cbb2ee3f79d532c8a1dd9ef2e8e08e752a3babb"
  scanProcessStatusKey_NotFound="false"
  status="success"
  failMessage=""
/>

Response attributes

  • scanFileAPIKey - Final hash key used to query scan data from this file (only here if processing is complete)

  • scanProcessStatusKey_NotFound - Invalid scan processing status key

  • status - “pending”, “success”, “fail”, or “deleted”

  • failMessage - If failed, a message describing the reason for failure

Delete scan processing key

Mark a scan processing key as deleted. Ensures not accidentally used again. Note that these keys do age and are automatically deleted with time.

URI

/update/uploadedScanFile_Delete_For_ScanProcessStatusKey_XML

Method

POST

URL Params (GET)

None

POST data

 
<get_UploadedScanFileInfo_Request
   scanProcessStatusKey=""
/>

Post attributes

  • scanProcessStatusKey - Key to use to query the status of processing and obtain final key

Success Response

Success (200 OK)

Error Response

Bad Request (400), Unauthorized (401)

Sample Response

 
<uploadScanFile_Delete_For_ScanProcessStatusKey_Request
  scanProcessStatusKey_NotFound="false"
  statusSuccess="true"
/>

Response attributes

  • statusSuccess - Whether or not the request was successfull. “true” or “false”

  • scanProcessStatusKey_NotFound - Invalid scan processing status key