@ohos.net.http (Data Request)

Modules to Import

import { http } from '@kit.NetworkKit';

Example

// Import modules.
import { http, connection } from '@kit.NetworkKit';
import { BusinessError } from '@kit.BasicServicesKit';
import { common } from '@kit.AbilityKit';

let context: common.UIAbilityContext = this.getUIContext().getHostContext() as common.UIAbilityContext;
// Each httpRequest corresponds to an HTTP request task and cannot be reused.
let httpRequest = http.createHttp();
// This API is used to listen for HTTP response header events, which returns earlier than the request. You can listen for HTTP response header events as required.
// on('headerReceive', AsyncCallback) is replaced by on('headersReceive', Callback) since API version 8.
httpRequest.on('headersReceive', (header: Object) => {
  console.info('header: ' + JSON.stringify(header));
});

httpRequest.request(// Enter the URL of the HTTP request. The URL can contain parameters or not. The URL needs to be customized.
  "EXAMPLE_URL",
  {
    method: http.RequestMethod.POST, // Optional. The default value is http.RequestMethod.GET.
    // You are advised to use the body field to transfer the request body content. The specific format needs to be negotiated with the server.
    body: 'data to send', // Supported since API version 26.
    // You are advised to use the queryParams field to transfer URL parameters. The value can be a string or an object.
    queryParams: { scene: 'demo', tag: ['a', 'b'] }, // Supported since API version 26.
    expectDataType: http.HttpDataType.STRING, // Optional. This parameter specifies the type of the return data.
    usingCache: true, // Optional. The default value is true.
    priority: 1, // Optional. The default value is 1.
    // You can add the header field based on service requirements. Note that map objects cannot be passed to header fields.
    header: { 'Accept' : 'application/json' },
    readTimeout: 60000, // Optional. The default value is 60000, in ms.
    connectTimeout: 60000 // Optional. The default value is 60000, in ms.
    usingProtocol: http.HttpProtocol.HTTP1_1, // Optional. The default protocol type is automatically specified by the system.
    usingProxy: false, // Optional. The system proxy is used by default. If this parameter is set to false, no proxy is used. This property is supported since API version 10.
    caPath: '/path/to/cacert.pem', // Optional. The system preset CA certificate is used by default. This field is supported since API version 10.
    caData: '-----BEGIN CERTIFICATE-----\n' +
        'MIIDaTCCAlGgAwIBAgIICN287lmB2cMwDQYJKoZIhvcNAQELBQAwgYoxCzAJBgNV\n' +
        'BAYTAkNOMRMwEQYDVQQDDApleGFtcGxlLmNuMRAwDgYDVQQKDAdDb21wYW55MREw\n' +
        'DwYDVQQLDAhEaXZpc2lvbjEOMAwGA1UECAwFQW5IdWkxDjAMBgNVBAcMBUhlRmVp\n' +
        'MSEwHwYJKoZIhvcNAQkBFhJleGFtcGxlQGV4YW1wbGUuY24wHhcNMjUwNDEzMDAy\n' +
        'MjQxWhcNMjgwNDEzMDAyMjQxWjBeMQswCQYDVQQGEwJDTjESMBAGA1UEAwwJMTI3\n' +
        'LjAuMC4xMQkwBwYDVQQKDAAxCTAHBgNVBAsMADEJMAcGA1UECAwAMQkwBwYDVQQH\n' +
        'DAAxDzANBgkqhkiG9w0BCQEWADCCASIwDQYJKoZIhvcNAQEBBQADggEPADCCAQoC\n' +
        'ggEBANN/JrQC8dy7sxUk+TDJlGlq4h8lajdqSASkFbWVBadU4eMCbRrKejXuFX/n\n' +
        'Yu4J3wkgni0NKRejdWu/M+LLibQEIF9RUGNR/OgdlR4AKr8ZxmG44+7Ps2aiDcOy\n' +
        'Z95UcxYj59ctfFk63cacbBi19aq200spjl/H0jTVsQ2/JvwMVEH62WbyjIJ3KXgq\n' +
        'yyjf75rKbR9CdVdGk+OoR4S4c6nY5cTZP6T7iCupYR6MpKEtIR2bbams/N5GxQEh\n' +
        '9+7YxswTQn4EkVhi+UOFZolYLhtIdoLThmStN+WiSL5VDvchAkTUmwUBTGV21WnH\n' +
        'qo6J1t7XtwUpAZF6OuWl85R8D50CAwEAATANBgkqhkiG9w0BAQsFAAOCAQEAqjKq\n' +
        'gwR+4B6bwdAOZ6k0cutLqxvVgBaktX28omuYtoiYagM0zfB8/8WijXL8jT1VLEFx\n' +
        'wPaojwegqYWANfQkPd7A6rjsabgOH7oYBCDoCH52cjzGlJunC0BL6w5g3z6MCOB4\n' +
        'Ciz8rnYMvYqQJiMqrO7Po9onoFBHiRQGO4Wva3O8ErEmd2dKvXb3vN02P3T7CtwM\n' +
        'Z6D0rtZbzdsSOQfGcX08WFIfvfpz6tdU/X/6VqKrt5oiaNQH7ded6gJ3C6RM/Q/x\n' +
        'I2j/hSKy0yU7FoCFSOnlhxbm3TlbIvtjZKQ9ymK4x7iE0VKqExUAA6Z8qsIUBUt4\n' +
        'aqNDeZWXFBqrSujLJA==\n' +
        '-----END CERTIFICATE-----', // Optional. The system preset CA certificate is used by default. This field is supported since API version 20.
    clientCert: { // Optional. The client certificate is not used by default. This field is supported since API version 11.
      certPath: '/path/to/client.pem', // The client certificate is not used by default. This field is supported since API version 11.
      keyPath: '/path/to/client.key', // If the certificate contains key information, an empty string is passed. This field is supported since API version 11.
      certType: http.CertType.PEM, // Optional. A certificate in the PEM format is used by default. This field is supported since API version 11.
      keyPassword: "passwordToKey" // Optional. Password of the key file. This field is supported since API version 11.
    },
    certificatePinning: [ // Optional. Dynamic configuration of certificate pinning. This field is supported since API version 12.
      {
        publicKeyHash: 'Pin1', // Certificate PIN passed by the application. This field is supported since API version 12.
        hashAlgorithm: 'SHA-256' // Encryption algorithm. Currently, it can only be set to SHA-256. This field is supported since API version 12.
      }, {
        publicKeyHash: 'Pin2', // Certificate PIN passed by the application. This field is supported since API version 12.
        hashAlgorithm: 'SHA-256' // Encryption algorithm. Currently, it can only be set to SHA-256. This field is supported since API version 12.
      }
    ],
    multiFormDataList: [ // Optional. This field is valid only when content-Type in the header is multipart/form-data. It is supported since API version 11.
      {
        name: "Part1", // Data name. This field is supported since API version 11.
        contentType: 'text/plain', // Data type. This field is supported since API version 11.
        data: 'Example data', // Data content, optional. This field is supported since API version 11.
        remoteFileName: 'example.txt' // Optional. This field is supported since API version 11.
      }, {
        name: "Part2", // Data name. This field is supported since API version 11.
        contentType: 'text/plain', // Data type. This field is supported since API version 11.
        // data/app/el2/100/base/com.example.myapplication/haps/entry/files/fileName.txt
        filePath: `${context.filesDir}/fileName.txt`, // File path, optional. This field is supported since API version 11.
        remoteFileName: 'fileName.txt' // Optional. This field is supported since API version 11.
      }
    ],
    addressFamily: http.AddressFamily.DEFAULT // Optional. By default, the IPv4 or IPv6 address of the target domain name is selected. This field is supported since API version 15.
    customMethod: 'GET', // Optional. This field is supported since API version 23.
    maxRedirects: 30, // Optional. The default value is 30. This field is supported since API version 23.
    sniHostName: "www.example.com", // Optional. This field is supported since API version 23.
    reuseConnections: true, // Optional. The default value is **true**. This field is supported since API version 26.0.0.
    inactivityMs: 0, // Optional. The default value is 0, which means no limit. This filed is supported since API version 26.0.0.
    usingSocks5Proxy: { // Optional. The SOCKS5 proxy is not used by default. This filed is supported since API version 26.0.0. If this field is specified, the usingProxy field does not take effect.
      host: 'host', // Host name of the SOCKS5 proxy server. This field is supported since API version 26.0.0.
      port: 1080, // Port of the SOCKS5 proxy server. This field is supported since API version 26.0.0.
      username: 'username', // Optional. User name for SOCKS5 proxy authentication. This field is supported since API version 26.0.0.
      password: 'password', // Optional. Password for SOCKS5 proxy authentication. This field is supported since API version 26.0.0.
      dnsStrategy: connection.Socks5DnsStrategy.SYSTEM_MODE, // Optional. Used to specify whether DNS resolution is performed by the system or the SOCKS5 proxy server. The default value is performed by the system. This field is supported since API version 26.0.0.
      exclusionList: [ 'www.example.com' ] // Optional. Used to specify the domain names that do not use the SOCKS5 proxy. This field is supported since API version 26.0.0.
    }
  },
  (err: BusinessError, data: http.HttpResponse) => {
    if (!err) {
      // data.result is the HTTP response. Parse the response based on service requirements.
      console.info('Result:' + JSON.stringify(data.result));
      console.info('code:' + JSON.stringify(data.responseCode));
      console.info('type:' + JSON.stringify(data.resultType));
      // data.header is the HTTP response header. Parse the content based on service requirements.
      console.info('header:' + JSON.stringify(data.header));
      console.info('cookies:' + JSON.stringify(data.cookies)); // Cookies are supported since API version 8.
      // HTTP interaction information can be obtained since API version 24.
      console.info('connectionExtraInfo:' + JSON.stringify(data.connectionExtraInfo));
      // Unsubscribe from HTTP response header events.
      httpRequest.off('headersReceive');
      // Call destroy() to release resources when the request is no longer needed, preventing memory leaks.
      httpRequest.destroy();
    } else {
      console.error('error:' + JSON.stringify(err));
      // Unsubscribe from HTTP response header events.
      httpRequest.off('headersReceive');
      // Call destroy() to release resources when the request is no longer needed, preventing memory leaks.
      httpRequest.destroy();
    }
  });

