---
name: "apiRequestByHighway"
mode: "kit"
versionRequirements:
  - { name: "MiniKit", version: "2.3.6" }
  - { name: "@ray-js/ray", version: "0.5.9" }
platform:
  - "iOS"
  - "Android"
async: true
title: "apiRequestByHighway"
---

## apiRequestByHighway

> [VERSION] MiniKit >= 2.3.6 | @ray-js/ray >= 0.5.9

> [PLATFORM] iOS, Android

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

### Description

Initiate a highway request

### Parameters

| Property | Type | Required | Default | Since | Description |
| --- | --- | --- | --- | --- | --- |
| `api` | `string` | Yes | - | `2.3.6` | API name |
| `data` | `Record<string, any>` | No | - | `2.3.6` | Highway API request parameters; field structure is defined by the Highway interface for the specified api |
| `method` | `"OPTIONS" \| "GET" \| "HEAD" \| "POST" \| "PUT" \| "DELETE" \| "TRACE" \| "CONNECT"` | No | `'GET'` | `2.3.6` | method request method |
| `requestId` | `string` | No | - | `3.27.0` | requestId request ID, not exposed to business code |
| `cache` | `ApiRequestCacheBean` | No | - | `3.27.0` | cache cache configuration |
| `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` | `Record<string, any>` | `3.2.0` | Raw API response data |

#### 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` ApiRequestCacheBean

| Property | Type | Since | Description |
| --- | --- | --- | --- |
| `timeout` | `number` | `4.24.0` | Cache timeout, in seconds |
| `policy` | `"NETWORK_ONLY" \| "CACHE_ELSE_NETWORK" \| "CACHE_THEN_NETWORK"` | `4.24.0` | Cache policy; default: CachePolicy.CACHE_THEN_NETWORK |


### Valid Values

##### `method` valid values

| Value | Description |
| --- | --- |
| `"GET"` | HTTP GET request |
| `"POST"` | HTTP POST request |
| `"PUT"` | HTTP PUT request |
| `"DELETE"` | HTTP DELETE request |

##### `cache.policy` valid values

| Value | Description |
| --- | --- |
| `"NETWORK_ONLY"` | Only send a network request, do not use cache |
| `"CACHE_ELSE_NETWORK"` | Use cache first; if not present, send a network request |
| `"CACHE_THEN_NETWORK"` | Prefer cache while also sending a network request; the network result will be delivered via events |


### Examples

#### Demo

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

// Highway RESTful request: api is a "/v1.0/..." url, method is GET/POST,
// data depends on the specific highway api. (Real usage from @ray-js/ray miniapps.)
apiRequestByHighway({
  api: "/v1.0/m/tc/album/pic/batch/download/url",
  method: "POST",
  data: {},
  success: data => {
    console.log(data);
  },
  fail: error => {
    console.error(error);
  },
});
```