---
name: "request"
mode: "kit"
versionRequirements:
  - { name: "BaseKit", version: "2.0.1" }
platform:
  - "iOS"
  - "Android"
async: true
title: "request"
---

## request

> [VERSION] BaseKit >= 2.0.1

> [PLATFORM] iOS, Android

> ⚡ **Supports Promise** — Returns a Promise when success / fail / complete callbacks are omitted.

### Description

Initiate an HTTPS request

### Parameters

| Property | Type | Required | Default | Since | Description |
| --- | --- | --- | --- | --- | --- |
| `url` | `string` | Yes | - | `2.0.1` | Developer server API URL |
| `data` | `string` | No | - | `2.0.1` | Request parameters |
| `header` | `Record<string, string>` | No | - | `2.0.1` | Set request headers; the Referer cannot be set. content-type defaults to application/json |
| `timeout` | `number` | No | - | `2.0.1` | Timeout in milliseconds |
| `method` | `"OPTIONS" \| "GET" \| "HEAD" \| "POST" \| "PUT" \| "DELETE" \| "TRACE" \| "CONNECT"` | No | `'GET'` | `2.0.1` | HTTP request method |
| `dataType` | `string` | No | `"json"` | `2.0.1` | Data type of the request body (Android only, applies when the method is not GET) |
| `responseType` | `string` | No | `"text"` | `2.0.1` | Response data type |
| `enableHttp2` | `boolean` | No | `false` | `2.0.1` | enableHttp2 |
| `enableQuic` | `boolean` | No | `false` | `2.0.1` | enableQuic |
| `enableCache` | `boolean` | No | `false` | `2.0.1` | enableCache |
| `complete` | `() => void` | No | - | - | Callback executed when the API call completes (runs on both success and failure) |
| `success` | `(params: Object) => void` ↓see below | No | - | - | Success callback |
| `fail` | `(params: Object) => void` ↓see below | No | - | - | Failure callback |

#### success callback parameters

| Property | Type | Since | Description |
| --- | --- | --- | --- |
| `data` | `string` | `3.2.6` | Data returned by the developer server |
| `statusCode` | `number` | `3.2.6` | HTTP status code returned by the developer server |
| `header` | `Record<string, string>` | `3.2.6` | HTTP response headers returned by the developer server |
| `cookies` | `string[]` | `3.2.6` | Cookies returned by the developer server, as a string array |
| `profile` | `Profile` | `3.2.6` | Debug information during the network request |
| `taskId` | `string` | `3.2.6` | Network request ID for canceling, listening, and other operations |

#### fail callback parameters

| Property | Type | Description |
| --- | --- | --- |
| `errorMsg` | `string` | Error message |
| `errorCode` | `string \| number` | Error code |
| `innerError` | `Object` | Error extension |

##### fail(params).innerError properties

| Property | Type | Description |
| --- | --- | --- |
| `errorCode` | `string \| number` | Extended error code |
| `errorMsg` | `string` | Extended error information |


### Referenced Types

##### `interface` Profile

| Property | Type | Since | Description |
| --- | --- | --- | --- |
| `redirectStart` | `number` | `3.2.6` | Time of the first HTTP redirect. Only counted for same-domain redirects; otherwise 0 |
| `redirectEnd` | `number` | `3.2.6` | Time when the last HTTP redirect completes. Only counted for same-domain redirects; otherwise 0 |
| `fetchStart` | `number` | `3.2.6` | Time when the component is ready to fetch resources using an HTTP request, which occurs before checking the local cache |
| `domainLookupStart` | `number` | `3.2.6` | DNS lookup start time. If local cache is used (no DNS lookup) or a persistent connection is used, equals fetchStart |
| `domainLookupEnd` | `number` | `3.2.6` | DNS lookup end time. If local cache is used (no DNS lookup) or a persistent connection is used, equals fetchStart |
| `connectStart` | `number` | `3.2.6` | HTTP (TCP) connection start time. If a persistent connection is used, equals fetchStart. Note: If a transport-level error occurs and a new connection is established, this shows the start time of the new connection |
| `connectEnd` | `number` | `3.2.6` | HTTP (TCP) connection established time (handshake complete). If a persistent connection is used, equals fetchStart. Note: If a transport-level error occurs and a new connection is established, this shows the completion time of the new connection. Handshake completion includes secure connection established and SOCKS authorization |
| `SSLconnectionStart` | `number` | `3.2.6` | SSL connection start time; 0 if not a secure connection |
| `SSLconnectionEnd` | `number` | `3.2.6` | SSL connection completion time; 0 if not a secure connection |
| `requestStart` | `number` | `3.2.6` | Time when the HTTP request starts reading the actual document (connection established), including reads from local cache. On connection error and reconnect, this shows the time the new connection was established |
| `requestEnd` | `number` | `3.2.6` | Time when the HTTP request finishes reading the actual document |
| `responseStart` | `number` | `3.2.6` | Time when HTTP starts receiving the response (first byte received), including reads from local cache |
| `responseEnd` | `number` | `3.2.6` | Time when the HTTP response is fully received (last byte received), including reads from local cache |
| `rtt` | `number` | `3.2.6` | Real-time RTT during the connection for this request |
| `estimate_nettype` | `string` | `3.2.6` | Estimated network status: slow 2G/2G/3G/4G |
| `httpRttEstimate` | `number` | `3.2.6` | Protocol layer’s RTT estimate of the current network based on multiple requests (for reference only) |
| `transportRttEstimate` | `number` | `3.2.6` | Transport layer’s RTT estimate of the current network based on multiple requests (for reference only) |
| `downstreamThroughputKbpsEstimate` | `number` | `3.2.6` | Estimated download kbps for the current network |
| `throughputKbps` | `number` | `3.2.6` | Actual download kbps of the current network |
| `peerIP` | `string` | `3.2.6` | IP address of the current request |
| `port` | `number` | `3.2.6` | Port number of the current request |
| `socketReused` | `boolean` | `3.2.6` | Whether the connection is reused |
| `sendBytesCount` | `number` | `3.2.6` | Bytes sent |
| `receivedBytedCount` | `number` | `3.2.6` | Bytes received |


### Valid Values

##### `method` valid values

| Value | Description |
| --- | --- |
| `"OPTIONS"` | HTTP OPTIONS request |
| `"GET"` | HTTP GET request |
| `"HEAD"` | HTTP HEAD request |
| `"POST"` | HTTP POST request |
| `"PUT"` | HTTP PUT request |
| `"DELETE"` | HTTP DELETE request |
| `"TRACE"` | HTTP TRACE request |
| `"CONNECT"` | HTTP TRACE request |


### Examples

```tsx
// Initiate an HTTPS GET request. ty.request synchronously returns a RequestTask; the result is returned via the success/fail callbacks.
ty.request({
  url: "https://httpbin.org/get",
  method: "GET",
  success: data => {
    console.log(data);
  },
  fail: error => {
    console.error(error);
  },
});
```