On the page describing the arguments to list users API, the description under search is:

Limit results to those matching a string.

I'd like to request this be clarified: what field (or fields?) are being searched when a parameter is provided? Username? First name? Last name? More? Some combination?

WordPress/gutenberg#9967 and WP Trac #39953 establish some nuances to how unspecified or "floating" dates are handled for draft posts. As we cannot go back in time and make unspecified dates return null, we should instead document this behavior (including how to identify floating dates and, if the ticket is accepted, how to revert a post to floating status).

I've read this doc for REST API authentication.

At the last chapter ( Authentication Plugins ), the doc suggest some plugins to extends authentication methods. But all the suggested plugins are outdated and not tested with recent versions of Wordpress...

Can you provide updated suggestions for Authenticating users with other methods than only cookies ?

As noted in #47, not all resources for which we generate the docs using a template are really comparable. Some require authentication, others require contextual overrides for things like the improperly named resources introduced by Gutenberg in order to be legible. We don't have a good way to support introducing these per-resource changes short of manually editing the generated files, which is not sustainable. We should come up with an alternative or more powerful templating solution, ideally.

From https://developer.wordpress.org/rest-api/reference/posts/#schema

apedog proposes,

Perhaps a small tutorial. Saying archives.php template translates to endpoint /rest/?my_archives=whatever/. And offer the non-dev wp user some common endpoints he might want to have a look at when installing his site.

Using existing WP concepts to establish what the API does would be a good way to introduce the endpoint usage section.

Per discussion in core Slack, it would be helpful to clarify some of the behavior around type coercion in the API.

Here's a bit of text to kick off the process. Feel free to modify :)

Because the REST API's schema validation needs to work in different contexts (such as query strings, JSON, etc.), being explicit and consistent with your schema types is very important.

Consequently, you might find that values are not always coerced — that is, automatically transformed between types — in the way you are used to in PHP, with its inherent type flexibility.

For example, if you use register_meta to register a piece of array meta containing a string property, but then store the value as an integer, the REST API is not able to safely convert the integer to a string. In this case, the API would return null instead of your array.

To solve this, you can use a prepare_callback to cast the value to the expected type, before it's validated against your schema.

For example, to store and retrieve an array of string IDs—which may also be saved in your database as integers—you might use the following:

register_meta(
	'post',
	'my_id_array',
	[
		'type'         => 'array',
		'single'       => true,
		'show_in_rest' => [
			'schema' => [
				'items' => [
					'type' => 'string',
				],
			],
			'prepare_callback' => function ( $value ) {
				return array_map(
					function ( $item ) {
						return (string) $item;
					},
					$value
				);
			},
		],
	]
);

This will ensure that integers are correctly transformed so the data matches the registered schema before the data is returned in the API response.

The layout of the handbook makes our generated documentation minimally-useful. mrMark in Slack proposes summarizing some pieces of information for each endpoint in the start of each reference page:

Is there any Chinese version of WP-API docs ? If not ,I hope the WordPress group add a button
to switch language like Morzilla's MDN, It's hopeful for all Chinese developer. Or anyone can edit it.
Thanks!

I've recently become super interested in using the backbone javascript client for some React-based settings pages but I'm finding it increasingly difficult to use. I feel like the documentation needs a bit of an update.

Specifically speaking this link here

Some of the problems I've noticed are as follows

Extending custom post types won't take the new URL root

Documentation specifies the following for custom post types

// Extend wp.api.models.Post and wp.api.collections.Posts to load a custom post type
const CustomPost = wp.api.models.Post.extend( {
  urlRoot: wpApiSettings.root + 'wp/v2/custom_post_slug',
  defaults: {
    type: 'custom_post_slug',
  },
} );

Yet when you extend the model and try save to the API it completely ignores the specified URL root.

Documentation relating to custom post type collections specifies an ambiguous type.

In the section relating to custom post type collections it mentions an ambiguous type 'BLProduct'. Is this supposed to be CustomPost?

const CustomPosts = wp.api.collections.Posts.extend( {
  url: wpApiSettings.root + 'wp/v2/custom_post_slug',
  model: BLProduct,
} );
const someCustomPosts = new CustomPosts();
someCustomPosts.fetch().then( ( posts ) => {
  // do something with the custom posts
} );

Some other minor issues I've discovered.

• No documentation on post.setMeta functions (they also seem to error out when doing so).
• No documentation on how to use the MetaData models
• Code does not appear to be open-sourced so debugging problems like these is really difficult

Backbone client seems like an extremely powerful and handy tool and I feel it really needs some attention and love from wordpress.

