Akamai NetStorage HTTP API for Node.js

Common errors

• Error: Akamai API Error. Status: 409 Conflict

  cause Attempting to create a directory (`mkdir`) or symlink (`symlink`) where a file or directory with the same name already exists at the target path.
  fix Implement checks (e.g., using `fileExists` or `stat`) before creating resources, or specifically handle the `err.code === 409` condition in your error callback.

• Error: read ECONNRESET

  cause A network connection reset occurred. This can happen due to an unstable network, Akamai rate limiting abruptly closing the connection, or an incorrect host configuration causing the server to reject the connection.
  fix Verify your network stability, ensure the `host` is correctly configured, and check Akamai's rate limit guidance. Consider implementing retry logic with back-off.

• Error: ETIMEDOUT (or similar timeout error)

  cause The HTTP request to Akamai NetStorage exceeded the configured `request.timeout` value before receiving a response. This could be due to network latency, large file transfers, or an unreachable host.
  fix Check network connectivity and the correctness of the configured `host`. For large files, consider increasing the `request.timeout` value in `setConfig`.

Warnings

• breaking The core HTTP client library, 'request', which `akamai-http-api` depends on, is officially deprecated and no longer maintained. While this package updates its dependencies, continued reliance on 'request' could lead to future compatibility issues or unpatched security vulnerabilities in the underlying HTTP layer.
  Fix: Be aware of this underlying dependency risk. Monitor 'akamai-http-api' for potential migrations to a modern HTTP client, or consider alternatives if 'request' becomes a critical blocker for your security or compliance needs.
• gotcha Multiple security vulnerabilities in the 'lodash' dependency have been patched. To ensure your application is secure, it is critical to use `akamai-http-api` version `0.6.1` or higher.
  Fix: Upgrade to `akamai-http-api@0.6.1` or newer. Regularly run `npm audit` to identify and mitigate any new security advisories.
• gotcha Akamai NetStorage has a soft rate limit of approximately 15 operations per second. Exceeding this limit can result in 500 series HTTP errors being returned by NetStorage, which are not automatically retried or handled by this client.
  Fix: Implement client-side rate limiting, exponential back-off, or queueing mechanisms if your application performs a high volume of NetStorage operations.
• gotcha Providing an incorrect `host` value in `setConfig` (e.g., a typo) will not immediately throw an error but will cause HTTP requests to hang until the connection timeout is reached (default 20 seconds).
  Fix: Double-check the `host` value against your Akamai NetStorage configuration. Utilize the `request.timeout` option within `setConfig` to adjust the timeout duration if needed.
• deprecated The configuration for HTTP request timeouts was introduced and later standardized under a nested `request` object. Direct top-level `timeout` options might be ignored or behave inconsistently in newer versions.
  Fix: Always configure HTTP request timeouts using `akamai.setConfig({ request: { timeout: milliseconds } })`.

Install

• npm install akamai-http-api npm
• yarn add akamai-http-api yarn
• pnpm add akamai-http-api pnpm

Imports

• akamai
  wrong:

  const akamai = require('akamai-http-api');

  correct:

  import akamai from 'akamai-http-api';

  The library exports a single object containing all API methods. While the package documentation primarily uses CommonJS `require`, it can be imported as a default export in ESM environments.
• setConfig

  akamai.setConfig({ /* config */ });

  Configuration is applied globally via a method on the imported `akamai` object and must be called before performing any API operations.
• upload

  akamai.upload(stream, '/path/to/remote', callback);

  This is one of the 'Advanced' API methods for stream-based file uploads. Other methods like `download`, `dir`, `delete` are also accessed directly from the `akamai` object.

Quickstart

This quickstart demonstrates how to initialize the `akamai-http-api` client using configuration from environment variables and then perform a basic file upload to Akamai NetStorage via a readable stream. It includes local file creation and cleanup.

const akamai = require('akamai-http-api');
const fs = require('fs');
const path = require('path');

// Ensure these environment variables are set or provide direct values
akamai.setConfig({
  keyName: process.env.AKAMAI_KEY_NAME ?? 'your-akamai-keyname',
  key: process.env.AKAMAI_KEY ?? 'your-akamai-secret-key-long-string',
  host: process.env.AKAMAI_HOST ?? 'your-netstorage-hostname.akamaihd.net',
  ssl: true, // Recommended for production
  verbose: false,
  request: {
    timeout: 30000 // 30 seconds timeout (default is 20s)
  }
});

const localTempDir = './temp_akamai_uploads';
if (!fs.existsSync(localTempDir)) {
  fs.mkdirSync(localTempDir);
}
const localFilePath = path.join(localTempDir, 'example-upload.txt');
const remoteFilePath = '/12345/MyFolder/example-upload.txt'; // Replace 12345 with your CP code

// Create a dummy file for upload
fs.writeFileSync(localFilePath, 'Hello Akamai NetStorage from node-akamai-http-api!');
console.log(`Created local file: ${localFilePath}`);

const uploadStream = fs.createReadStream(localFilePath);

akamai.upload(uploadStream, remoteFilePath, function (err, data) {
  if (err) {
    console.error('Akamai upload failed:', err.message || err);
    // Clean up even on error
    fs.unlinkSync(localFilePath);
    fs.rmdirSync(localTempDir);
    return;
  }
  console.log('Akamai upload successful:', data);

  // Clean up the dummy file and directory
  fs.unlinkSync(localFilePath);
  fs.rmdirSync(localTempDir);
  console.log(`Cleaned up local file: ${localFilePath}`);
});