http.createHttp

createHttp(): HttpRequest

Creates an HTTP request. You can use this API to initiate or destroy an HTTP request, or enable or disable listening for HTTP Response Header events. To initiate multiple HTTP requests, you must create an HttpRequest object for each HTTP request. An HttpRequest object corresponds to an HTTP request.

Atomic service API: This API can be used in atomic services since API version 11.

System capability: SystemCapability.Communication.NetStack

Return value

Example

import { http } from '@kit.NetworkKit';

let httpRequest = http.createHttp();

HttpRequest

Defines an HTTP request task. Before invoking APIs provided by HttpRequest, you must call createHttp() to create an HttpRequestTask object.

request

request(url: string, callback: AsyncCallback<HttpResponse>): void

Initiates an HTTP request to a given URL. This API uses an asynchronous callback to return the result.

Required permissions: ohos.permission.INTERNET

Atomic service API: This API can be used in atomic services since API version 11.

System capability: SystemCapability.Communication.NetStack

Parameters

Error codes

For details about the error codes, see Common Error Codes and HTTP Error Codes.

The HTTP error code mapping is in the format of 2300000 + Curl error code. For more common error codes, see Curl Error Codes.

Example

import { http } from '@kit.NetworkKit';

let httpRequest = http.createHttp();
httpRequest.request("EXAMPLE_URL", (err: Error, data: http.HttpResponse) => {
  if (!err) {
    console.info('Result:' + data.result);
    console.info('code:' + data.responseCode);
    console.info('type:' + JSON.stringify(data.resultType));
    console.info('header:' + JSON.stringify(data.header));
    console.info('cookies:' + data.cookies); // Cookies are supported since API version 8.
  } else {
    console.error('error:' + JSON.stringify(err));
  }
});

request

request(url: string, options: HttpRequestOptions, callback: AsyncCallback<HttpResponse>):void

Initiates an HTTP request containing specified options to a given URL. This API uses an asynchronous callback to return the result.

Required permissions: ohos.permission.INTERNET

Atomic service API: This API can be used in atomic services since API version 11.

System capability: SystemCapability.Communication.NetStack

Parameters

Error codes

For details about the error codes, see Common Error Codes and HTTP Error Codes.

The HTTP error code mapping is in the format of 2300000 + Curl error code. For more common error codes, see Curl Error Codes.

Example

import { http } from '@kit.NetworkKit';

class Header {
  public contentType: string;

  constructor(contentType: string) {
    this.contentType = contentType;
  }
}

let httpRequest = http.createHttp();
let options: http.HttpRequestOptions = {
    method: http.RequestMethod.POST, // Optional. The default value is http.RequestMethod.GET.
  // You are advised to use the body field to transfer the request body content. The specific format needs to be negotiated with the server.
  body: 'data to send', // Supported since API version 26.
  // You are advised to use the queryParams field to transfer URL parameters. The value can be a string or an object.
  queryParams: { scene: 'request-demo', page: 1 }, // Supported since API version 26.
    expectDataType: http.HttpDataType.STRING, // Optional. This parameter specifies the type of the return data.
    usingCache: true, // Optional. The default value is true.
    priority: 1, // Optional. The default value is 1.
    // You can add the header field based on service requirements.
    header: new Header('application/json'),
    readTimeout: 60000, // Optional. The default value is 60000, in ms.
    connectTimeout: 60000 // Optional. The default value is 60000, in ms.
    usingProtocol: http.HttpProtocol.HTTP1_1, // Optional. The default protocol type is automatically specified by the system.
    usingProxy: false, // Optional. The system proxy is used by default. If this parameter is set to false, no proxy is used. This field is supported since API version 10.
};

