This module is available to use in your EdgeWorkers code bundles to export the httpRequest() function.

HTTP sub-requests

EdgeWorkers supports HTTP requests made from within an event handler. These HTTP sub-requests provide a logical way to fetch resources asynchronously across the network. If you want your callback to wait for the sub-request to complete, the event handlers should return a Promise or be declared async.

📘

Caching features set within the delivery product also apply to the associated sub-request hostnames.

Any caching features defined for the delivery product apply to both standard URLs and sub-requests.

To use sub-requests you need an associated delivery product. Hostnames can only be requested directly when served through the Akamai network. If you don't have an associated delivery product sub-requests will fail with a 400 HTTP response code. If your content is not yet available through the Akamai platform, refer to the Property Manager guide for instructions on how to Create a new property.

See the Limitations section for more information about the supported delivery products and the event handler timeouts.

👍

For information about re-using request and response headers, refer to the FAQ in this guide.

Debugging sub-requests

Extra trace information is available for debugging sub-requests. It exposes information including the sub-request status code, request timing, and rate limiting.

You can enable the enhanced sub-request trace by adding debug pragmas to your request.

httpRequest()

Exports a function from a built-in module called http-request.

httpRequest() returns a Promise that resolves to an httpResponse Object. This function is similar to fetch from the Fetch API.

When a httpRequest() timeout occurs, a JavaScript error() Object is thrown.

These restrictions apply when using the httpRequest function:

• Requests made through the httpRequest() function will only trigger subWorker enabled EdgeWorkers attached to the requested resource.
• EdgeWorkers sub-requests only support HTTPS. If you specify another protocol in the sub-request the EdgeWorkers function will automatically convert it to HTTPS.
• You cannot specify a port number.
• Sub-requests may specify the GET, HEAD, POST, PUT, DELETE and OPTIONS verbs.
• Hostnames created using automated slot matching are not supported.
• To prevent intermittent data corruption errors that are hard to debug you shoudn't pass sub-request headers back in the response. For more information, review the FAQ in the EdgeWorkers JavaScript code section.

📘

For more information you can also review the Limitations that apply to sub-requests.

To view debugging information for HTTP sub-requests you need to Enable enhanced debug headers. For more information review the Enhanced debug header details for HTTP sub-requests section.

Parameters

httpRequest(url [,options])

httpRequest('https://[akamai served domain]')

The options must be a JavaScript object containing at least one of the optional properties.

const options = {}
 
options.method = "POST"
options.headers = { "Content-Type": "application/x-www-form-urlencoded" }
options.body = "field1=value1&field2=value2"
 
const response = await httpRequest(url, options)

const response = await httpRequest(url, {
   method: "POST",
   headers: { "Content-Type": "application/x-www-form-urlencoded" },
   body: "field1=value1&field2=value2"
})

const options = {}
options.method = "GET"
options.timeout = 100

const response = await httpRequest(url, options)

const response = await httpRequest(url, {
   method: "GET",
   timeout: 100
})

This example shows how to use ReadableStream as the body type when making a request.

const options = {}

const requestBody = new ReadableStream({
    start(controller) {
        controller.enqueue('hello ');
        controller.enqueue('world');
        controller.close();
    }
});

options.method = "POST"
options.headers = {
    "Content-Type": "application/x-www-form-urlencoded"
}
options.body = requestBody.pipeThrough(new TextEncoderStream())

const response = await httpRequest(url, options)

This example shows the response when you use ReadableStream as the body type.

const response = await httpRequest(url, {
    method: "POST",
    headers: {
        "Content-Type": "application/x-www-form-urlencoded"
    },
    body: new ReadableStream({
        start(controller) {
            controller.enqueue('hello ');
            controller.enqueue('world');
            controller.close();
        }
    })
})

This example shows how to use an asynchronous encapsulating function to call an httpRequest() function.

async function getJSON (url) {
  const response = await httpRequest(`${url}`);
  if (response.ok) {
	return await response.json();
  } else {
	return { language: 'en', greeting: 'Hello World' };
  }
}

This example shows how to use the onClientRequest event handler to call an httpRequest() function. It is also async.

import { httpRequest } from 'http-request';
import { logger } from 'log';
export async function onClientRequest(request) {
  try {
    const response = await httpRequest('/ab_test/ab.json');
    logger.log('OnClientRequest SubRequest Successful');
      if (response.ok) {
       // Add logic process response 
      }
  } catch (error) {
    logger.log('OnClientRequest SubRequest Failed: %s', error);
  }
}

httpResponse Object

The httpResponse Object defines the details of the response for the httpRequest.

Properties

body

This is the stream used to read the content body. This is a read-only ReadableStream.

export function responseProvider (request) {
 return httpRequest(`https://${request.host}${request.url}`).then(response => {
   return createResponse(

ok

This is true for 2XX response headers. This is a read-only boolean value.

const response = await httpRequest(subrequestURL);
      if (response.ok) {
...
        } else {
        ...
      }

status

The HTTP statuscode. This is a read-only integer.

// HTTP/1.1 200
  response.status;
// => 200

Methods

The following methods are available for the EdgeWorkers httpResponse objects.

getHeader()

Provides header values by header name using the same signature as the getHeader() function on callback request objects. If the header exists, returns an array of strings that lists the values of the headers.
Returns undefined if the header does not exist.

Parameters

getHeader(name)

Review the table for information about the available parameters.

response.getHeader('Content-Type')

getHeaders()

Returns an object with its own properties corresponding to the response headers.

The key is the header name normalized to lowercase and the value is an array of strings containing one string for each HTTP header with the same name. The object is mutable, but independent of the response object - meaning changes won't be reflected by response.getHeader(). The header properties are in the order that they were received by the Akamai edge servers. When you iterate across the object properties you will get the headers in the order that the browser sent them.

getHeaders() is only supported where httpRequest() is allowed.

import { httpRequest } from 'http-request';
export async function onClientRequest(request) {
    let response = await httpRequest('/example');
    request.respondWith(response.status, response.getHeaders(), "OK" );

json()

Returns a Promise that resolves to the parsed JSON response.

The response size is limited to 128 KB.

let fromOrigin = httpRequest('/endpoint.json');
let json = await fromOrigin.json();

📘

The response is buffered not streamed.

text()

Reads the body to completion and returns a Promise that resolves to a String containing the full body.

The response size is limited to 128 KB.

let fromOrigin = httpRequest('/endpoint.json');
let bodytext = await fromOrigin.text();

📘

The response is buffered not streamed.

httpResponse Headers Object

The httpResponse Headers Object provides header values by header name for the httpRequest response.

get()

This function has the same signature as the Fetch API's Header.get method.

Parameters

get(name)