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

## request

> [VERSION] BaseKit >= 2.0.1 | @ray-js/ray >= 0.3.23

> [PLATFORM] iOS, Android

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

### Description

Make an HTTPS request

### Parameters

| Property | Type | Required | Default | Since | Description |
| --- | --- | --- | --- | --- | --- |
| `url` | `string` | Yes | - | `2.0.1` | URL of the developer server endpoint |
| `data` | `string` | No | - | `2.0.1` | Request parameters |
| `header` | `Record<string, string>` | No | - | `2.0.1` | Set request headers; 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, effective 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 | - | - | Completion callback (executed on both success and failure) |
| `success` | `(params: Object) => void` ↓see below | No | - | - | Callback on successful API call |
| `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 request |
| `taskId` | `string` | `3.2.6` | Network request ID for canceling, listening, etc. |

#### 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` | Error extension code |
| `errorMsg` | `string` | Error extension message |


### Referenced Types

##### `interface` Profile

| Property | Type | Since | Description |
| --- | --- | --- | --- |
| `redirectStart` | `number` | `3.2.6` | Time when the first HTTP redirect occurred. Only counted for redirects within the same domain; otherwise 0 |
| `redirectEnd` | `number` | `3.2.6` | Time when the last HTTP redirect finished. Only counted for redirects within the same domain; otherwise 0 |
| `fetchStart` | `number` | `3.2.6` | Time when the component became ready to fetch the resource via HTTP, before checking the local cache |
| `domainLookupStart` | `number` | `3.2.6` | Time when DNS lookup started; if a local cache (no DNS lookup) or a persistent connection is used, equals fetchStart |
| `domainLookupEnd` | `number` | `3.2.6` | Time when DNS lookup completed; if a local cache (no DNS lookup) or a persistent connection is used, equals fetchStart |
| `connectStart` | `number` | `3.2.6` | Time when the HTTP (TCP) connection started to be established; if a persistent connection, equals fetchStart. Note: if an error occurred at the transport layer and the connection was re-established, this shows the start time of the new connection |
| `connectEnd` | `number` | `3.2.6` | Time when the HTTP (TCP) connection finished establishing (handshake completed); if a persistent connection, equals fetchStart. Note: if an error occurred at the transport layer and the connection was re-established, this shows the completion time of the new connection. Note: handshake completion includes secure connection established and SOCKS authorization passed |
| `SSLconnectionStart` | `number` | `3.2.6` | Time when the SSL connection started; if not a secure connection, the value is 0 |
| `SSLconnectionEnd` | `number` | `3.2.6` | Time when the SSL connection completed; if not a secure connection, the value is 0 |
| `requestStart` | `number` | `3.2.6` | Time when the HTTP request started reading the actual document (after the connection was established), including reads from the local cache. On reconnect after a connection error, this also shows the time the new connection was established |
| `requestEnd` | `number` | `3.2.6` | Time when reading the actual document ended |
| `responseStart` | `number` | `3.2.6` | Time when HTTP started receiving the response (first byte), including local cache reads |
| `responseEnd` | `number` | `3.2.6` | Time when the entire HTTP response was received (last byte), including local cache reads |
| `rtt` | `number` | `3.2.6` | Real-time RTT during this request’s connection |
| `estimate_nettype` | `string` | `3.2.6` | Estimated network status: slow 2g/2g/3g/4g |
| `httpRttEstimate` | `number` | `3.2.6` | Protocol layer’s estimated current network RTT based on multiple requests (for reference only) |
| `transportRttEstimate` | `number` | `3.2.6` | Transport layer’s estimated current network RTT based on multiple requests (for reference only) |
| `downstreamThroughputKbpsEstimate` | `number` | `3.2.6` | Estimated download kbps of 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 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 request OPTIONS |
| `"GET"` | HTTP request GET |
| `"HEAD"` | HTTP request HEAD |
| `"POST"` | HTTP request POST |
| `"PUT"` | HTTP request PUT |
| `"DELETE"` | HTTP request DELETE |
| `"TRACE"` | HTTP request TRACE |
| `"CONNECT"` | HTTP request TRACE |


### Examples

#### Demo

```tsx
import { request } from '@ray-js/ray'

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