httpRequest.request("EXAMPLE_URL", options, (err: Error, data: http.HttpResponse) => {
  if (!err) {
    console.info('Result:' + data.result);
    console.info('code:' + data.responseCode);
    console.info('type:' + JSON.stringify(data.resultType));
    console.info('header:' + JSON.stringify(data.header));
    console.info('cookies:' + data.cookies); // Cookies are supported since API version 8.
  } else {
    console.error('error:' + JSON.stringify(err));
  }
});

request

request(url: string, options? : HttpRequestOptions): Promise<HttpResponse>

Initiates an HTTP request containing specified options to a given URL. This API uses a promise to return the result.

Required permissions: ohos.permission.INTERNET

Atomic service API: This API can be used in atomic services since API version 11.

System capability: SystemCapability.Communication.NetStack

Parameters

Return value

Error codes

For details about the error codes, see Common Error Codes and HTTP Error Codes.

The HTTP error code mapping is in the format of 2300000 + Curl error code. For more common error codes, see Curl Error Codes.

Example

import { http } from '@kit.NetworkKit';

class Header {
  public contentType: string;

  constructor(contentType: string) {
    this.contentType = contentType;
  }
}

let httpRequest = http.createHttp();
let promise = httpRequest.request("EXAMPLE_URL", {
  method: http.RequestMethod.GET,
  connectTimeout: 60000,
  readTimeout: 60000,
  header: new Header('application/json')
});
promise.then((data:http.HttpResponse) => {
  console.info('Result:' + data.result);
  console.info('code:' + data.responseCode);
  console.info('type:' + JSON.stringify(data.resultType));
  console.info('header:' + JSON.stringify(data.header));
  console.info('cookies:' + data.cookies); // Cookies are supported since API version 8.
  console.info('header.content-Type:' + data.header);
  console.info('header.Status-Line:' + data.header);
}).catch((err:Error) => {
  console.error('error:' + JSON.stringify(err));
});

destroy

destroy(): void

Stops an HTTP request task and releases system resources.

Atomic service API: This API can be used in atomic services since API version 11.

System capability: SystemCapability.Communication.NetStack

Example

import { http } from '@kit.NetworkKit';
let httpRequest = http.createHttp();

httpRequest.destroy();

requestInStream¹⁰⁺

requestInStream(url: string, callback: AsyncCallback<number>): void

Initiates an HTTP request containing specified options to a given URL. This API uses an asynchronous callback to return the result, which is a streaming response.

Required permissions: ohos.permission.INTERNET

Atomic service API: This API can be used in atomic services since API version 15.

System capability: SystemCapability.Communication.NetStack

Parameters

Error codes

For details about the error codes, see Common Error Codes and HTTP Error Codes.

The HTTP error code mapping is in the format of 2300000 + Curl error code. For more common error codes, see Curl Error Codes.

Example

import { http } from '@kit.NetworkKit';
import { BusinessError } from '@kit.BasicServicesKit';

let httpRequest = http.createHttp();
httpRequest.requestInStream("EXAMPLE_URL", (err: BusinessError, data: number) => {
  if (!err) {
    console.info("requestInStream OK! ResponseCode is " + JSON.stringify(data));
  } else {
    console.error("requestInStream ERROR : err = " + JSON.stringify(err));
  }
})

requestInStream¹⁰⁺

requestInStream(url: string, options: HttpRequestOptions, callback: AsyncCallback<number>): void

Initiates an HTTP request containing specified options to a given URL. This API uses an asynchronous callback to return the result, which is a streaming response.

Required permissions: ohos.permission.INTERNET

Atomic service API: This API can be used in atomic services since API version 15.

System capability: SystemCapability.Communication.NetStack

Parameters

Error codes

For details about the error codes, see Common Error Codes and HTTP Error Codes.

The HTTP error code mapping is in the format of 2300000 + Curl error code. For more common error codes, see Curl Error Codes.

Example

import { http } from '@kit.NetworkKit';
import { BusinessError } from '@kit.BasicServicesKit';

class Header {
  public contentType: string;

  constructor(contentType: string) {
    this.contentType = contentType;
  }
}

let httpRequest = http.createHttp();
let options: http.HttpRequestOptions = {
    method: http.RequestMethod.POST, // Optional. The default value is http.RequestMethod.GET.
    // This field is used to transfer the request body when a POST request is used. Its format needs to be negotiated with the server.
    extraData: 'data to send', // Since API version 26, you are advised to use the body field to transfer the request body content. The specific format needs to be negotiated with the server.
    expectDataType: http.HttpDataType.STRING, // Optional. This field specifies the type of the return data.
    usingCache: true, // Optional. The default value is true.
    priority: 1, // Optional. The default value is 1.
    // You can add the header field based on service requirements.
    header: new Header('application/json'),
    readTimeout: 60000, // Optional. The default value is 60000, in ms.
    connectTimeout: 60000 // Optional. The default value is 60000, in ms.
    usingProtocol: http.HttpProtocol.HTTP1_1, // Optional. The default protocol type is automatically specified by the system.
    usingProxy: false, // Optional. The system proxy is used by default. If this parameter is set to false, no proxy is used. This field is supported since API version 10.
};
httpRequest.requestInStream("EXAMPLE_URL", options, (err: BusinessError<void> , data: number) => {
  if (!err) {
    console.info("requestInStream OK! ResponseCode is " + JSON.stringify(data));
  } else {
    console.error("requestInStream ERROR : err = " + JSON.stringify(err));
  }
})

requestInStream¹⁰⁺

requestInStream(url: string, options? : HttpRequestOptions): Promise<number>

Initiates an HTTP request containing specified options to a given URL. This API uses a promise to return the result, which is a streaming response.

Required permissions: ohos.permission.INTERNET

Atomic service API: This API can be used in atomic services since API version 15.

System capability: SystemCapability.Communication.NetStack

Parameters

Return value

Error codes

For details about the error codes, see Common Error Codes and HTTP Error Codes.

The HTTP error code mapping is in the format of 2300000 + Curl error code. For more common error codes, see Curl Error Codes.

Example

import { http } from '@kit.NetworkKit';

class Header {
  public contentType: string;

  constructor(contentType: string) {
    this.contentType = contentType;
  }
}

let httpRequest = http.createHttp();
let promise = httpRequest.requestInStream("EXAMPLE_URL", {
  method: http.RequestMethod.GET,
  connectTimeout: 60000,
  readTimeout: 60000,
  header: new Header('application/json')
});
promise.then((data: number) => {
  console.info("requestInStream OK!" + data);
}).catch((err: Error) => {
  console.error("requestInStream ERROR : err = " + JSON.stringify(err));
});

requestSync

requestSync(url: string, options?: HttpRequestOptions): HttpResponse

