@wordpress/api-fetch

What is @wordpress/api-fetch?

@wordpress/api-fetch is a package designed to facilitate making HTTP requests to the WordPress REST API. It provides a set of utilities to handle common tasks such as authentication, nonce handling, and error handling, making it easier to interact with WordPress data from JavaScript applications.

What are @wordpress/api-fetch's main functionalities?

Basic GET Request

This feature allows you to make a basic GET request to the WordPress REST API to fetch a list of posts.

const apiFetch = require('@wordpress/api-fetch');

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

Authenticated Request

This feature demonstrates how to make an authenticated request using a nonce. It shows how to create a new post by sending a POST request.

const apiFetch = require('@wordpress/api-fetch');

apiFetch.use(apiFetch.createNonceMiddleware('your-nonce-here'));

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

Custom Middleware

This feature shows how to add custom middleware to modify requests. In this example, a custom header is added to all requests.

const apiFetch = require('@wordpress/api-fetch');

const customMiddleware = (options, next) => {
  options.headers = {
    ...options.headers,
    'X-Custom-Header': 'CustomValue'
  };
  return next(options);
};

apiFetch.use(customMiddleware);

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

Other packages similar to @wordpress/api-fetch

axios

Axios is a popular promise-based HTTP client for the browser and Node.js. It provides a simple API for making HTTP requests and supports features like interceptors, automatic JSON transformation, and request cancellation. Compared to @wordpress/api-fetch, Axios is more general-purpose and not specifically tailored for WordPress.

fetch

Fetch is a native JavaScript API for making HTTP requests. It is built into modern browsers and provides a simple and flexible interface for fetching resources. Unlike @wordpress/api-fetch, Fetch does not include built-in support for WordPress-specific features like nonce handling or custom middleware.

superagent

Superagent is a small, progressive client-side HTTP request library. It has a simple API and supports features like query string parsing, automatic JSON response parsing, and request retries. While it is versatile, it does not offer the WordPress-specific utilities provided by @wordpress/api-fetch.

README

API Fetch

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

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 such language features and APIs, you should include the polyfill shipped in @wordpress/babel-preset-default in your code.

Usage

GET

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

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

GET with Query Args

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

POST

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

Options

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

Additionally, the following options are available:

path (string)

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

url (string)

Absolute URL to the endpoint from which to fetch.

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.

data (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.

Aborting a request

Aborting a request can be achieved through the use of AbortController in the same way as you would when using the native fetch API.

For legacy browsers that don't support AbortController, you can either:

• Provide your own polyfill of AbortController if you still want it to be abortable.
• Ignore it as shown in the example below.

Example

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

apiFetch( { path: '/wp/v2/posts', signal: controller?.signal } ).catch(
	( error ) => {
		// If the browser doesn't support AbortController then the code below will never log.
		// However, in most cases this should be fine as it can be considered to be a progressive enhancement.
		if ( error.name === 'AbortError' ) {
			console.log( 'Request has been aborted' );
		}
	}
);

controller?.abort();

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

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 ) );

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

Contributing to this package

This is an individual package that's part of the Gutenberg project. The project is organized as a monorepo. It's made up of multiple self-contained software packages, each with a specific purpose. The packages in this monorepo are published to npm and used by WordPress as well as other software projects.

To find out more about contributing to this package or Gutenberg as a whole, please read the project's main contributor guide.