All Products
Search
Document Center

Dynamic Content Delivery Network:Fetch API

Last Updated:Mar 19, 2024

You can call the Fetch API operation to fetch data from points of presence (POPs) over HTTP or HTTPS and return the data to users. It is similar to the Fetch API in the browser environment and can be used in scenarios such as dynamic loading of content, interaction with backend services, and A/B testing.

Redirect

The Fetch API supports 3xx redirects. Fetch requests can follow 3xx redirects. HTTP 3xx status codes include 301, 302, 303, 307, and 308. You can set the redirect parameter to one of the following values based on your business requirements.

  • {redirect: "manual"}: Fetch requests do not follow 3xx redirects. You must manually handle 3xx redirects. This is the default value.

  • {redirect: "error"}: Exceptions are thrown when 3xx redirects occur.

  • {redirect: "follow"}: Fetch requests follow 3xx redirects. The maximum number of 3xx redirects supported by the Fetch API is 20.

The following table describes the 3xx status codes.

HTTP status code

Redirect description

301, 302, 303, and 308

The request method is changed to GET, and the body is ignored.

307

Fetch requests follow the redirect only if the request method is GET. If the request method is not GET, an exception is thrown.

Note

The URL to which a request is redirected is contained in the Location header. If the Location header is missing, an exception is thrown.

  • The Location header can contain a list of URLs that are separated by commas (,). Requests are redirected only to the first URL in the list. Other URLs are ignored.

  • The Location header can contain absolute URLs or relative URLs.

Decompress

The Fetch API allows you to configure a decompression mode, for example, fetch("https://www.example.com",{decompress: "manual"}). The decompress parameter supports the following values:

  • manual: does not decompress data. If the server returns compressed data upon a fetch request, the data received by EdgeRoutine (ER) is also compressed.

  • decompress: automatically decompresses data. This is the default value. The Fetch API supports Gzip compression. ER automatically detects or decompresses data based on the Content-Encoding header. After ER decompresses data, ER changes the value of Content-Encoding. If the Gzip parameter is deleted, you can configure the following settings to prevent exceptions during data transmission:

    • content-encoding: gzip: ER recognizes the value of Content-Encoding and decompresses data.

    • content-encoding: gzip, identity: ER recognizes the value of Content-Encoding and decompresses data.

    Note

    Algorithms other than Gzip cause exceptions.

  • fallbackIdentity: The effect of this value is similar to the effect of the value decompress. If ER cannot recognize this value, ER does not decompress data.

Important

After the Fetch API automatically decompresses data, you cannot pass the Content-Length header as needed if the response contains the Content-Length header. This is because the Content-Length header indicates the size of the data before decompression.

CdnProxy

When you use the Fetch API to make subrequests in ER, ER directly sends HTTP requests to the Internet, as illustrated by Step 6 in the following figure. You can also use Alibaba Cloud CDN or DCDN as a proxy to process the subrequests, as shown in the following figure. In this case, the subrequests are processed through step 5 and 3. To use Alibaba Cloud CDN as a proxy, set the cdnProxy parameter, for example, fetch("http://www.example.com", {cdnProxy: true}). You can use the cdnProxy parameter to fetch resources from only Alibaba Cloud CDN and DCDN domain names. When you use the cdnProxy parameter, Fetch requests can directly access files cached on the same POP without being redirected to other POPs after DNS resolution. This reduces the time consumption.

Note

The domain name, such as www.example.com, from which you use the Fetch API to fetch resources must be added to Alibaba Cloud CDN or DCDN. Otherwise, the HTTP 403 status code is returned. When you use Alibaba Cloud CDN or DCDN as a proxy, all configurations of the domain name in Alibaba Cloud CDN or DCDN are automatically triggered, including the caching and back-to-origin rules.

How it works

content-length