Initiates an HTTP network request based on the URL and related configuration options (optional). This API returns the response synchronously.

Since: 26.0.0

Required permission: ohos.permission.INTERNET

System capability: SystemCapability.Communication.NetStack

Model restriction: This API can be used only in the stage model.

Parameters

Return value

Error codes

For details about the error codes, see Common Error Codes and HTTP Error Codes.

The HTTP error code mapping is in the format of 2300000 + Curl error code. For more common error codes, see Curl Error Codes.

Example

import { http } from '@kit.NetworkKit';

class Header {
  public contentType: string;

  constructor(contentType: string) {
    this.contentType = contentType;
  }
}

let httpRequest = http.createHttp();
let options: http.HttpRequestOptions = {
    method: http.RequestMethod.POST, // Optional. The default value is http.RequestMethod.GET.
    // This field is used to transfer the request body when a POST request is used. Its format needs to be negotiated with the server.
    extraData: 'data to send',
    expectDataType: http.HttpDataType.STRING, // Optional. This field specifies the type of the return data.
    usingCache: true, // Optional. The default value is true.
    priority: 1, // Optional. The default value is 1.
    // You can add the header field based on service requirements.
    header: new Header('application/json'),
    readTimeout: 60000, // Optional. The default value is 60000, in ms.
    connectTimeout: 60000 // Optional. The default value is 60000, in ms.
    usingProtocol: http.HttpProtocol.HTTP1_1, // Optional. The default protocol type is automatically specified by the system.
    usingProxy: false, // Optional. The system proxy is used by default. If this parameter is set to false, no proxy is used. This field is supported since API version 10.
};
let url = "EXAMPLE_URL"; // Access URL.
try {
  let data: http.HttpResponse = httpRequest.requestSync(url, options);
  console.info('Result:' + data.result);
  console.info('code:' + data.responseCode);
  console.info('type:' + JSON.stringify(data.resultType));
  console.info('header:' + JSON.stringify(data.header));
  console.info('cookies:' + data.cookies); // Cookies are supported since API version 8.
} catch (err) {
  console.error('error:' + JSON.stringify(err));
}
httpRequest.destroy();

enableAutoCookie

enableAutoCookie(enable: boolean): void

Sets whether to automatically carry and share cookies. That is, whether to automatically reuse the cookies delivered by the server among multiple requests of the same HttpRequest instance.

Since: 26.0.0

System capability: SystemCapability.Communication.NetStack

Model restriction: This API can be used only in the stage model.

Parameters

Example

import { http } from '@kit.NetworkKit';

let httpRequest = http.createHttp();
let url = "EXAMPLE_URL"; // Access URL. You need to define the URL based on the actual scenario.

// Enable automatic cookie sharing.
httpRequest.enableAutoCookie(true);

httpRequest.request(url, {
  method: http.RequestMethod.GET
}).then((data: http.HttpResponse) => {
  console.info('first request code:' + data.responseCode);
  // Subsequent requests will automatically reuse the cookies saved by this instance.
  return httpRequest.request(url, { method: http.RequestMethod.GET });
}).then((data: http.HttpResponse) => {
  console.info('second request code:' + data.responseCode);
}).catch((err: Error) => {
  console.error('error:' + JSON.stringify(err));
}).finally(() => {
  httpRequest.destroy();
});

on("headerReceive")^(deprecated)

on(type: "headerReceive", callback: AsyncCallback<Object>): void

Registers an observer for HTTP Response Header events.

System capability: SystemCapability.Communication.NetStack

Parameters

Example

import { http } from '@kit.NetworkKit';
import { BusinessError } from '@kit.BasicServicesKit';

let httpRequest = http.createHttp();
httpRequest.on("headerReceive", (data: BusinessError) => {
  console.error("error:" + JSON.stringify(data));
});

off("headerReceive")^(deprecated)

off(type: "headerReceive", callback?: AsyncCallback<Object>): void

Unregisters the observer for HTTP Response Header events.

System capability: SystemCapability.Communication.NetStack

Parameters

Example

import { http } from '@kit.NetworkKit';

let httpRequest = http.createHttp();
httpRequest.off("headerReceive");

on("headersReceive")⁸⁺

on(type: "headersReceive", callback: Callback<Object>): void

Registers an observer for HTTP Response Header events.

Atomic service API: This API can be used in atomic services since API version 11.

System capability: SystemCapability.Communication.NetStack

Parameters

Example

import { http } from '@kit.NetworkKit';

let httpRequest = http.createHttp();
httpRequest.on("headersReceive", (header: Object) => {
  console.info("header: " + JSON.stringify(header));
});
httpRequest.off("headersReceive");

off("headersReceive")⁸⁺

off(type: "headersReceive", callback?: Callback<Object>): void

Unregisters the observer for HTTP Response Header events.

Atomic service API: This API can be used in atomic services since API version 11.

System capability: SystemCapability.Communication.NetStack

Parameters

Example

import { http } from '@kit.NetworkKit';

let httpRequest = http.createHttp();
httpRequest.on("headersReceive", (header: Object) => {
  console.info("header: " + JSON.stringify(header));
});
httpRequest.off("headersReceive");

once("headersReceive")⁸⁺

once(type: "headersReceive", callback: Callback<Object>): void

Registers a one-time observer for HTTP Response Header events. Once triggered, the observer will be removed. This API uses an asynchronous callback to return the result.

Atomic service API: This API can be used in atomic services since API version 15.

System capability: SystemCapability.Communication.NetStack

Parameters

Example

import { http } from '@kit.NetworkKit';

let httpRequest = http.createHttp();
httpRequest.once("headersReceive", (header: Object) => {
  console.info("header: " + JSON.stringify(header));
});

on("dataReceive")¹⁰⁺

on(type: "dataReceive", callback: Callback<ArrayBuffer>): void

Registers an observer for events indicating receiving of HTTP streaming responses.

Atomic service API: This API can be used in atomic services since API version 15.

System capability: SystemCapability.Communication.NetStack

Parameters

Example

import { http } from '@kit.NetworkKit';

let httpRequest = http.createHttp();
httpRequest.on("dataReceive", (data: ArrayBuffer) => {
  console.info("dataReceive length: " + JSON.stringify(data.byteLength));
});
httpRequest.off("dataReceive");

off("dataReceive")¹⁰⁺

off(type: "dataReceive", callback?: Callback<ArrayBuffer>): void

Unregisters the observer for events indicating receiving of HTTP streaming responses.

Atomic service API: This API can be used in atomic services since API version 15.

System capability: SystemCapability.Communication.NetStack

Parameters

Example

import { http } from '@kit.NetworkKit';

let httpRequest = http.createHttp();
httpRequest.on("dataReceive", (data: ArrayBuffer) => {
  console.info("dataReceive length: " + JSON.stringify(data.byteLength));
});
httpRequest.off("dataReceive");

on("dataEnd")¹⁰⁺

on(type: "dataEnd", callback: Callback<void>): void

