@wordpress/api-fetch Edit

Utility to make WordPress REST API requests. It’s a wrapper around window.fetch.

Installation #Installation

Install the module

npm install @wordpress/api-fetch --save

This package assumes that your code will run in an ES2015+ environment. If you’re using an environment that has limited or no support for ES2015+ such as lower versions of IE then using core-js or @babel/polyfill will add support for these methods. Learn more about it in Babel docs.

Top ↑

Usage #Usage

import apiFetch from '@wordpress/api-fetch';

// GET
apiFetch( { path: '/wp/v2/posts' } ).then( posts => {
    console.log( posts );
} );

// POST
apiFetch( {
    path: '/wp/v2/posts/1',
    method: 'POST',
    data: { title: 'New Post Title' },
} ).then( res => {
    console.log( res );
} );

Options #Options

apiFetch supports and passes through all options of the fetch global.

Additionally, the following options are available:

path (string) #path (string)

Shorthand to be used in place of url, appended to the REST API root URL for the current site.

Top ↑

url (string) #url (string)

Absolute URL to the endpoint from which to fetch.

Top ↑

parse (boolean, default true) #parse (boolean, default true)

Unlike fetch, the Promise return value of apiFetch will resolve to the parsed JSON result. Disable this behavior by passing parse as false.

Top ↑

data (object) #data (object)

Shorthand to be used in place of body, accepts an object value to be stringified to JSON.

Top ↑

Middlewares #Middlewares

the api-fetch package supports middlewares. Middlewares are functions you can use to wrap the apiFetch calls to perform any pre/post process to the API requests.

Example

import apiFetch from '@wordpress/api-fetch';

apiFetch.use( ( options, next ) => {
    const start = Date.now();
    const result = next( options );
    result.then( () => {
        console.log( 'The request took ' + Date.now() - start );
    } );
    return result;
} );

Top ↑

Built-in middlewares #Built-in middlewares

The api-fetch package provides built-in middlewares you can use to provide a nonce and a custom rootURL.

Nonce middleware

import apiFetch from '@wordpress/api-fetch';

const nonce = "nonce value";
apiFetch.use( apiFetch.createNonceMiddleware( nonce ) );

The function returned by createNonceMiddleware includes a nonce property corresponding to the actively used nonce. You may also assign to this property if you have a fresh nonce value to use.

Root URL middleware

import apiFetch from '@wordpress/api-fetch';

const rootURL = "http://my-wordpress-site/wp-json/";
apiFetch.use( apiFetch.createRootURLMiddleware( rootURL ) );

Top ↑

Custom fetch handler #Custom fetch handler

The api-fetch package uses window.fetch for making the requests but you can use a custom fetch handler by using the setFetchHandler method. The custom fetch handler will receive the options passed to the apiFetch calls.

Example

The example below uses a custom fetch handler for making all the requests with axios.

import apiFetch from '@wordpress/api-fetch';
import axios from 'axios';

apiFetch.setFetchHandler( ( options ) => {
    const { url, path, data, method } = options;

    return axios( {
        url: url || path,
        method,
        data,
    } );
} );