If you configure the Content-Length header in a fetch request, data is encoded in the format that is specified in the Content-Length header, and the method used by the Fetch API to transmit data is changed. If you do not configure the Content-Length header, the Fetch API automatically fetches all data in the body stream and transmits the data. The transmitted data is encoded by using the chunked transfer encoding scheme.

  • Configure Content-Length

    • If the Content-Length header is set to a non-negative value, the Fetch API fetches data from the body stream based on the Content-Length header and transmits the fetched data. If Content-Length is set to 0, no data is transmitted.

    • If the Content-Length header is set to an invalid value, the Fetch API transmits all values in the body. The transmitted data is encoded by using the chunked transfer encoding scheme.

  • Examples

    The Fetch API automatically decompresses data. After the data is decompressed, the Content-Length header is retained in the response. The Content-Length header indicates the size of data before the data is decompressed. If you call the Fetch API after you modify the body, check whether the Content-Length header needs to be modified. If the Content-Length header needs to be modified, but you do not modify it, the content that is transmitted may be incorrect.

    In the following example, a POST request that contains the Content-Length header is sent from a client. When you call the Fetch API to fetch data, the request body uses the Headers object from the client request. The value of the Content-Length header may be different from the actual size of the body. If the Headers object is transmitted, check whether the size of the body is changed.

    addEventListener('fetch', (event) => {
      event.respondWith(h(event));
    });
    
    async function h(event) {
      return fetch("http://www.example.com", {
        headers: event.request.headers,
        method: event.request.method,
        body: "SomeData"
      });
    }

Headers

  • Definition

    For more information about the Headers object, see Headers.

  • Limits

    A header records the amount of memory resources that are consumed. The maximum size of a Headers object is 8 KB. If the size of a Headers object exceeds this limit, a JavaScript exception is thrown.

  • Blacklist

    The Fetch API uses a header blacklist. If you attempt to read or write a header that is on the blacklist, an exception is thrown. The following table describes the headers that are included in the blacklist.

    • expect

    • te

    • trailer

    • upgrade

    • proxy-connection

    • connection

    • keep-alive

    • dnt

    • host

    • Reserved headers

Request

  • Definition

    For more information about the Request operation, see Request.

  • Limits

    The following properties of the Request object are not in use.

    • context

    • credentials

    • destination

    • integrity

    • mode

    • referrer

    • referrerPolicy

    • cache

  • Use cases of the Request operation

    • Fetches the request method: request.method.

    • Fetches the request URL: request.url.

    • Fetches the request header: request.header.

    • Fetches the request payload: request.body. The Body property (body) is a ReadableStream object.

    • Fetches JSON data: await request.json().

    • Fetches form data: await request.formData().

    • Fetches strings encoded in UTF-8: await request.text().

    The Request operation is a standard API operation. The Request operation ignores the body when it fetches all values of the body without the need to consume the memory resources of ER. This minimizes the garbage collection (GC) pause time and ensures that all values of the request body are fetched from the underlying sockets. If you do not need to read the fetched body, you can call request.ignore in await request.ignore() for all fetch requests. After the body of a request is fetched, ER automatically sends the request to the connection pool for future use.

Response

  • Definition

    For more information about the Response operation, see Response.

  • Limits

    The useFinalURLS and error properties of the Response object are not in use.

  • Use cases of the Response operation

    • Fetches the response code: response.status.

    • Fetches the reason phrase of a response: response.statusText.

    • Fetches the response header: response.headers.

    • Fetches the response URL: response.url.

    • Fetches a list of URLs that redirect to other URLs: response.urlList. This method is a non-standard method, which is similar to the implementation of the Body mixin by the Request object. You can use similar methods to fetch the Body object.

FormData

  • Definition

    For more information about the FormData operation, see FormData.

  • Limits

    The FormData operation is similar to the Headers operation. FormData limits the size of headers. If the size of a header exceeds the upper limit, an exception is thrown. If you send FormData as an HTTP request body, content-type is set to form-data/multipart by default.

URLSearchParams

  • Definition

    For more information about the URLSearchParams operation, see URLSearchParams().

  • Limits

    If you send URLSearchParams as an HTTP request body, content-type is set to application/x-www-form-urlencode by default. The data size cannot exceed 1,000 bytes.

Blob and File

  • Definition

    • For more information about the Blob operation, see Blob.

    • For more information about the File operation, see File.

  • Limits

    ER supports the Blob and File classes, which meet the standards of the Blob and File operations. ER cannot read or write files. You can pass the Blob and File classes supported by ER to the response body. The value of the content-type header is the same as the MIME type in the Blob or File operation.