Registers an observer for events indicating completion of receiving HTTP streaming responses.

Atomic service API: This API can be used in atomic services since API version 15.

System capability: SystemCapability.Communication.NetStack

Parameters

Example

import { http } from '@kit.NetworkKit';

let httpRequest = http.createHttp();
httpRequest.on("dataEnd", () => {
  console.info("Receive dataEnd !");
});
httpRequest.off("dataEnd");

off("dataEnd")¹⁰⁺

off(type: "dataEnd", callback?: Callback<void>): void

Unregisters the observer for events indicating completion of receiving HTTP streaming responses.

Atomic service API: This API can be used in atomic services since API version 15.

System capability: SystemCapability.Communication.NetStack

Parameters

Example

import { http } from '@kit.NetworkKit';

let httpRequest = http.createHttp();
httpRequest.on("dataEnd", () => {
  console.info("Receive dataEnd !");
});
httpRequest.off("dataEnd");

on('dataReceiveProgress')¹⁰⁺

on(type: 'dataReceiveProgress', callback: Callback<DataReceiveProgressInfo>): void

Registers an observer for events indicating progress of receiving HTTP streaming responses.

Atomic service API: This API can be used in atomic services since API version 15.

System capability: SystemCapability.Communication.NetStack

Parameters

Example

import { http } from '@kit.NetworkKit';

let httpRequest = http.createHttp();
httpRequest.on("dataReceiveProgress", (data: http.DataReceiveProgressInfo) => {
  console.info("dataReceiveProgress:" + JSON.stringify(data));
});
httpRequest.off("dataReceiveProgress");

off('dataReceiveProgress')¹⁰⁺

off(type: 'dataReceiveProgress', callback?: Callback<DataReceiveProgressInfo>): void

Unregisters the observer for events indicating progress of receiving HTTP streaming responses.

Atomic service API: This API can be used in atomic services since API version 15.

System capability: SystemCapability.Communication.NetStack

Parameters

Example

import { http } from '@kit.NetworkKit';

let httpRequest = http.createHttp();
httpRequest.on("dataReceiveProgress", (data: http.DataReceiveProgressInfo) => {
  console.info("dataReceiveProgress:" + JSON.stringify(data));
});
httpRequest.off("dataReceiveProgress");

on('dataSendProgress')¹¹⁺

on(type: 'dataSendProgress', callback: Callback<DataSendProgressInfo>): void

Registers an observer for events indicating progress of sending HTTP requests.

Atomic service API: This API can be used in atomic services since API version 15.

System capability: SystemCapability.Communication.NetStack

Parameters

Example

import { http } from '@kit.NetworkKit';

let httpRequest = http.createHttp();
httpRequest.on("dataSendProgress", (data: http.DataSendProgressInfo) => {
  console.info("dataSendProgress:" + JSON.stringify(data));
});
httpRequest.off("dataSendProgress");

off('dataSendProgress')¹¹⁺

off(type: 'dataSendProgress', callback?: Callback<DataSendProgressInfo>): void

Unregisters the observer for events indicating progress of sending HTTP requests.

Atomic service API: This API can be used in atomic services since API version 15.

System capability: SystemCapability.Communication.NetStack

Parameters

Example

import { http } from '@kit.NetworkKit';

let httpRequest = http.createHttp();
httpRequest.on("dataSendProgress", (data: http.DataSendProgressInfo) => {
  console.info("dataSendProgress:" + JSON.stringify(data));
});
httpRequest.off("dataSendProgress");

HttpRequestOptions

Defines the options for initiating an HTTP request.

System capability: SystemCapability.Communication.NetStack

RequestMethod

Defines an HTTP request method.

System capability: SystemCapability.Communication.NetStack

ResponseCode

Enumerates the response codes for an HTTP request.

System capability: SystemCapability.Communication.NetStack

HttpResponse

Defines the response to an HTTP request.

System capability: SystemCapability.Communication.NetStack

ClientCert¹¹⁺

Defines the client certificate type.

System capability: SystemCapability.Communication.NetStack

PerformanceTiming¹¹⁺

Defines the performance timing (unit: ms).

System capability: SystemCapability.Communication.NetStack

ConnectionExtraInfo²⁴⁺

Defines the detailed information about the HTTP request interaction.

System capability: SystemCapability.Communication.NetStack

Model restriction: This API can be used only in the stage model.

DataReceiveProgressInfo¹¹⁺

Defines the data receiving progress information.

Atomic service API: This API can be used in atomic services since API version 15.

System capability: SystemCapability.Communication.NetStack

DataSendProgressInfo¹¹⁺

Defines the data sending progress information.

Atomic service API: This API can be used in atomic services since API version 15.

System capability: SystemCapability.Communication.NetStack

Attributes

MultiFormData¹¹⁺

Defines the type of multi-form data.

System capability: SystemCapability.Communication.NetStack

http.createHttpResponseCache⁹⁺

createHttpResponseCache(cacheSize?: number): HttpResponseCache

Creates an HttpResponseCache object that stores the response data of HTTP requests. You can call flush and delete in the object.

Atomic service API: This API can be used in atomic services since API version 11.

System capability: SystemCapability.Communication.NetStack

Parameters

Return value

Example

import { http } from '@kit.NetworkKit';

let httpResponseCache = http.createHttpResponseCache();

HttpResponseCache⁹⁺

Defines an object that stores the response to an HTTP request. Before invoking APIs provided by HttpResponseCache, you must call createHttpResponseCache() to create an HttpRequestTask object.

Usage of Keywords in the Response Header

• Cache-Control: specifies the cache policy, for example, no-cache, no-store, max-age, public, or private.

• Expires: specifies the expiration time of a resource. The value is in the GMT format.

• ETag: identifies the resource version. The client can use the If-None-Match request header to check whether the resource has been modified.

• Last-Modified: specifies the last modification time of a resource. The client can use the If-Modified-Since request header to check whether a resource has been modified.

• Vary: specifies the parts of the request header that affect the cached response. This field is used to distinguish different cache versions.

When using these keywords, ensure that the response header is correctly configured on the server. The client determines whether to use the cached resource and how to verify whether the resource is the latest based on the response header. Correct cache policies help to improve application performance and user experience.

How to Set the Cache-Control Header

Cache-Control is a common header, but it is usually used on the server. It allows you to define when, how, and how long a response should be cached. The following are some common Cache-Control directives:

• no-cache: indicates that the response can be stored in the cache, but it must be verified with the origin server before each reuse. If the resource remains unchanged, the response status code is 304 (Not Modified). In this case, the resource content is not sent, and the resource in the cache is used. If the resource has expired, the response status code is 200 and the resource content is sent.

• no-store: indicates that resources cannot be cached. Resources must be obtained from the server for each request.

• max-age: specifies the maximum cache duration, in seconds. For example, Cache-Control: max-age=3600 indicates that the valid cache duration is 3,600 seconds (that is, 1 hour).

