Sending a package with HTTP Gateway

Edit online

Leverage the Faspex API and the HTTP Gateway SDK to send a package to a recipient.

Before you begin

Before following the steps in this guide:

About this task

Note:
  • The code examples for the Faspex API are written with curl.
  • The code examples for the HTTP Gateway SDK are written in JavaScript.

Procedure

  1. Retrieve a bearer token from the Faspex server.
  2. Create a package in Faspex:

    Endpoint: POST https://faspex5.example.com/aspera/faspex/api/v5/packages

    Example:

    curl -X POST 'https://faspex5.example.com/aspera/faspex/api/v5/packages/' \
-H 'Content-Type: application/json' \
-H "Authorization: Bearer eyJhbGciOiJIUzI1NiJ9.eyJ1c2VyX2lkIjoyLCJleHAiOjE1OTYwMzY3NzV9.068OqoSZoTLYYMpEjYf5poK0hxVEYpktaAYx7hBKP9I"
-d '{
  "title": "Example Package 1",
  "recipients": [
    "name":"admin@ibm.com" // This example uses the authenticated user as both sender and recipient
  ]
}'

    Result:

    If successful, Faspex returns a response with the package information:
    {
  "id": "43",
  "title": "Example Package 1",
  "note": "",
  "recipients": [
    {
      "recipient_type": "user",
      "id": "256",
      "name": "admin@ibm.com",
      "first_name": "John",
      "last_name": "Doe",                                                                                                                                                                                                                                                                                                                                                       "email": "jhwan@us.ibm.com"
    }
  ],
  "release_policy": "now",
  "release_date": "2022-02-18T21:30:05.000+0000",
  "sender": "admin@ibm.com",
  "state": "held",
  "prevent_http_download": false,
  "archived": false,
  "obfuscation_enabled": false,
  "ear_enabled": null,
  "notified_on_upload": [],
  "notified_on_download": [],
  "notified_on_receipt": [],
  "active_downloads": 0,
  "active_downloaders": [],
  "download_count": 0,
  "downloaders": [],
  "total_bytes": 0,
  "total_files": 0,
  "recalculation_needed": false,
  "recalculation_in_progress": false,
  "creation_date": "2022-02-18T21:30:05.000+0000",
  "last_modified": "2022-02-18T21:30:05.000+0000",
  "package_uuid": "feedbdbc-0468-4c9d-bd49-0873171683eb",
  "expiration_policy": "none",
  "mailbox": "inbox"
}
  3. Use the HTTP Gateway SDK to retrieve the transfer specification from Faspex and send the package.
    Copy the sample code below and change the constants using the results from the previous steps.
    1. In upload.js, change:
      • FASPEX_HOSTNAME: The hostname of your Faspex server.
      • BEARER_TOKEN: The bearer token generated when you authenticated to the Faspex server.
      • PACKAGE_ID: The ID of the package you created on the Faspex server.
      • GATEWAY_HOSTNAME: The hostname of your HTTP Gateway server.
      upload.js
      /* Change these constants */
const FASPEX_HOSTNAME = "https://faspex_hostname";
const BEARER_TOKEN = "bearer_token";
const PACKAGE_ID = "package_id";
const GATEWAY_HOSTNAME = "https://http_gateway_hostname";

/* Constants used for picking files */
const formId = 'send-file';
const files = [];

/*
 * fetchTransferSpec() - Fetch a transfer specification for HTTP Gateway to use
 * to send a package.
 *
 * Required params:
 *   filepaths - array of filepaths with format:
 *     { paths: [ { source: /path/to/file } ] }
 */
async function fetchTransferSpec(filepaths) {
  // Retrieve upload transfer specification for HTTP Gateway
  const ts_url = `${FASPEX_HOSTNAME}/aspera/faspex/api/v5/packages/${PACKAGE_ID}/transfer_spec/upload?transfer_type=http_gateway`
  const ts_response= await fetch(ts_url, {
    method: "POST",
    headers: {
"Content-Type": "application/json",
"Authorization": `Bearer ${BEARER_TOKEN}`
    },
    body: JSON.stringify(filepaths)
  });
  let ts_data = await ts_response.json()

  console.log("Transfer specification", ts_data)

  // If successful, Faspex returns a transfer specification
  return ts_data
}

/*
 * filePickCallback is a callback to save the user-selected file from the
 * browser file picker and to append the filename to the HTML document
 */
function filePickCallback(data) {
  const { files } = data.dataTransfer
  const files_for_spec = [];
  for (let file of files) {
    files_for_spec.push(file);
  }
  document.querySelector("#send-file").innerHTML = files_for_spec[0].name
  this.files = files_for_spec
  console.log('Files picked', files);
};

/*
 * pickFile() opens the browser file picker and saves the user selection.
 *
 * Used in `upload.html` to trigger the browser file picker.
 *
 */
function pickFile() {
  this.files = this.client.getFilesForUpload(filePickCallback, this.formId)
};

/* monitorTransfers is a callback to print transfer progress to Console */
const monitorTransfers = (result) => {
  result.transfers.forEach(transfer => {
    console.log(
      `New Transfer:
- Percent: ${transfer.percent * 100}%,
- Status: ${transfer.status},
- Data Sent: ${transfer.bytes_written},
- Data Total: ${transfer.bytes_expected}
`
    );
  });
  console.log("Transfer completed")
}

/*
 * upload() registers the callback and uploads the picked file
 *
 * This function triggered by a button in `upload.html`
 *
 */
async function upload() {
  this.client.registerActivityCallback(monitorTransfers);
  console.log("Registered callback to monitor transfers")
  if (this.files.length === 1) {
    let fileToUpload = this.files[0].name;
    const filepaths = {
      "paths": [
        fileToUpload
      ]
    }
    fetchTransferSpec(filepaths).then(transferSpec => {
      this.client.upload(transferSpec, this.formId).then(response => {
        console.log('Upload started', response);
      }).catch(error => {
        console.log('Upload could not start', error);
      });
    })
  }
}

/*
 * initHttpGateway() initializes the HTTP Gateway client from the HTTP Gateway SDK.
 *
 * Used in `upload.html` on page load.
 */
function initHttpGateway() {
  this.client = asperaHttpGateway
  const gateway_url = `${GATEWAY_HOSTNAME}/aspera/http-gwy/v1/`
  this.client.initHttpGateway(gateway_url).then(response => {
    console.log('HTTP Gateway SDK started', response);
  }).catch(error => {
    console.warn('HTTP Gateway SDK did not start', error);
  })
}
    2. In upload.html, change the path to the HTTP Gateway Javascript SDK (find /path/to/http-gateway.js).
      upload.html
      <!DOCType HTML>
<html>
  <head>
    <title>Testing HTTP Gateway Upload</title>
    <style>
div {
  margin-left: auto;
  margin-right: auto; 
  width: 8rem;
}

button {
  width: 8rem;
}
    </style>
    <script src="/path/to/http-gateway.js"></script>

    <script type="text/javascript" src="upload.js"></script>
  </head>
  <body onload="initHttpGateway();">
    <h1 style="text-align:center;">IBM Aspera HTTP Gateway simple upload example</h1>
    <div>
      <button onclick="pickFile()">Pick a file to send</button>
    </div>
    <div>
      <p>File picked:
      <p id="send-file"></p>
    </div>
    <div>
      <button onclick="upload()">Send file</button>
    </div>
  </body>
</html>
    3. Open the HTML file, pick a file, and send.

Results

HTTP Gateway sends the package to the recipient Faspex user.