WPRequest - Documentation

new WPRequest(options)

WPRequest is the base API request object constructor

Source:

lib/constructors/wp-request.js, line 12

Parameters:

Name Type Description

options

Object

A hash of options for the WPRequest instance

Name	Type	Attributes	Description
`endpoint`	`String`		The endpoint URI for the invoking WPAPI instance
`transport`	`Object`		An object of http transport methods (get, post, etc)
`username`	`String`	<optional>	A username for authenticating API requests
`password`	`String`	<optional>	A password for authenticating API requests
`nonce`	`String`	<optional>	A WP nonce for use with cookie authentication

Methods

auth(credentials) → {WPRequest}

Set a request to use authentication, and optionally provide auth credentials

If auth credentials were already specified when the WPAPI instance was created, calling .auth on the request chain will set that request to use the existing credentials:

Source:

lib/constructors/wp-request.js, line 599

Parameters:

Name Type Description

credentials

Object

An object with 'username' and 'password' string properties, or else a 'nonce' property

Name	Type	Attributes	Description
`username`	`String`	<optional>	A WP-API Basic HTTP Authentication username
`password`	`String`	<optional>	A WP-API Basic HTTP Authentication password
`nonce`	`String`	<optional>	A WP nonce for use with cookie authentication

Returns:

Type:: WPRequest

The WPRequest instance (for chaining)

Examples

use existing credentials

    request.auth().get...

Alternatively, a username & password (or nonce) can be explicitly passed into `.auth`:

use explicit basic authentication credentials

    request.auth({
      username: 'admin',
      password: 'super secure'
    }).get...

use a nonce for cookie authentication

    request.auth({
      nonce: 'somenonce'
    })...

context(context) → {WPRequest}

Set the context of the request. Used primarily to expose private values on a request object by setting the context to "edit".

Source:

lib/constructors/wp-request.js, line 421

Parameters:

Name	Type	Description
`context`	`String`	The context to set on the request

Returns:

Type:: WPRequest

The WPRequest instance (for chaining)

create(data, callbackopt) → {Promise}

Create the specified resource with the provided data

This is the public interface for creating POST requests

Source:

lib/constructors/wp-request.js, line 725

Parameters:

Name	Type	Attributes	Description
`data`	`Object`		The data for the POST request
`callback`	`function`	<optional>	A callback to invoke with the results of the POST request

Returns:

Type:: Promise

A promise to the results of the HTTP request

delete(dataopt, callbackopt) → {Promise}

Delete the specified resource

Source:

lib/constructors/wp-request.js, line 754

Parameters:

Name	Type	Attributes	Description
`data`	`Object`	<optional>	Data to send along with the DELETE request
`callback`	`function`	<optional>	A callback to invoke with the results of the DELETE request

Returns:

Type:: Promise

A promise to the results of the HTTP request

edit() → {WPRequest}

Convenience wrapper for .context( 'edit' )

Source:

lib/constructors/wp-request.js, line 430

Returns:

Type:: WPRequest

The WPRequest instance (for chaining)

embed() → {WPRequest}

Return embedded resources as part of the response payload.

Source:

lib/constructors/wp-request.js, line 441

Returns:

Type:: WPRequest

The WPRequest instance (for chaining)

exclude(ids)

Exclude specific resource IDs in the response collection.

Source:

lib/constructors/wp-request.js, line 532

Parameters:

Name	Type	Description
`ids`	`Number` \| `Array.<Number>`	An ID or array of IDs to exclude

Returns:

The request instance (for chaining)

file(file, nameopt) → {WPRequest}

Specify a file or a file buffer to attach to the request, for use when creating a new Media item

Source:

lib/constructors/wp-request.js, line 645

Parameters:

Name	Type	Attributes	Description
`file`	`string` \| `object`		A path to a file (in Node) or an file object (Node or Browser) to attach to the request
`name`	`string`	<optional>	An (optional) filename to use for the file

Returns:

Type:: WPRequest

The WPRequest instance (for chaining)

Examples

within a server context

    wp.media()
      // Pass .file() the file system path to a file to upload
      .file( '/path/to/file.jpg' )
      .create({})...

within a browser context

    wp.media()
      // Pass .file() the file reference from an HTML file input
      .file( document.querySelector( 'input[type="file"]' ).files[0] )
      .create({})...

get(callbackopt) → {Promise}

Get (download the data for) the specified resource

Source:

lib/constructors/wp-request.js, line 698

Parameters:

Name	Type	Attributes	Description
`callback`	`function`	<optional>	A callback to invoke with the results of the GET request

Returns:

Type:: Promise

A promise to the results of the HTTP request

headers(callbackopt) → {Promise}

Get the headers for the specified resource

Source:

lib/constructors/wp-request.js, line 710

Parameters:

Name	Type	Attributes	Description
`callback`	`function`	<optional>	A callback to invoke with the results of the HEAD request

Returns:

Type:: Promise

A promise to the header results of the HTTP request

include(ids)

Include specific resource IDs in the response collection.

Source:

lib/constructors/wp-request.js, line 522

Parameters:

Name	Type	Description
`ids`	`Number` \| `Array.<Number>`	An ID or array of IDs to include

Returns:

The request instance (for chaining)

namespace(namespace) → {WPRequest}