• public: indicates that the response can be cached by any object, for example, the client that sends the request or the proxy server.

• private: indicates that the response can be cached only by a single user and cannot be used as a shared cache (that is, the response cannot be cached by the proxy server).

• must-revalidate: indicates that a resource must be revalidated with the origin server once it has become stable.

• no-transform: indicates that the proxy server is not allowed to modify the response content.

• proxy-revalidate: works in a way similar to must-revalidate, but applies only to shared caches.

• s-maxage: works in a way similar to max-age, but applies only to shared caches.

flush⁹⁺

flush(callback: AsyncCallback<void>): void

Flushes data in the cache to the file system so that the cached data can be accessed in the next HTTP request. This API uses an asynchronous callback to return the result. Cached data includes the response header (header), response body (result), cookies, request time (requestTime), and response time (responseTime).

Atomic service API: This API can be used in atomic services since API version 11.

System capability: SystemCapability.Communication.NetStack

Parameters

Example

import { http } from '@kit.NetworkKit';
import { BusinessError } from '@kit.BasicServicesKit';

let httpResponseCache = http.createHttpResponseCache();
let httpRequest = http.createHttp();
httpRequest.request("EXAMPLE_URL", (err: BusinessError, data: http.HttpResponse) => {
  if (!err) {
    httpResponseCache.flush((err: BusinessError) => {
      if (err) {
        console.error('flush fail');
      }
      console.info('flush success');
    });
    httpRequest.destroy();
  } else {
    console.error('error:' + JSON.stringify(err));
    // Call destroy() to release resources when the request is no longer needed, preventing memory leaks.
    httpRequest.destroy();
  }
});

flush⁹⁺

flush(): Promise<void>

Flushes data in the cache to the file system so that the cached data can be accessed in the next HTTP request. This API uses a promise to return the result.

Atomic service API: This API can be used in atomic services since API version 11.

System capability: SystemCapability.Communication.NetStack

Return value

Example

import { http } from '@kit.NetworkKit';
import { BusinessError } from '@kit.BasicServicesKit';

let httpRequest = http.createHttp();
let httpResponseCache = http.createHttpResponseCache();
let promise = httpRequest.request("EXAMPLE_URL");

promise.then((data: http.HttpResponse) => {
  httpResponseCache.flush().then(() => {
    console.info('flush success');
  }).catch((err: BusinessError) => {
    console.error('flush fail');
  });
}).catch((err: Error) => {
  console.error('error:' + JSON.stringify(err));
});

delete⁹⁺

delete(callback: AsyncCallback<void>): void

Disables the cache and deletes the data in it. This API uses an asynchronous callback to return the result.

Atomic service API: This API can be used in atomic services since API version 11.

System capability: SystemCapability.Communication.NetStack

Parameters

Example

import { http } from '@kit.NetworkKit';
import { BusinessError } from '@kit.BasicServicesKit';

let httpRequest = http.createHttp();
httpRequest.request("EXAMPLE_URL").then(data => {
  const httpResponseCache = http.createHttpResponseCache();
  httpResponseCache.delete((err: BusinessError) => {
    try {
      if (err) {
        console.error('fail: ' + err);
      } else {
        console.info('success');
      }
    } catch (err) {
      console.error('error: ' + err);
    }
  });
  httpRequest.destroy();
}).catch((error: BusinessError) => {
  console.error("errcode" + JSON.stringify(error));
});

delete⁹⁺

delete(): Promise<void>

Disables the cache and deletes the data in it. This API uses a promise to return the result.

Atomic service API: This API can be used in atomic services since API version 11.

System capability: SystemCapability.Communication.NetStack

Return value

Example

import { http } from '@kit.NetworkKit';
import { BusinessError } from '@kit.BasicServicesKit';

let httpRequest = http.createHttp();
httpRequest.request("EXAMPLE_URL").then(data => {
  const httpResponseCache = http.createHttpResponseCache();
  httpResponseCache.delete().then(() => {
    console.info("success");
  }).catch((err: BusinessError) => {
    console.error("fail");
  });
  httpRequest.destroy();
}).catch((error: BusinessError) => {
  console.error("errcode" + JSON.stringify(error));
});

HttpDataType⁹⁺

Enumerates HTTP data types.

Atomic service API: This API can be used in atomic services since API version 11.

System capability: SystemCapability.Communication.NetStack

HttpProtocol⁹⁺

Enumerates HTTP protocol versions.

System capability: SystemCapability.Communication.NetStack

CertType¹¹⁺

Enumerates certificate types.

System capability: SystemCapability.Communication.NetStack

CertificatePinning¹²⁺

Defines the dynamic configuration of certificate pinning.

System capability: SystemCapability.Communication.NetStack

HttpProxy¹⁰⁺

type HttpProxy = connection.HttpProxy

Defines the network proxy configuration.

Atomic service API: This API can be used in atomic services since API version 11.

System capability: SystemCapability.Communication.NetStack

Socks5Proxy

type Socks5Proxy = connection.Socks5Proxy

Defines the SOCKS5 proxy configuration information.

Since: 26.0.0

Model restriction: This API can be used only in the stage model.

System capability: SystemCapability.Communication.NetStack

QueryParamValue

type QueryParamValue = string | number | boolean | null | undefined

Defines the single-value type that can be used in QueryParamObject.

Since: 26.0.0

System capability: SystemCapability.Communication.NetStack

Model restriction: This API can be used only in the stage model.

QueryParamObject

type QueryParamObject = Record<string, QueryParamValue | QueryParamValue[]>

Defines the key-value object type used to construct URL query parameters.

Since: 26.0.0

System capability: SystemCapability.Communication.NetStack

Model restriction: This API can be used only in the stage model.

AddressFamily¹⁵⁺

Enumerates IP address families of the target domain name.

System capability: SystemCapability.Communication.NetStack

Credential¹⁸⁺

Represents the credential used for server identity verification in a session, including the user name and password.

Atomic service API: This API can be used in atomic services since API version 18.

System capability: SystemCapability.Communication.NetStack

ServerAuthentication¹⁸⁺

Defines HTTP server identity verification information.

Atomic service API: This API can be used in atomic services since API version 18.

System capability: SystemCapability.Communication.NetStack

TlsConfig¹⁸⁺

Defines the TLS configuration, including the version and cipher suite.

Atomic service API: This API can be used in atomic services since API version 18.

System capability: SystemCapability.Communication.NetStack

TlsVersion¹⁸⁺

Enumerates TLS versions.

Atomic service API: This API can be used in atomic services since API version 18.

System capability: SystemCapability.Communication.NetStack

TlsOptions¹⁸⁺

type TlsOptions = 'system' | TlsConfig

Defines the TLS configuration.

Atomic service API: This API can be used in atomic services since API version 18.

System capability: SystemCapability.Communication.NetStack

RemoteValidation¹⁸⁺

type RemoteValidation = 'system' | 'skip' | ValidationCallback

