API Fetch

The @wordpress/api-fetch package is a utility wrapper around window.fetch designed specifically for making WordPress REST API requests. It simplifies API calls by automatically handling REST API root URLs, nonces, and request parsing.

Installation

You can install the package using npm:

npm install @wordpress/api-fetch --save

This package assumes your code will run in an ES2015+ environment. If you’re targeting environments with limited support for modern JavaScript features, include the polyfill from @wordpress/babel-preset-default.

Basic Usage

Making GET Requests

You can make GET requests by passing a path option to apiFetch:

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

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

GET with Query Parameters

Combine apiFetch with addQueryArgs from @wordpress/url to add query parameters:

import apiFetch from '@wordpress/api-fetch';
import { addQueryArgs } from '@wordpress/url';

const queryParams = { include: [1, 2, 3] }; // Return posts with ID = 1, 2, 3.

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

Making POST Requests

You can use the method and data options to send POST requests:

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

API Reference

apiFetch( options )

The main function that makes API requests. It accepts all standard fetch options plus additional WordPress-specific options.

Options

string

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

string

Absolute URL to the endpoint from which to fetch.

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.

object

Sent on POST or PUT requests only. Shorthand to be used in place of body, accepts an object value to be stringified to JSON.

string

HTTP method for the request (e.g., ‘GET’, ‘POST’, ‘PUT’, ‘DELETE’).

Aborting Requests

You can abort requests using the AbortController API:

const controller =
	typeof AbortController === 'undefined' ? undefined : new AbortController();

apiFetch( { path: '/wp/v2/posts', signal: controller?.signal } ).catch(
	( error ) => {
		if ( error.name === 'AbortError' ) {
			console.log( 'Request has been aborted' );
		}
	}
);

controller?.abort();

For legacy browsers that don’t support AbortController, you can provide your own polyfill or ignore the aborting functionality as a progressive enhancement.

Middleware

The api-fetch package supports middleware functions that wrap apiFetch calls to perform pre/post processing.

Using Middleware

You can add custom middleware using the use() method:

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 ) + 'ms' );
	} );
	return result;
} );

apiFetch.use( middleware )

Registers a middleware function.

function

required

A function that receives options and next, and returns a Promise. The middleware should call next(options) to continue the chain.

Built-in Middleware

Nonce Middleware

The nonce middleware automatically adds authentication to your requests:

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

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

apiFetch.createNonceMiddleware( nonce )

Creates middleware that adds a nonce to requests for authentication.

string

required

The nonce value for authentication.

function

The middleware function with a nonce property that you can update with a fresh nonce value.

Root URL Middleware

The root URL middleware sets the base URL for API requests:

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

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

apiFetch.createRootURLMiddleware( rootURL )

Creates middleware that prepends the root URL to the path.

string

required

The REST API root URL.

Custom Fetch Handler

You can replace the default window.fetch with a custom handler using setFetchHandler():

apiFetch.setFetchHandler( handler )

Sets a custom fetch handler for making requests.

function

required

A function that receives the request options and returns a Promise.

Example 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,
	} );
} );

Version

Current version: 7.40.0

Core Packages

UI Components

Editor Implementations

Developer Tools

Utilities

@wordpress/api-fetch

API Fetch

Installation

Basic Usage

Making GET Requests

GET with Query Parameters

Making POST Requests

API Reference

apiFetch( options )

Options

Aborting Requests

Middleware

Using Middleware

apiFetch.use( middleware )

Built-in Middleware

Nonce Middleware

apiFetch.createNonceMiddleware( nonce )

Root URL Middleware

apiFetch.createRootURLMiddleware( rootURL )

Custom Fetch Handler

apiFetch.setFetchHandler( handler )

Example with Axios

Version

Links

​API Fetch

​Installation

​Basic Usage

​Making GET Requests

​GET with Query Parameters

​Making POST Requests

​API Reference

​apiFetch( options )

​Options

​Aborting Requests

​Middleware

​Using Middleware

​apiFetch.use( middleware )

​Built-in Middleware

​Nonce Middleware

​apiFetch.createNonceMiddleware( nonce )

​Root URL Middleware

​apiFetch.createRootURLMiddleware( rootURL )

​Custom Fetch Handler

​apiFetch.setFetchHandler( handler )

​Example with Axios

​Version

​Links

API Fetch

Installation

Basic Usage

Making GET Requests

GET with Query Parameters

Making POST Requests

API Reference

apiFetch( options )

Options

Aborting Requests

Middleware

Using Middleware

apiFetch.use( middleware )

Built-in Middleware

Nonce Middleware

apiFetch.createNonceMiddleware( nonce )

Root URL Middleware

apiFetch.createRootURLMiddleware( rootURL )

Custom Fetch Handler

apiFetch.setFetchHandler( handler )

Example with Axios

Version

Links