Skip to main content
Version: v4

CapacitorHttp

The Capacitor Http API provides native http support via patching fetch and XMLHttpRequest to use native libraries. It also provides helper methods for native http requests without the use of fetch and XMLHttpRequest. This plugin is bundled with @capacitor/core.

Configuration

By default, the patching of window.fetch and XMLHttpRequest to use native libraries is disabled. If you would like to enable this feature, modify the configuration below in the capacitor.config file.

PropTypeDescriptionDefault
enabledbooleanEnable the patching of fetch and XMLHttpRequest to use native libraries instead.false

Example Configuration

In capacitor.config.json:

{
"plugins": {
"CapacitorHttp": {
"enabled": true
}
}
}

In capacitor.config.ts:

import { CapacitorConfig } from '@capacitor/cli';

const config: CapacitorConfig = {
plugins: {
CapacitorHttp: {
enabled: true,
},
},
};

export default config;

Example

import { CapacitorHttp } from '@capacitor/core';

// Example of a GET request
const doGet = () => {
const options = {
url: 'https://example.com/my/api',
headers: { 'X-Fake-Header': 'Max was here' },
params: { size: 'XL' },
};

const response: HttpResponse = await CapacitorHttp.get(options);

// or...
// const response = await CapacitorHttp.request({ ...options, method: 'GET' })
};

// Example of a POST request. Note: data
// can be passed as a raw JS Object (must be JSON serializable)
const doPost = () => {
const options = {
url: 'https://example.com/my/api',
headers: { 'X-Fake-Header': 'Thomas was here' },
data: { foo: 'bar', cool: true },
};

const response: HttpResponse = await CapacitorHttp.post(options);

// or...
// const response = await CapacitorHttp.request({ ...options, method: 'POST' })
};

Large File Support

Due to the nature of the bridge, parsing and transferring large amount of data from native to the web can cause issues. Support for downloading and uploading files to the native device is planned to be added to the @capacitor/filesystem plugin in the near future. One way to potentially circumvent the issue of running out of memory in the meantime (specifically on Android) is to edit the AndroidManifest.xml and add android:largeHeap="true" to the application element. Most apps should not need this and should instead focus on reducing their overall memory usage for improved performance. Enabling this also does not guarantee a fixed increase in available memory, because some devices are constrained by their total available memory.

API

request(...)

request(options: HttpOptions) => Promise<HttpResponse>

Make a Http Request to a server using native libraries.

ParamType
optionsHttpOptions

get(...)

get(options: HttpOptions) => Promise<HttpResponse>

Make a Http GET Request to a server using native libraries.

ParamType
optionsHttpOptions

post(...)

post(options: HttpOptions) => Promise<HttpResponse>

Make a Http POST Request to a server using native libraries.

ParamType
optionsHttpOptions

put(...)

put(options: HttpOptions) => Promise<HttpResponse>

Make a Http PUT Request to a server using native libraries.

ParamType
optionsHttpOptions

patch(...)

patch(options: HttpOptions) => Promise<HttpResponse>

Make a Http PATCH Request to a server using native libraries.

ParamType
optionsHttpOptions

delete(...)

delete(options: HttpOptions) => Promise<HttpResponse>

Make a Http DELETE Request to a server using native libraries.

ParamType
optionsHttpOptions

Interfaces

HttpOptions

PropTypeDescription
urlstringThe URL to send the request to.
method?stringThe Http Request method to run. (Default is GET)
params?HttpParamsURL parameters to append to the request.
data?anyJSON data to send with the request.
headers?HttpHeadersHttp Request headers to send with the request.
readTimeout?numberHow long to wait to read additional data. Resets each time new data is received.
connectTimeout?numberHow long to wait for the initial connection.
disableRedirects?booleanSets whether automatic Http redirects should be disabled.
webFetchExtra?RequestInitExtra arguments for fetch when running on the web.
responseType?HttpResponseTypeParse the response appropriately before returning it to the client. If the response content-type is json, this value is ignored.
shouldEncodeUrlParams?booleanA option to keep the URL unencoded if necessary (already encoded, azure/firebase testing, etc.). (Default is true)

HttpParams

TypeDescription
[key: string]: string or string[]A key/value dictionary of URL parameters to set.

HttpHeaders

TypeDescription
[key: string]: stringA key/value dictionary of Http headers.

HttpResponseType

TypeDescription
'arraybuffer' or 'blob' or 'json' or 'text' or 'document'How to parse the Http response before returning it to the client.

HttpResponse

PropTypeDescription
urlstringThe response URL recieved from the Http response.
statusnumberThe status code received from the Http response.
dataanyAdditional data received with the Http response.
headersHttpHeadersThe headers received from the Http response.