Enumerates the identity verification modes of the remote server.

Atomic service API: This API can be used in atomic services since API version 18.

System capability: SystemCapability.Communication.NetStack

X509Cert

type X509Cert = cert.X509Cert

X509 certificate object.

Since: 26.0.0

Model restriction: This API can be used only in the stage model.

System capability: SystemCapability.Communication.NetStack

ValidationContext

Certificate context information used when verifying the identity of the remote server, which is passed in as a parameter of ValidationCallback.

Since: 26.0.0

Model restriction: This API can be used only in the stage model.

System capability: SystemCapability.Communication.NetStack

ValidationCallback

type ValidationCallback = (context: ValidationContext) => boolean | Promise<boolean>

Defines a custom callback for remote server identity verification. Developers can use this callback to implement custom certificate verification logic, supporting synchronous or asynchronous return of the verification result.

Since: 26.0.0

Model restriction: This API can be used only in the stage model.

System capability: SystemCapability.Communication.NetStack

Parameters

Return value

AuthenticationType¹⁸⁺

type AuthenticationType = 'basic' | 'ntlm' | 'digest'

Enumerates server authentication modes in a session.

Atomic service API: This API can be used in atomic services since API version 18.

System capability: SystemCapability.Communication.NetStack

CipherSuite¹⁸⁺

type CipherSuite = TlsV13CipherSuite

Declares the cipher suite.

Atomic service API: This API can be used in atomic services since API version 18.

System capability: SystemCapability.Communication.NetStack

TlsV13CipherSuite¹⁸⁺

type TlsV13CipherSuite = TlsV12CipherSuite | TlsV13SpecificCipherSuite

Declares the cipher suite for TLS 1.3, which is also compatible with TLS 1.2.

Atomic service API: This API can be used in atomic services since API version 18.

System capability: SystemCapability.Communication.NetStack

TlsV12CipherSuite¹⁸⁺

type TlsV12CipherSuite = TlsV11CipherSuite | TlsV12SpecificCipherSuite

Declares the cipher suite for TLS 1.2, which is also compatible with TLS 1.1.

Atomic service API: This API can be used in atomic services since API version 18.

System capability: SystemCapability.Communication.NetStack

TlsV11CipherSuite¹⁸⁺

type TlsV11CipherSuite = TlsV10CipherSuite

Declares the cipher suite for TLS 1.1, which is the same as that for TLS1.0.

Atomic service API: This API can be used in atomic services since API version 18.

System capability: SystemCapability.Communication.NetStack

TlsV10CipherSuite¹⁸⁺

type TlsV10CipherSuite = TlsV10SpecificCipherSuite

Declares the cipher suite for TLS 1.0.

Atomic service API: This API can be used in atomic services since API version 18.

System capability: SystemCapability.Communication.NetStack

TlsV13SpecificCipherSuite¹⁸⁺

type TlsV13SpecificCipherSuite = 'TLS_AES_128_GCM_SHA256' | 'TLS_AES_256_GCM_SHA384' | 'TLS_CHACHA20_POLY1305_SHA256'

Enumerates cipher suites supported by TLS 1.3 or later.

Atomic service API: This API can be used in atomic services since API version 18.

System capability: SystemCapability.Communication.NetStack

TlsV12SpecificCipherSuite¹⁸⁺

type TlsV12SpecificCipherSuite = 'TLS_ECDHE_ECDSA_WITH_AES_128_GCM_SHA256' | 'TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256' |

'TLS_ECDHE_ECDSA_WITH_AES_256_GCM_SHA384' | 'TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384' |

'TLS_ECDHE_ECDSA_WITH_CHACHA20_POLY1305_SHA256' | 'TLS_ECDHE_RSA_WITH_CHACHA20_POLY1305_SHA256' |

'TLS_RSA_WITH_AES_128_GCM_SHA256' | 'TLS_RSA_WITH_AES_256_GCM_SHA384'

Enumerates cipher suites supported by TLS 1.2 or later.

Atomic service API: This API can be used in atomic services since API version 18.

System capability: SystemCapability.Communication.NetStack

TlsV10SpecificCipherSuite¹⁸⁺

type TlsV10SpecificCipherSuite = 'TLS_ECDHE_ECDSA_WITH_AES_128_CBC_SHA' | 'TLS_ECDHE_RSA_WITH_AES_128_CBC_SHA' |

'TLS_ECDHE_ECDSA_WITH_AES_256_CBC_SHA' | 'TLS_ECDHE_RSA_WITH_AES_256_CBC_SHA' | 'TLS_RSA_WITH_AES_128_CBC_SHA' |

'TLS_RSA_WITH_AES_256_CBC_SHA' | 'TLS_RSA_WITH_3DES_EDE_CBC_SHA'

Enumerates cipher suites supported by TLS 1.0 or later.

Atomic service API: This API can be used in atomic services since API version 18.

System capability: SystemCapability.Communication.NetStack

SslType²⁰⁺

type SslType = 'TLS' | 'TLCP'

Defines the secure communications protocol.

Atomic service API: This API can be used in atomic services since API version 20.

System capability: SystemCapability.Communication.NetStack

InterceptorType²²⁺

Enumerates the types of HTTP interceptors.

Atomic service API: This API can be used in atomic services since API version 22.

System capability: SystemCapability.Communication.NetStack

HttpRequestContext²²⁺

Defines HTTP request context data. The object instance is passed as a parameter in the interceptorHandle method of the interceptor. You can use this object to obtain and modify the information about the HTTP request.

Atomic service API: This API can be used in atomic services since API version 22.

System capability: SystemCapability.Communication.NetStack

Attributes

ChainContinue²²⁺

type ChainContinue = boolean

Specifies whether to continue to process the interceptor chain.

Atomic service API: This API can be used in atomic services since API version 22.

System capability: SystemCapability.Communication.NetStack

HttpInterceptor²²⁺

Defines the HTTP interceptor API, which is used to define the interception processing function.

Atomic service API: This API can be used in atomic services since API version 22.

System capability: SystemCapability.Communication.NetStack

Attributes

interceptorHandle²²⁺

interceptorHandle(reqContext: HttpRequestContext, rspContext: HttpResponse): Promise<ChainContinue>

Intercepts the HTTP processing and modifies it as required.

Atomic service API: This API can be used in atomic services since API version 22.

System capability: SystemCapability.Communication.NetStack

Parameters

Return value

Example

import { http } from '@kit.NetworkKit';

// Create a custom interceptor.
class CustomInterceptor implements http.HttpInterceptor {
  interceptorType: http.InterceptorType = http.InterceptorType.INITIAL_REQUEST;

  async interceptorHandle(reqContext: http.HttpRequestContext, rspContext: http.HttpResponse): Promise<http.ChainContinue> {
    // Add the authentication header in the initial request phase.
    reqContext.header['Authorization'] = 'Bearer token';
    console.info('Interceptor: Added authorization header');
    return true; // Continue to process the interceptor chain.
  }
}