Set the namespace of the request, e.g. to specify the API root for routes registered by wp core v2 ("wp/v2") or by any given plugin. Any previously- set namespace will be overwritten by subsequent calls to the method.

Source:

lib/constructors/wp-request.js, line 560

Parameters:

Name	Type	Description
`namespace`	`String`	A namespace string, e.g. "wp/v2"

Returns:

Type:: WPRequest

The WPRequest instance (for chaining)

offset(offsetNumber)

Set an arbitrary offset to retrieve items from a specific point in a collection.

Source:

lib/constructors/wp-request.js, line 478

Parameters:

Name	Type	Description
`offsetNumber`	`Number`	The number of items by which to offset the response

Returns:

The request instance (for chaining)

order(direction)

Change the sort direction of a returned collection

Source:

lib/constructors/wp-request.js, line 492

Parameters:

Name	Type	Description
`direction`	`String`	The order to use when sorting the response

Returns:

The request instance (for chaining)

Example

order comments chronologically (oldest first)

    site.comments().order( 'asc' )...

orderby(field)

Order a collection by a specific field

Source:

lib/constructors/wp-request.js, line 502

Parameters:

Name	Type	Description
`field`	`String`	The field by which to order the response

Returns:

The request instance (for chaining)

page(pageNumber)

Set the pagination of a request. Use in conjunction with .perPage() for explicit pagination handling. (The number of pages in a response can be retrieved from the response's _paging.totalPages property.)

Source:

lib/constructors/wp-request.js, line 458

Parameters:

Name	Type	Description
`pageNumber`	`Number`	The page number of results to retrieve

Returns:

The request instance (for chaining)

param(props, valueopt) → {WPRequest}

Set a parameter to render into the final query URI.

Source:

lib/constructors/wp-request.js, line 381

Parameters:

Name	Type	Attributes	Description
`props`	`String` \| `Object`		The name of the parameter to set, or an object containing parameter keys and their corresponding values
`value`	`String` \| `Number` \| `Array`	<optional>	The value of the parameter being set

Returns:

Type:: WPRequest

The WPRequest instance (for chaining)

perPage(itemsPerPage)

Set the number of items to be returned in a page of responses.

Source:

lib/constructors/wp-request.js, line 468

Parameters:

Name	Type	Description
`itemsPerPage`	`Number`	The number of items to return in one page of results

Returns:

The request instance (for chaining)

search(searchString)

Filter results to those matching the specified search terms.

Source:

lib/constructors/wp-request.js, line 512

Parameters:

Name	Type	Description
`searchString`	`String`	A string to search for within post content

Returns:

The request instance (for chaining)

setHeaders(headers, valueopt) → {WPRequest}

Specify one or more headers to send with the dispatched HTTP request.

Since:

1.1.0

Source:

lib/constructors/wp-request.js, line 678

Parameters:

Name	Type	Attributes	Description
`headers`	`String` \| `Object`		The name of the header to set, or an object of header names and their associated string values
`value`	`String`	<optional>	The value of the header being set

Returns:

Type:: WPRequest

The WPRequest instance (for chaining)

Examples

Set a single header to be used on this request

    request.setHeaders( 'Authorization', 'Bearer trustme' )...

Set multiple headers to be used by this request

    request.setHeaders({
      Authorization: 'Bearer comeonwereoldfriendsright',
      'Accept-Language': 'en-CA'
    })...

setPathPart(level, val) → {WPRequest}

Set a component of the resource URL itself (as opposed to a query parameter)

If a path component has already been set at this level, throw an error: requests are meant to be transient, so any re-writing of a previously-set path part value is likely to be a mistake.

Source:

lib/constructors/wp-request.js, line 307

Parameters:

Name	Type	Description
`level`	`Number` \| `String`	A "level" of the path to set, e.g. "1" or "2"
`val`	`Number` \| `String`	The value to set at that path part level

Returns:

Type:: WPRequest

The WPRequest instance (for chaining)

slug(slug)

Query a collection for members with a specific slug.

Source:

lib/constructors/wp-request.js, line 542

Parameters:

Name	Type	Description
`slug`	`String`	A post slug (slug), e.g. "hello-world"

Returns:

The request instance (for chaining)

then(successCallbackopt, failureCallbackopt) → {Promise}

Calling .then on a query chain will invoke the query as a GET and return a promise

Source:

lib/constructors/wp-request.js, line 767

Parameters:

Name	Type	Attributes	Description
`successCallback`	`function`	<optional>	A callback to handle the data returned from the GET request
`failureCallback`	`function`	<optional>	A callback to handle any errors encountered by the request

Returns:

Type:: Promise

A promise to the results of the HTTP request

toString() → {String}

Parse the request into a WordPress API request URI string

Source:

lib/constructors/wp-request.js, line 284

Returns:

Type:: String

The URI for the HTTP request to be sent

validatePath() → {WPRequest}

Validate whether the specified path parts are valid for this endpoint

"Path parts" are non-query-string URL segments, like "some" "path" in the URL mydomain.com/some/path?and=a&query=string&too. Because a well-formed path is necessary to execute a successful API request, we throw an error if the user has omitted a value (such as /some/[missing component]/url) or has provided a path part value that does not match the regular expression the API uses to goven that segment.

Source:

lib/constructors/wp-request.js, line 330

Returns:

Type:: WPRequest

The WPRequest instance (for chaining), if no errors were found