If a WordPress site has plain permalinks setting enabled, I believe this affects how you can call/access API routes (please correct me if I'm wrong).

This is the setting I'm referring to:

When plain permalinks are enabled (the default setting), the curl examples in the docs don't work. For example:

curl http://localhost:8222/wp-json/wp/v2/posts
<!DOCTYPE HTML PUBLIC "-//IETF//DTD HTML 2.0//EN">
<html><head>
<title>404 Not Found</title>
</head><body>
<h1>Not Found</h1>
<p>The requested URL was not found on this server.</p>
<hr>
<address>Apache/2.4.38 (Debian) Server at localhost Port 8222</address>
</body></html>

(The examples work fine with any other permalink option enabed.)

I think there might be other gotchas when WordPress is installed in subfolder on the server. It would be great to add a section to the docs outlining these potential gotchas for new developers.

This section could also include recommendations for how to set up your WordPress install so the examples work out of the box. (Note that plain permalinks is the default setting in WordPress.)

From: https://core.trac.wordpress.org/ticket/46201

When using the _embed query with REST API, embedded terms are limited to 10 in the response.
This is not described in the documentation.

Hi,

I'm working on an application to automate blog comments and responses. I've noticed an issue when attempting to post comments on a blog post. It seems there is a limit of 1 per 20 seconds? I don't have any documentation of this limit to refer to but it certainly seems to be happening.

I can add a comment normally, but then if I call with a different email/comment text/user_agent etc, it will give error: "400 Client Error: Bad Request for url: /wp-json/wp/v2/comments"

If I add a 20 second delay between the comment calls, it will no longer get that message, but it also grinds my application to a halt when working on a lot of blogs on the same site.

Can we get some documentation on what the rate limits are?

Do we have any options to adjust them on a site by site basis?

This will serve as a tracking ticket for making documentation changes to account for WordPress 5.4. We should aim to have these done before 5.4 ships on March 31.

• Review closed tickets in the 5.4 milestone to identify what needs special docs handling
• Update the Changelog page
• Regenerate the reference documentation
• Document how to regenerate the reference documentation (assigned to @kadamwhite)

PouchDB & Rust both have good documentation; what can we learn from their site structure?

When 5.3 ships we should update associated documentation. This will be a running list of things we should cover.

• Array & Object Metadata
• _fields nesting
• New media endpoint (with note it's really intended for internal use)
• Performance?
• Audit tickets to figure out what else is needed (report of closed tickets)
• Update Changelog

The inline code formatting is broken when it contains a URL: https://developer.wordpress.org/rest-api/extending-the-rest-api/routes-and-endpoints/

It is rendered fine in the GitHub preview: https://github.com/WP-API/docs/blob/master/extending-the-rest-api/routes-and-endpoints.md

Last year at WCEU, @kadamwhite took notes on how a typical REST API request works in WordPress from the top down. We need to get this into some actual form on the handbook.

This section and this section:

As of WordPress 4.9.8 it’s possible to use register_meta with the object_subtype argument that allows one to reduce the usage of the meta key to a particular post type.

And:

The register_meta function simplifies the process of defining a meta field for a particular object type. By setting 'show_in_rest' => true when registering a new meta key, that key will be accessible through the REST API. Note however that at this time there is no way to register a meta field for a specific post type: meta fields registered for the “post” object will appear on all custom post types, as well as the default post record.

I believe the second section referenced needs updating.

I couldn't find enough information with extensive googling about the different options available for f.ex. the args array so I ended up opening an issue to track about the register_rest_route() not working as expected. I was wrong. It worked as intended (imo) but it required quite a bit of digging to understand how it was intended to be used and what I was doing wrong.

It would be great to have the WP-API Handbook searchable in Dash.

Here is a link to submit although I'm not sure how to keep the docset in sync with updates:

https://kapeli.com/docsets

Thanks!

The REST API routes documentation hasn't been refreshed in some time. Its missing the "search" endpoint for instance.

https://make.xwp.co/2017/07/25/defining-context-in-the-wp-rest-api/ This article by Weston Ruter was cited by espellcaste in core slack, pointing out how little we clarify or explain the reasoning behind Context.

WordPress 5.5 is slated for release on August 11. We should aim to have our documentation updated before then. Previously #88.

• Review closed tickets in the 5.5 milestone to identify what needs special docs handling.
• Update the Changelog page.
• Regenerate the reference documentation.

This should not be nested under "using the API"

Docs don't show example of how to do this, I'm still trying to figure it out:

https://developer.wordpress.org/rest-api/using-the-rest-api/global-parameters/#_fields

I can't filter _embedded fields.

@rmccue - hope this is an okay place to post this. Would you like me to begin migrating some of the examples we started on during WCEU? I have made some additions since then as well:

https://github.com/JulienMelissas/wp-api-guides/

If so, let me know where you would like them.

If the document has the page how to use 'Search' related API, it would be great.

related ticket

For example,
I want to find the article with keyword Iphone only under Post CPT and Product CPT.

Only 'status=publish' is accepted by now. Other states as draft, future,... return 401

https://example.com/wp-json/wp/v2/posts?status=future

It'd be great to get '?status=any' back as well.

The REST v2 /posts endpoint reference documents its optional status argument as letting clients "Limit result set to posts assigned one or more statuses", but does not specify the syntax for a list of two or more statuses, nor whether specifying >= 2 statuses filters to posts containing all or any of the statuses.

I somehow or other guessed that comma-separated statuses in a single string (e.g. "publish,future,draft,pending,private,trash") would work (desiring the "posts with any of these statuses" interpretation) and it appears to, but some WordPress sites return me an HTTP Error 400 with JSON reply payload specifying "code": "rest_invalid_param" and "message": "Invalid parameter(s): status" for a request that that kind of status query parameter. I suspect that error can actually indicate that the user account does not have access permission for posts with some of the specified statuses, rather than necessarily indicating that the given status argument is intrinsically malformed or invalid, since TypeMetal tends to get that error when attempting REST communication with a self-hosted site that does not have a REST authentication plugin installed, but not after installing and activating a REST authentication plugin. Is that true? If so, should I be detecting by some means what set of statuses it's valid to request for the user account in question, and filtering my /posts requests to specify only those? (The reason I want to filter by status is to omit auto-draft posts. I suppose I could filter those out of received results instead, but that would waste bandwidth.)

Some clearer documentation of the status parameter's syntax, semantics, and security/permissions requirements (if any) would be very helpful.

Hi in https://developer.wordpress.org/rest-api/reference/ i found a broken link "https://demo.wp-api.org/"

We should mention that you can now use register_post_meta and that custom post types need to have custom-fields support enabled.

Related Trac ticket: https://core.trac.wordpress.org/ticket/40408

https://github.com/WP-API/docs/blob/master/extending-the-rest-api/modifying-responses.md#working-with-registered-meta-in-the-rest-api

did you remove filter method from your api?

The REST v2 /media endpoint reference would benefit from a mention of file content upload mechanics. The first technique documented in this gist I found (set the Content-Disposition HTTP header field to form-data; filename="thefile.jpg" and send the file's content as the HTTP body data) ended up working for me, but it would be helpful to have official documentation on this embedded in or linked from the /media endpoint reference.

https://make.wordpress.org/core/2021/06/29/rest-api-changes-in-wordpress-5-8/

It looks like backbone.js is the client side library for making calls to the WP REST API. The documentation shows how to have WordPress add that library to the page but there are many apps that use WordPress as a CMS.

Could a section be added on how to separate and use the library in an external application or client?

Consider the use case where Morgan is making a mobile app but wants to display the blog posts in that app. He wants to use JS library independently to get those posts and allow users to comment from the app.

https://developer.wordpress.org/rest-api/using-the-rest-api/backbone-javascript-client/

The REST API docs give endpoints and an explanation around how they work, but nowhere in the docs does it mention that you need to prepend your endpoints with /wp-json/.

For instance in the table on this page the endpoints are shown:

That list tells me I need to use www.domain.com/wp/v2/posts when in reality I need to use www.domain.com/wp-json/wp/v2/posts

I just faffed about for several hours wondering why the endpoint I was using direct from the endpoints index at www.domain.com/wp-json was giving me a 404, turns out I needed some esoteric, unexplained, internal knowledge about the API in order to perform a basic task.

Please make this much clearer in the docs - ideally by including it in any example endpoints you provide.

Hi,

Would be great to add support for posts "type" when creating a post with POST /wp/v2/posts

According to https://developer.wordpress.org/rest-api/reference/posts/#create-a-post "type" is not supported?

https://github.com/WordPress/Requests
https://github.com/madeITBelgium/WordPress-PHP-SDK

Per discussion in core slack, it's not obvious how to take advantage of the selective inclusion field logic. This should be documented in "extending the API" under writing your own endpoints.

In the The Controller Pattern section on the Adding Custom Endpoints page, there's an anchor link for Extending Internal Classes that doesn't point to an existing anchor on the target page.

https://developer.wordpress.org/rest-api/reference/posts/#retrieve-a-post

I was researching how to authenticate a WP REST API which access had been restricted by reading the docs here https://developer.wordpress.org/rest-api/using-the-rest-api/authentication/

After a bit more research I stumble upon this post by @georgestephanis and that the feature was added in end of year 2020 in 5.6

Did I miss something or is this feature indeed not mentionned in the developer docs? How can I help? (again, I'm just discovering the feature now)

Maybe not the right repo?

I'm seeing formatting errors for special characters in the documentation due to translation of & to &. Single quote ends up as '

Tested in Safari and Chrome

The obvious way to update e.g. https://developer.wordpress.org/rest-api/extending-the-rest-api/modifying-responses/ is to edit the page from within WordPress. While moving this content into GitHub would allow easier contribution from the community, we need to be careful not to overwrite edits made from within the WP site.

A couple of potential options:

• Somehow detect changes to the content and warn/error before overwriting it.
• Some kind of sync thingy to go from HTML back to Markdown.
• Disable editing via the WP interface.

I found this page: https://developer.wordpress.org/rest-api/requests/ through a Google search but I can't see it in the REST API handbook's sidebar navigation.

doesn't need to be nested

did someone remove menus as reference path in API?!

Proposals from docs-focused API team meeting on Jan 2, 2020:

• Move Key Concepts into its own page
• Add some API basics:
  • The API exposes information about your site, but also provides a toolkit for creating your own endpoints; it's a REST API and a set of PHP api's for building a REST API, basically
  • Security misconceptions: we expose public data, accessible from anywhere (link to FAQ for lockdown maybe) and require authentication for sensitive data
  • Explain meta must be explicitly registered (link to that page in "extending")
• Demote technical content on the page and open with the usage rationale