Global Request Parameters

In the REST API, in addition to specific request parameters for a particular route, there are global parameters and pagination parameters. There are also some nuances related to request parameters. We will examine all of this in this section of the guide.

Global Parameters (developer.wordpress.org)

Contents:

Global Parameters
_fields (response fields)
_method (specifying the request method)
_envelope (envelope mode)
_embed (embedding mode)
_jsonp (cross-domain requests)
Pagination/Sorting Parameters
Pagination Parameters
Sorting Parameters
Why do request parameters not work?
What happened to the request parameter ?filter=?

Global Parameters

In the REST API, there are global parameters (meta-parameters). They control how the API processes requests/responses. They operate at a level above the resources themselves and are available for all routes (endpoints).

All such parameters start with an underscore _.

Global parameters are implemented in REST API routes as query string parameters. Query strings begin with the ? character, followed by a series of key=value pairs, separated by the & character.

For example, take the endpoint GET /wp-json/wp/v2/posts. By default, all available post fields are returned.

However, you can add the global parameter _fields, and then specify the fields you want to return GET wp-json/wp/v2/posts?_fields=author,id,excerpt,title,link. Making the request now will return only the specified fields in the response.

_fields (response fields)

The Post resource in REST contains a large amount of data: title, author ID, registered meta-information, fields, media, links to other resources, etc.

To specify that WordPress should return only specific fields in the response, you can use the _fields parameter. For example, if you are creating an archive output and you only need: ID, title, link, author, and excerpt, you can limit the response like this:

/wp/v2/posts?_fields=id,title,link,author,excerpt

You can also use an array of parameters instead of a comma-separated list:

/wp/v2/posts?_fields[]=author&_fields[]=id&_fields[]=excerpt&_fields[]=title&_fields[]=link

When _fields is specified, WordPress will skip fields when creating the response object, avoiding potentially expensive internal computations or queries for data that you do not need. This also means that the JSON object returned from the REST API will be smaller, requiring less time to load and parse.

Nested properties

Since WordPress 5.3, the _fields parameter supports nested properties. This can be useful if you have registered many meta-fields, allowing you to request the value for only one of the registered meta-fields:

?_fields=meta.one-of-many-keys

Only the value of the meta with the key one-of-many-keys will be returned, while the others will be excluded.

You can also request specific deeply nested properties within a complex meta-object:

?_fields=meta.key_name.nested_prop.deeply_nested_prop,meta.key_name.other_nested_prop

_method (specifying the request method)

When the server cannot handle or the client cannot send a non-standard HTTP method, the method can be specified in the request parameter _method or in the request header X-HTTP-Method-Override.

For example, delete requests use the DELETE method, but some clients cannot send this method. In this case, the method can be specified in the URL by adding ?_method=DELETE or in the request header X-HTTP-Method-Override=DELETE and send a POST request, and the REST API will process such a request as if it were made using the DELETE method.

Only POST requests are suitable for overriding the method. Because GET requests can be cached.

Example of method overriding

POST http://example.com/wp-json/wp/v2/posts/42?_method=DELETE

Or we can specify the method in the header of the request:

POST /wp-json/wp/v2/posts/42 HTTP/1.1
Host: example.com
X-HTTP-Method-Override: DELETE

The REST API will process such requests as a DELETE endpoint.

_envelope (envelope mode)

When the client application cannot receive HTTP response data, it can be passed in the body of the response (in a JSON object), for this, the parameter _envelope needs to be set. Thus, the response body will contain the response status code and other headers.

For the parameter, it is not necessary to specify a value; it can simply be defined. That is, you can just add ?_envelope to the GET request. Or you can specify the value 1 - ?_envelope=1, if the client application requires it, the result will be the same.

The _envelope response does not contain all header parameters, only the response status and some headers.

Example

Let's send a regular request:

GET http://example.com/wp-json/wp/v2/users/1

{
	"id": 1,
	"name": "kama",
	"url": "",
	"description": "",
	"link": "http://example.com/author/kama/",
	"slug": "kama",
	"avatar_urls": {
		"24": "http://1.gravatar.com/avatar/155e695ab2251ee3c482c1e3e690683b?s=24&d=mm&r=g"
	}
}

Now let's send a request with ?_envelope:

GET http://example.com/wp-json/wp/v2/users/1?_envelope

{
	"id": 1,
	"name": "kama",
	"url": "",
	"description": "",
	"link": "http://example.com/author/kama/",
	"slug": "kama",
	"avatar_urls": {
		"24": "http://1.gravatar.com/avatar/155e695ab2251ee3c482c1e3e690683b?s=24&d=mm&r=g"
	},
	"status": 200,
	"headers": {
		"Allow": "GET"
	}
}

_embed (embedding mode)

Many responses contain links to related resources (routes) that are located under the _links key. For example, a post may contain a link to a parent post or a link to comments on the post. Some of these resources can be embedded to reduce the number of HTTP requests. Thus, clients can get the resource itself, as well as related data in one request. To do this, the parameter ?_embed must be specified in the request.

_embed passed in the GET request includes embedding mode.