let customInterceptor = new CustomInterceptor();

HttpInterceptorChain²²⁺

Defines HTTP interceptor chain.

Atomic service API: This API can be used in atomic services since API version 22.

System capability: SystemCapability.Communication.NetStack

Example

import { http } from '@kit.NetworkKit';

let interceptorChain = new http.HttpInterceptorChain();

addChain²²⁺

addChain(chain: HttpInterceptor[]): boolean

Adds an interceptor to the HTTP client.

Atomic service API: This API can be used in atomic services since API version 22.

System capability: SystemCapability.Communication.NetStack

Parameters

Return value

Error codes

For details about the error codes, see Common Error Codes and HTTP Error Codes.

The HTTP error code mapping is in the format of 2300000 + Curl error code. For more common error codes, see Curl Error Codes.

Example

import { http } from '@kit.NetworkKit';

// Create an authentication interceptor.
class AuthInterceptor implements http.HttpInterceptor {
  interceptorType: http.InterceptorType = http.InterceptorType.INITIAL_REQUEST;

  async interceptorHandle(reqContext: http.HttpRequestContext, rspContext: http.HttpResponse): Promise<http.ChainContinue> {
    // Add the authentication header in the initial request phase.
    reqContext.header['Authorization'] = 'Bearer token';
    console.info('Interceptor: Added authorization header');
    return true; // Continue to process the interceptor chain.
  }
}

class LoggingInterceptor implements http.HttpInterceptor {
  interceptorType: http.InterceptorType = http.InterceptorType.FINAL_RESPONSE;

  async interceptorHandle(reqContext: http.HttpRequestContext, rspContext: http.HttpResponse): Promise<http.ChainContinue> {
    // Record logs in the final response phase.
    console.info(`LoggingInterceptor: Request to ${reqContext.url} completed with status ${rspContext.responseCode}`);
    return true; // Continue to process the interceptor chain.
  }
}

// Create an interceptor chain and apply the interceptor chain to the request.
let interceptorChain = new http.HttpInterceptorChain();
let authInterceptor = new AuthInterceptor();
let loggingInterceptor = new LoggingInterceptor();

// Add the interceptor to the chain.
try {
  let success = interceptorChain.addChain([authInterceptor, loggingInterceptor]);
  if (!success) {
    console.error('Failed to add interceptor chain');
  }
} catch (e) {
  console.error(`Interceptor chain add failed: code=${e.code}, message=${e.message}`);
}

getChain²²⁺

getChain(): HttpInterceptor[]

Obtains all interceptor instances in the current interceptor chain.

Atomic service API: This API can be used in atomic services since API version 22.

System capability: SystemCapability.Communication.NetStack

Return value

Example

import { http } from '@kit.NetworkKit';

// Create a custom interceptor.
class CustomInterceptor implements http.HttpInterceptor {
  interceptorType: http.InterceptorType = http.InterceptorType.INITIAL_REQUEST;

  async interceptorHandle(reqContext: http.HttpRequestContext, rspContext: http.HttpResponse): Promise<http.ChainContinue> {
    // Add the authentication header in the initial request phase.
    reqContext.header['Authorization'] = 'Bearer token';
    console.info('Interceptor: Added authorization header');
    return true; // Continue to process the interceptor chain.
  }
}

// Create an interceptor chain and apply the interceptor chain to the request.
let interceptorChain = new http.HttpInterceptorChain();
let customInterceptor = new CustomInterceptor();

// Add the interceptor to the chain.
try {
  let success = interceptorChain.addChain([customInterceptor]);
  if (!success) {
    console.error('Failed to add interceptor chain');
  }
} catch (e) {
  console.error(`Interceptor chain add failed: code=${e.code}, message=${e.message}`);
}

// Obtain all interceptors in the current interceptor chain.
let chain = interceptorChain.getChain();
console.info(`Current interceptor chain has ${chain.length} interceptors`);

apply²²⁺

apply(httpRequest: HttpRequest): boolean

Adds an interceptor chain to the target HTTP request. Each HTTP request instance can have only one interceptor chain attached.

Atomic service API: This API can be used in atomic services since API version 22.

System capability: SystemCapability.Communication.NetStack

Parameters

Return value

Error codes

For details about the error codes, see Common Error Codes and HTTP Error Codes.

The HTTP error code mapping is in the format of 2300000 + Curl error code. For more common error codes, see Curl Error Codes.

Example

import { http } from '@kit.NetworkKit';

// Create an authentication interceptor.
class AuthInterceptor implements http.HttpInterceptor {
  interceptorType: http.InterceptorType = http.InterceptorType.INITIAL_REQUEST;

  async interceptorHandle(reqContext: http.HttpRequestContext, rspContext: http.HttpResponse): Promise<http.ChainContinue> {
    // Add the authentication header in the initial request phase.
    reqContext.header['Authorization'] = 'Bearer token';
    console.info('Interceptor: Added authorization header');
    return true; // Continue to process the interceptor chain.
  }
}

class LoggingInterceptor implements http.HttpInterceptor {
  interceptorType: http.InterceptorType = http.InterceptorType.FINAL_RESPONSE;

  async interceptorHandle(reqContext: http.HttpRequestContext, rspContext: http.HttpResponse): Promise<http.ChainContinue> {
    // Record logs in the final response phase.
    console.info(`LoggingInterceptor: Request to ${reqContext.url} completed with status ${rspContext.responseCode}`);
    return true; // Continue to process the interceptor chain.
  }
}

// Create an interceptor chain.
let interceptorChain = new http.HttpInterceptorChain();
let authInterceptor = new AuthInterceptor();
let loggingInterceptor = new LoggingInterceptor();

// Create an HTTP request.
let httpRequest = http.createHttp();

try {
  // Add the interceptor to the chain.
  let success = interceptorChain.addChain([authInterceptor, loggingInterceptor]);
  if (!success) {
    console.error('Failed to add interceptor chain');
  }

  // Apply the interceptor chain to the HTTP request.
  let applySuccess = interceptorChain.apply(httpRequest);
  if (!applySuccess) {
    console.error('Failed to apply interceptor chain');
  }
} catch (e) {
  console.error(`Interceptor chain add failed: code=${e.code}, message=${e.message}`);
}

// Initiate an HTTP request. If interception is required, the request can be initiated only through the request API.
httpRequest.request("EXAMPLE_URL", {
  method: http.RequestMethod.GET,
  header: { 'Content-Type': 'application/json' }
}, (err: Error, data: http.HttpResponse) => {
  if (!err) {
    console.info('Request completed with response code: ' + data.responseCode);
  } else {
    console.error('Request failed: ' + JSON.stringify(err));
  }
  httpRequest.destroy();
});

PathPreference²³⁺

type PathPreference = 'auto' | 'primaryCellular' | 'secondaryCellular'

Enumerates the types of networks specified in an HTTP request.

System capability: SystemCapability.Communication.NetStack