Native HTTP Plugin

This is a Capacitor 2 plugin that performs HTTP requests natively (OkHttp on Android, URLSession on iOS), bypassing the WebView network layer.

• Native HTTP Plugin
• Install
• Example
  • web
  • native
• API
  • request
  • Interfaces
    • WGHttpRequestOptions
    • WGHttpResponse
    • WGHttpError
    • WGHttpErrorCode
• Notes

Install

npm install @wisdomgarden/capacitor-http
npx cap sync

or

yarn add @wisdomgarden/capacitor-http
npx cap sync

The Android library declares namespace in its build.gradle instead of package in the manifest, so it needs AGP 7.0+ — built against AGP 8.6 / Gradle 8.7. A Capacitor 2 app still on AGP 4.x will fail at configuration time.

iOS requires no extra setup. On Android, register the plugin in your MainActivity (Capacitor 2 does not auto-register third-party plugins):

import com.wisdomgarden.plugins.http.HttpPlugin;

init(savedInstanceState, new ArrayList<Class<? extends Plugin>>() {{
    add(HttpPlugin.class);
}});

Example

web

Not supported in web.

native

// use in native
import { Plugins } from '@capacitor/core';

const { WGCapacitorHttp } = Plugins;

const res = await WGCapacitorHttp.request({
  url: 'https://api.example.com/courses',
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  data: JSON.stringify({ page: 1 }),
  timeout: 15000,
});

console.log(res.status, res.statusText);   // 200 OK
console.log(res.data); // raw response body, as a string

try {
  await WGCapacitorHttp.request({ url });
} catch (err) {
  console.log(err.code, err.message);      // TIMEOUT, SocketTimeoutException: timeout
}

API

request

request(options: WGHttpRequestOptions): Promise<WGHttpResponse>;

Perform an HTTP request. Resolves for every HTTP status code, including 4xx and 5xx — only transport-level failures reject.

| Params | Type | Description | required | default | | --- | --- | --- | --- | --- | | url | string | The request URL | true | | | method | string | GET | POST | PUT | DELETE | PATCH | HEAD | false | GET | | headers | Record<string, string> | Request headers, passed through verbatim. Empty values are skipped | false | {} | | data | string | Request body. Must be a string — serialize it yourself | false | | | timeout | number | Total deadline for the call in ms, same semantics as axios timeout. 0 means platform default | false | 0 |

Returns: Promise<WGHttpResponse>

Rejects with: WGHttpError

Interfaces

WGHttpRequestOptions

| Prop | Type | Description | | --- | --- | --- | | url | string | The request URL | | method | string | HTTP method, defaults to GET | | headers | Record<string, string> | Request headers, passed through verbatim | | data | string | Request body as a string | | timeout | number | Total deadline in ms — elapsed wall time, not idle time. 0 for platform default: 60s on both, as a total deadline on Android and an idle timeout on iOS |

WGHttpResponse

| Prop | Type | Description | | --- | --- | --- | | status | number | HTTP status code. Use this for all logic | | statusText | string | Reason phrase for display only, from a fixed table shared by both platforms. Empty for unlisted codes | | data | string | Raw response body. Never parsed natively | | headers | Record<string, string> | Response headers, keys lowercased, repeated headers joined with ", " | | url | string | Final URL after following redirects |

WGHttpError

| Prop | Type | Description | | --- | --- | --- | | code | WGHttpErrorCode | Error classification | | message | string | Underlying native exception description |

WGHttpErrorCode

| Prop | Type | Description | | --- | --- | --- | | TIMEOUT | string | Connect or read timeout | | SSL_ERROR | string | Certificate or TLS handshake failure | | UNKNOWN_HOST | string | DNS resolution failed | | CONNECTION_ERROR | string | Host unreachable or connection refused | | RESPONSE_TOO_LARGE | string | Response body exceeded the 5 MiB limit | | NETWORK_ERROR | string | Any other transport failure |

Notes

• 4xx and 5xx resolve, they do not reject. Check status yourself, or run it through validateStatus if you are wiring this into axios.
• Response bodies are capped at 5 MiB, beyond which the request fails with RESPONSE_TOO_LARGE.
• Cookies are disabled on both platforms. Authenticate with request headers.
• Not supported: binary responses, upload/download progress, and request cancellation. Route those requests through XHR instead.