1# HTTP Data Request
2
3## When to Use
4
5An application can initiate a data request over HTTP. Common HTTP methods include **GET**, **POST**, **OPTIONS**, **HEAD**, **PUT**, **DELETE**, **TRACE**, and **CONNECT**.
6
7## Available APIs
8
9The HTTP request function is mainly implemented by the HTTP module.
10
11To use related APIs, you must declare the **ohos.permission.INTERNET** permission.
12
13For details about how to apply for permissions, see [Declaring Permissions](../security/AccessToken/declare-permissions.md).
14
15The following table provides only a simple description of the related APIs. For details, see [API Reference](../reference/apis-network-kit/js-apis-http.md).
16
17| API                                   | Description                               |
18| ----------------------------------------- | ----------------------------------- |
19| createHttp()                              | Creates an HTTP request.                 |
20| request()                                 | Initiates an HTTP request to a given URL.    |
21| requestInStream()<sup>10+</sup>           | Initiates an HTTP network request to a given URL and returns a streaming response.|
22| destroy()                                 | Destroys an HTTP request.                     |
23| on(type: 'headersReceive')                | Registers an observer for HTTP Response Header events.    |
24| off(type: 'headersReceive')               | Unregisters the observer for HTTP Response Header events.|
25| once\('headersReceive'\)<sup>8+</sup>     | Registers a one-time observer for HTTP Response Header events.|
26| on\('dataReceive'\)<sup>10+</sup>         | Registers an observer for events indicating receiving of HTTP streaming responses.     |
27| off\('dataReceive'\)<sup>10+</sup>        | Unregisters the observer for events indicating receiving of HTTP streaming responses. |
28| on\('dataEnd'\)<sup>10+</sup>             | Registers an observer for events indicating completion of receiving HTTP streaming responses. |
29| off\('dataEnd'\)<sup>10+</sup>            | Unregisters the observer for events indicating completion of receiving HTTP streaming responses.|
30| on\('dataReceiveProgress'\)<sup>10+</sup>        | Registers an observer for events indicating progress of receiving HTTP streaming responses. |
31| off\('dataReceiveProgress'\)<sup>10+</sup>       | Unregisters the observer for events indicating progress of receiving HTTP streaming responses.|
32| on\('dataSendProgress'\)<sup>11+</sup>        | Registers an observer for events indicating progress of sending HTTP requests. |
33| off\('dataSendProgress'\)<sup>11+</sup>       | Unregisters the observer for events indicating progress of sending HTTP requests.|
34
35## How to Develop request APIs
36
371. Import the **http** namespace from **@kit.NetworkKit**.
382. Call **createHttp()** to create an **HttpRequest** object.
393. Call **httpRequest.on()** to subscribe to HTTP response header events. This API returns a response earlier than the request. You can subscribe to HTTP response header events based on service requirements.
404. Call **httpRequest.request()** to initiate a network request. You need to pass in the URL and optional parameters of the HTTP request.
415. Parse the returned result based on service requirements.
426. Call **off()** to unsubscribe from HTTP response header events.
437. Call **httpRequest.destroy()** to release resources after the request is processed.
44
45```ts
46// Import the http namespace.
47import { http } from '@kit.NetworkKit';
48import { BusinessError } from '@kit.BasicServicesKit';
49
50// Each httpRequest corresponds to an HTTP request task and cannot be reused.
51let httpRequest = http.createHttp();
52// This API is used to listen for the HTTP Response Header event, which is returned earlier than the result of the HTTP request. It is up to you whether to listen for HTTP Response Header events.
53// on('headerReceive', AsyncCallback) is replaced by on('headersReceive', Callback) since API version 8.
54httpRequest.on('headersReceive', (header) => {
55  console.info('header: ' + JSON.stringify(header));
56});
57httpRequest.request(
58  // Customize EXAMPLE_URL in extraData on your own. It is up to you whether to add parameters to the URL.
59  "EXAMPLE_URL",
60  {
61    method: http.RequestMethod.POST, // Optional. The default value is http.RequestMethod.GET.
62    // You can add header fields based on service requirements.
63    header: {
64      'Content-Type': 'application/json'
65    },
66    // This field is used to transfer the request body when a POST request is used. Its format needs to be negotiated with the server.
67    extraData: "data to send",
68    expectDataType: http.HttpDataType.STRING, // Optional. This field specifies the type of the return data.
69    usingCache: true, // Optional. The default value is true.
70    priority: 1, // Optional. The default value is 1.
71    connectTimeout: 60000 // Optional. The default value is 60000, in ms.
72    readTimeout: 60000, // Optional. The default value is 60000, in ms.
73    usingProtocol: http.HttpProtocol.HTTP1_1, // Optional. The default protocol type is automatically specified by the system.
74    usingProxy: false, // Optional. By default, network proxy is not used. This field is supported since API version 10.
75    caPath: '/path/to/cacert.pem', // Optional. The preset CA certificate is used by default. This field is supported since API version 10.
76    clientCert: { // Optional. The client certificate is not used by default. This field is supported since API version 11.
77      certPath: '/path/to/client.pem', // The client certificate is not used by default. This field is supported since API version 11.
78      keyPath: '/path/to/client.key', // If the certificate contains key information, an empty string is passed. This field is supported since API version 11.
79      certType: http.CertType.PEM, // Certificate type, optional. A certificate in the PEM format is used by default. This field is supported since API version 11.
80      keyPassword: "passwordToKey" // Password of the key file, optional. It is supported since API version 11.
81    },
82    multiFormDataList: [ // Optional. This field is valid only when content-Type in the header is multipart/form-data. It is supported since API version 11.
83      {
84        name: "Part1", // Data name. This field is supported since API version 11.
85        contentType: 'text/plain', // Data type. This field is supported since API version 11.
86        data: 'Example data', // Data content, optional. This field is supported since API version 11.
87        remoteFileName: 'example.txt' // Optional. This field is supported since API version 11.
88      }, {
89        name: "Part2", // Data name. This field is supported since API version 11.
90        contentType: 'text/plain', // Data type. This field is supported since API version 11.
91        // data/app/el2/100/base/com.example.myapplication/haps/entry/files/fileName.txt
92        filePath: `${getContext(this).filesDir}/fileName.txt`, // File path, optional. This field is supported since API version 11.
93        remoteFileName: 'fileName.txt' // Optional. This field is supported since API version 11.
94      }
95    ]
96  }, (err: BusinessError, data: http.HttpResponse) => {
97    if (!err) {
98      // data.result carries the HTTP response. Parse the response based on service requirements.
99      console.info('Result:' + JSON.stringify(data.result));
100      console.info('code:' + JSON.stringify(data.responseCode));
101      // data.header carries the HTTP response header. Parse the content based on service requirements.
102      console.info('header:' + JSON.stringify(data.header));
103      console.info('cookies:' + JSON.stringify(data.cookies)); // 8+
104      // Call the destroy() method to release resources after HttpRequest is complete.
105      httpRequest.destroy();
106    } else {
107      console.error('error:' + JSON.stringify(err));
108      // Unsubscribe from HTTP Response Header events.
109      httpRequest.off('headersReceive');
110      // Call the destroy() method to release resources after HttpRequest is complete.
111      httpRequest.destroy();
112    }
113  }
114);
115```
116
117## How to Develop requestInStream APIs
118
1191. Import the **http** namespace from **@kit.NetworkKit**.
1202. Call **createHttp()** to create an **HttpRequest** object.
1213. Depending on your need, call **on()** of the **HttpRequest** object to subscribe to HTTP response header events as well as events indicating receiving of HTTP streaming responses, progress of receiving HTTP streaming responses, and completion of receiving HTTP streaming responses.
1224. Call **requestInStream()** to initiate a network request. You need to pass in the URL and optional parameters of the HTTP request.
1235. Parse the returned response code as needed.
1246. Call **off()** of the **HttpRequest** object to unsubscribe from the related events.
1257. Call **httpRequest.destroy()** to release resources after the request is processed.
126
127```ts
128// Import the http namespace.
129import { http } from '@kit.NetworkKit';
130import { BusinessError } from '@kit.BasicServicesKit';
131
132// Each httpRequest corresponds to an HTTP request task and cannot be reused.
133let httpRequest = http.createHttp();
134// Subscribe to HTTP response header events.
135httpRequest.on('headersReceive', (header: Object) => {
136  console.info('header: ' + JSON.stringify(header));
137});
138// Subscribe to events indicating receiving of HTTP streaming responses.
139let res = new ArrayBuffer(0);
140httpRequest.on('dataReceive', (data: ArrayBuffer) => {
141   const newRes = new ArrayBuffer(res.byteLength + data.byteLength);
142   const resView = new Uint8Array(newRes);
143   resView.set(new Uint8Array(res));
144   resView.set(new Uint8Array(data), res.byteLength);
145   res = newRes;
146   console.info('res length: ' + res.byteLength);
147});
148// Subscribe to events indicating completion of receiving HTTP streaming responses.
149httpRequest.on('dataEnd', () => {
150  console.info('No more data in response, data receive end');
151});
152// Subscribe to events indicating progress of receiving HTTP streaming responses.
153class Data {
154  receiveSize: number = 0;
155  totalSize: number = 0;
156}
157httpRequest.on('dataReceiveProgress', (data: Data) => {
158  console.log("dataReceiveProgress receiveSize:" + data.receiveSize + ", totalSize:" + data.totalSize);
159});
160
161let streamInfo: http.HttpRequestOptions = {
162  method: http.RequestMethod.POST, // Optional. The default value is http.RequestMethod.GET.
163  // You can add header fields based on service requirements.
164  header: {
165    'Content-Type': 'application/json'
166  },
167  // This field is used to transfer the request body when a POST request is used. Its format needs to be negotiated with the server.
168  extraData: "data to send",
169  expectDataType: http.HttpDataType.STRING, // Optional. This field specifies the type of the return data.
170  usingCache: true, // Optional. The default value is true.
171  priority: 1, // Optional. The default value is 1.
172  connectTimeout: 60000 // Optional. The default value is 60000, in ms.
173  readTimeout: 60000, // Optional. The default value is 60000, in ms. If a large amount of data needs to be transmitted, you are advised to set this parameter to a larger value to ensure normal data transmission.
174  usingProtocol: http.HttpProtocol.HTTP1_1 // Optional. The default protocol type is automatically specified by the system.
175}
176
177// Customize EXAMPLE_URL in extraData on your own. It is up to you whether to add parameters to the URL.
178httpRequest.requestInStream("EXAMPLE_URL", streamInfo).then((data: number) => {
179  console.info("requestInStream OK!");
180  console.info('ResponseCode :' + JSON.stringify(data));
181  // Unsubscribe from HTTP Response Header events.
182  httpRequest.off('headersReceive');
183  // Unregister the observer for events indicating receiving of HTTP streaming responses.
184  httpRequest.off('dataReceive');
185  // Unregister the observer for events indicating progress of receiving HTTP streaming responses.
186  httpRequest.off('dataReceiveProgress');
187  // Unregister the observer for events indicating completion of receiving HTTP streaming responses.
188  httpRequest.off('dataEnd');
189  // Call the destroy() method to release resources after HttpRequest is complete.
190  httpRequest.destroy();
191}).catch((err: Error) => {
192  console.info("requestInStream ERROR : err = " + JSON.stringify(err));
193});
194```
195
196