capacitor-community / http

Community plugin for native HTTP
MIT License
208 stars 136 forks source link
capacitor http


HTTP

@capacitor-community/http

Capacitor community plugin for native HTTP requests, file download/uploads, and cookie management.


Maintainers

Maintainer GitHub Social
Max Lynch mlynch @maxlynch
Thomas Vidas thomasvidas @thomasvidas

Installation

npm install @capacitor-community/http
npx cap sync

Maintence Mode

The next iteration of this plugin will be an official plugin bundled with Capacitor 4.x. In order for a smooth transition, this repo will be in maintence mode with no new features added until the plugin moves to the main Capacitor Plugins repo. In the meantime, if there are critical security bug fixes required, they will still be made to this plugin as a patch release.

Capacitor 2.x

For Capacitor 2.x projects, you will need to install a version less than 1.0.0. You can do that by specifying the version in your package.json or installing like this. The latest 2.x compatible version is 0.3.1.

npm install @capacitor-community/http@0.x

Configuration

In most cases no configuration is required for this plugin. If the Android application connects with use the self-signed certificates or without encryption, see Network security configuration article.

Usage

To use the plugin while fully supporting the web version, import and use it like this:

import { Http } from '@capacitor-community/http';

// 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 Http.get(options);

  // or...
  // const response = await Http.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 Http.post(options);

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

const setCookie = async () => {
  const options = {
    url: 'http://example.com',
    key: 'language',
    value: 'en',
  };

  await Http.setCookie(options);
};

const deleteCookie = async () => {
  const options = {
    url: 'http://example.com',
    key: 'language',
  };

  await Http.deleteCookie(options);
};

const clearCookies = async () => {
  await Http.clearCookies({ url: 'http://example.com' });
};

const getCookies = async () => {
  const cookies: HttpCookie[] = await Http.getCookies({
    url: 'http://example.com',
  });
};

const downloadFile = async () => {
  const options = {
    url: 'https://example.com/path/to/download.pdf',
    filePath: 'document.pdf',
    fileDirectory: Directory.Downloads,
    // Optional
    method: 'GET',
  };

  // Writes to local filesystem
  const response: HttpDownloadFileResult = await Http.downloadFile(options);

  // Then read the file
  if (response.path) {
    const read = await Filesystem.readFile({
      path: 'download.pdf',
      directory: Directory.Downloads,
    });
  }
};

const uploadFile = async () => {
  const options = {
    url: 'https://example.com/path/to/upload.pdf',
    name: 'myFile',
    filePath: 'document.pdf',
    fileDirectory: FilesystemDirectory.Downloads,
  };

  const response: HttpUploadFileResult = await Http.uploadFile();
};

API Reference

You can view the API Reference generated by TypeDoc here: https://capacitor-community.github.io/http/docs/classes/web.httpweb.html

Third Party Cookies on iOS

As of iOS 14, you cannot use 3rd party cookies by default. There is an open issue on the Capacitor Core repo on properly patching in cookies on iOS. For now, you must specify a domain of for the cookie you are saving to properly save and send them via requests. You can also add the following lines to your Info.plist file to get better support for cookies on iOS. You can add up to 10 domains.

<key>WKAppBoundDomains</key>
<array>
    <string>www.mydomain.com</string>
    <string>api.mydomain.com</string>
    <string>www.myothercooldomain.com</string>
</array>

Contributors ✨

Thanks goes to these wonderful people (emoji key):


Daniel Sogl

πŸ“–

Priyank Patel

πŸ’»

Max Lynch

πŸ’»

Falk Schieber

πŸ‘€

Andy Sousa

πŸ’»

Thomas Vidas

πŸ’» 🚧

Emily Curry

πŸ’»

graefenhain

πŸ’»

Lee Houghton

πŸ›

Felix Schwarzmeier

πŸ’»

Kamil Jakubus

πŸ’»

Joe Flateau

πŸ›

Frank608

πŸ›

Joel Nieto

πŸ›

ultimate-tester

πŸ’»

Adrian Sanchez

πŸ›

milanc

πŸ’»

herecoulbeyourname

πŸ’»

Landschaft

πŸ’»

stonewoodman

πŸ›

HΓ©ctor Cruz

πŸ›

Patrick Bußmann

πŸ’»

Jesper Bjerke

πŸ›

This project follows the all-contributors specification. Contributions of any kind welcome!