@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 such language features and APIs, you should include the polyfill shipped in @wordpress/babel-preset-default
in your code.
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.
url
(string
) url
(string
)
Absolute URL to the endpoint from which to fetch.
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
.
data
(object
) data
(object
)
Shorthand to be used in place of body
, accepts an object value to be stringified to JSON.
Aborting a request 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 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 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 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, } ); } );