CodeAPI

wix-fetch

An implementation of the standard Javascript Fetch API which can be used in public and backend code for fetching resources from 3rd party services using HTTPS.

To make a request, call the fetch() function with the path to a resource and the optional WixFetchRequest options. The returns a promise that resolves to a WixFetchResponse. The response object contains a number of properties and functions for retrieving the response's information.

The Fetch API can be used in your front-end or backend code.

To use the Fetch API in the backend, import the fetch function from the wix-fetch module:

   import {fetch} from 'wix-fetch';

The implementation of the Fetch API differs slightly depending on where it's being used. The features documented here comprise the base functionality for both implementations. However, each implementation contains additional features:

  • In public files, the native browser's Fetch API is used.
  • In backend files the node-fetch module is used.

Table of Contents

FUNCTIONS

?
Perform actions on an object.
fetch( )Retrieves the specified resource from the network using HTTPS.
getJSON( )Retrieves the specified JSON resource from the network using HTTPS.

OBJECTS

?
Objects used when setting, getting, or calling the properties and methods listed above.
WixFetchRequestAn object used by the fetch() function representing an HTTPS request.

fetch( )

Retrieves the specified resource from the network using HTTPS.

Description

The fetch() function fetches an HTTPS resource from the network. It returns a Promise that resolves to a WixFetchResponse object representing the HTTP response to the request.

Responses with an HTTP status code in the ranges 2xx, 4xx, and 5xx are considered fulfilled. Use the httpResponse.ok property to confirm that the HTTP request was successful with a response code in the 2xx range.

Note

Some common errors when using the fetch() function are described here along with possible solutions. You can usually tell if you are experiencing these issues by checking your browser's console using the browser's developer tools.

Certain CORS (Cross-Origin Resource Sharing) requests are restricted when originating from a browser. Usually, GET requests and certain POST requests can be made from your site's Public, Page, or Site code. All other requests need to be made from your site's Backend code. If you are experiencing an issue with a fetch() call due to a CORS restriction, move the fetch() call to the backend as described in Accessing 3rd Party Services.

You cannot request HTTP content if your site is an HTTPS site. To fix this issue you can either use the HTTPS protocol to fetch the requested resources or you can turn off SSL on your site.

Syntax

function fetch(url: string, options: WixFetchRequest): Promise<WixFetchResponse>
PARAMETERS
?
The kind of data the property stores.
url
string
The url of the resource to fetch.
options
Options for the fetch operation.
RETURN VALUE
?
Value that a function evaluates to when it is finished running.

Fulfilled - The HTTP response of the fetch operation. Rejected - The error that caused the rejection.

Examples

Get a resource

import {fetch} from 'wix-fetch';

// ...

fetch("https://exchangeratesapi.io/api/latest", {method: "get"})
  .then( (httpResponse) => {
    if (httpResponse.ok) {
      return httpResponse.json();
    } else {
      return Promise.reject("Fetch did not succeed");
    }
  } )
  .then(json => console.log(json.rates["USD"]))
  .catch(err => console.log(err));

Get a resource and the response information

import {fetch} from 'wix-fetch';

// ...

fetch("https://exchangeratesapi.io/api/latest", {method: "get"})
  .then( (httpResponse) => {
    let url = httpResponse.url;
    let statusCode = httpResponse.status;
    let statusText = httpResponse.statusText;
    let headers = httpResponse.headers;
    let bodyUsed = httpResponse.bodyUsed;
    if (httpResponse.ok) {
      return httpResponse.json();
    }
    else {
      return Promise.reject("Fetch did not succeed");
    }
  } )
  .then( (json) => {
    console.log(json.rates["USD"]);
  } )
  .catch( (err) => {
    console.log(err);
  } );

getJSON( )

Retrieves the specified JSON resource from the network using HTTPS.

Description

The getJSON() function retrieves an JSON resource from the network. It returns a Promise that resolves to a JSON object representing the response to the request.

To use getJSON, import it from wix-fetch:

 import {getJSON} from 'wix-fetch';

Retrieving the JSON object is perfomed using the GET method, regardless of what is specified in the options parameter.

The Accept header is assumed to be application/json by default, but you can overriding it by explicitly setting a different value for Accept.

Responses with an HTTP status code in the ranges 2xx, 4xx, and 5xx are considered fulfilled. Use the httpResponse.ok property to confirm that the HTTP request was successful with a response code in the 2xx range.

Note

Some common errors when using the getJSON() function are described here along with possible solutions. You can usually tell if you are experiencing these issues by checking your browser's console using the browser's developer tools.

Certain CORS (Cross-Origin Resource Sharing) requests are restricted when originating from a browser. Usually, GET requests and certain POST requests can be made from your site's Public, Page, or Site code. All other requests need to be made from your site's Backend code. If you are experiencing an issue with a fetch() call due to a CORS restriction, move the fetch() call to the backend as described in Accessing 3rd Party Services.

You cannot request HTTP content if your site is an HTTPS site. To fix this issue you can either use the HTTPS protocol to fetch the requested resources or you can turn off SSL on your site.

Syntax

function getJSON(url: string, options: WixFetchRequest): Promise<Object>
PARAMETERS
?
The kind of data the property stores.
url
string
The url of the JSON resource to retrieve.
options
Options for the retrieval operation.
RETURN VALUE
?
Value that a function evaluates to when it is finished running.
Promise<Object>

Fulfilled - The JSON response of the fetch operation. Rejected - The error that caused the rejection.

Examples

Get a JSON resource

import {getJSON} from 'wix-fetch';

// ...

getJSON("https://exchangeratesapi.io/api/latest")
  .then(json => console.log(json.rates["USD"]))
  .catch(err => console.log(err));

WixFetchRequest

An object used by the fetch() function representing an HTTPS request.

Description

The WixFetchRequest object contains information about an HTTPS request. More functionality is available in each of the respective Fetch API implementations.

Syntax

type WixFetchRequest = {
  method: string
  headers: Object
  body: string
}
MEMBERS
?
The kind of data the property stores.
method
string
The HTTP method to use (if omitted, defaults to "GET").
headers
Object
The request headers.
body
string
The request body.