For the parameter, it is not necessary to specify a value; it can simply be defined. That is, you can just add ?_embed to the GET request. Or you can specify the value 1 - ?_embed=1, if the client application requires it.

Responses in "embedding" mode will contain an additional key _embedded, which will contain the data of related resources (routes). For it to be embedded, it must have the property embeddable = true.

For more details on embedding, read in the corresponding section of the guide.

_jsonp (cross-domain requests)

The REST API supports JSONP responses to allow cross-domain requests (between different domains) for outdated browsers and clients. In this parameter, you need to specify the name of the JavaScript callback function. The response will be wrapped in the specified function so that the URL can then be loaded using the <script> tag.

The callback function (the value of the parameter) can contain letters, numbers, _ or .: [a-zA-Z0-9_.]. If an incorrect function name is specified, we will receive a response with HTTP 400 error and the callback will not be called.

Example:

<script>
function receiveData( data ){
  // do something with the data.
  // output the data to the console.
  console.log( data );
}
</script>
<script src="https://demo.wp-api.org/wp-json/?_jsonp=receiveData"></script>

https://demo.wp-api.org/wp-json/?_jsonp=receiveData will return:

receiveData(
	{
		"name": "WP REST API Demo",
		"description": "Just another WP API Demo Sites site",
		"url": "https://demo.wp-api.org",
		"home": "https://demo.wp-api.org",
		"gmt_offset": "0",
		"timezone_string": "",
		"permalink_structure": "/%year%/%monthnum%/%day%/%postname%/",
		"namespaces": [
			"oembed/1.0",
			"broker/v1",
			"wp/v2"
		],
		...
	}
)

For modern browsers and applications, the _jsonp parameter is not needed! Modern browsers can handle Cross-Origin Resource Sharing (CORS) requests for cross-domain requests, and JSONP is needed to support all browsers.

Pagination/Sorting Parameters

There may be a lot of content on the site, and therefore in the REST API it is divided into parts (only part of the content can be obtained in one request). Endpoints by default return a limited number of items per request. Similar to how 10 records are displayed on one page of a category.

The REST API also has pagination, which is controlled by common parameters that can be specified for routes with collections of items (containing multiple items).

Pagination Parameters

?page=

Specifies which pagination page needs to be obtained.

For example: /wp/v2/posts?page=2 will return the second page of posts. By gathering data from endpoints: /wp/v2/posts, /wp/v2/posts?page=2, etc., you can collect all posts on the site.

?per_page=

Specifies how many items need to be displayed on one pagination page. Cannot be more than 100.

For example: /wp/v2/posts?per_page=1 will get only the first post of all possible.

?offset=

Specifies the offset (from the top) from which to start obtaining items.

For example: /wp/v2/posts?offset=6 will use the default number of items per request but will start obtaining them after skipping the first 6 posts.

Combining Parameters

Parameters can be specified simultaneously to get the desired result. Only this should be logical.

/wp/v2/posts?per_page=5&page=4 - will get 5 records from the 4th pagination page.
/wp/v2/posts?per_page=5&offset=15 - will get 5 records skipping 15. This is the same as the previous option.

Large requests can reduce site performance, so per_page is limited to 100 records. If you need to obtain more than 100 records, for example, to create a list of all available categories, you will have to make several requests and combine the results into one.

How much data is there in total

To determine how many pages of data exist, the API returns two fields in the response headers:

X-WP-Total: The total number of records in the collection
X-WP-TotalPages: The total number of pages covering all available records

Sorting Parameters

The REST API allows sorting results by specified fields of the item. There are several parameters for this:

?order=

Specifies how to sort. Can be:

asc - ascending order - ?order=asc
desc - descending order - ?order=desc

Default: desc

?orderby=

Specifies the field by which to sort. The values of the parameter vary depending on the route, for example:

/wp/v2/posts - author, date, id, include, modified, parent, relevance, slug, title.
/wp/v2/categories - id, include, name, slug, term_group, description, count

For other collections, see the sections on obtaining lists by route in the section WP Routes Out of the Box.

Default: date (for all routes of items that have dates)

Why do request parameters not work?

If parameters like: ?page=2 or ?_embed do not affect the result in any way, it may mean that your server is configured differently and cannot determine them. If Nginx is used to serve requests, try to find the line try_files in the configuration file, and if the line looks like this:

try_files $uri $uri/ /index.php$args;

then it needs to be changed to:

try_files $uri $uri/ /index.php$is_args$args;

The variable $is_args will add a ?, if there are query parameters, this will allow WordPress to correctly determine the request parameters.

What happened to the request parameter `?filter=`?

When the REST API was integrated into the core of WP, the request parameter ?filter was removed to prevent compatibility and maintenance issues in the future.

The ability to pass filtering arguments in the ?filter parameter was needed at the very beginning of the creation of the REST API (when it was still a separate plugin). And almost all request parameters were replaced with more stable ones: ?categories=, ?slug= and ?per_page=.

Whenever possible, it is recommended to use the native request parameters!

Restoring the request parameter ?filter in the REST API is possible with the rest-filter plugin.