Skip to content

Commit 7138033

Browse files
kadamwhitekadamwhite
committed
Merge branch 'master' into pr/32
2 parents f70426c + cb385ff commit 7138033

35 files changed

+2263
-137
lines changed

‎bin/manifest.json‎

Lines changed: 25 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -109,6 +109,16 @@
109109
"parent": "reference",
110110
"markdown_source": "https://github.com/WP-API/docs/blob/master/reference/posts.md"
111111
},
112+
"reference/rendered-blocks": {
113+
"slug": "rendered-blocks",
114+
"parent": "reference",
115+
"markdown_source": "https://github.com/WP-API/docs/blob/master/reference/rendered-blocks.md"
116+
},
117+
"reference/search-results": {
118+
"slug": "search-results",
119+
"parent": "reference",
120+
"markdown_source": "https://github.com/WP-API/docs/blob/master/reference/search-results.md"
121+
},
112122
"reference/settings": {
113123
"slug": "settings",
114124
"parent": "reference",
@@ -124,11 +134,26 @@
124134
"parent": "reference",
125135
"markdown_source": "https://github.com/WP-API/docs/blob/master/reference/taxonomies.md"
126136
},
137+
"reference/themes": {
138+
"slug": "themes",
139+
"parent": "reference",
140+
"markdown_source": "https://github.com/WP-API/docs/blob/master/reference/themes.md"
141+
},
127142
"reference/users": {
128143
"slug": "users",
129144
"parent": "reference",
130145
"markdown_source": "https://github.com/WP-API/docs/blob/master/reference/users.md"
131146
},
147+
"reference/wp_block-revisions": {
148+
"slug": "wp_block-revisions",
149+
"parent": "reference",
150+
"markdown_source": "https://github.com/WP-API/docs/blob/master/reference/wp_block-revisions.md"
151+
},
152+
"reference/wp_blocks": {
153+
"slug": "wp_blocks",
154+
"parent": "reference",
155+
"markdown_source": "https://github.com/WP-API/docs/blob/master/reference/wp_blocks.md"
156+
},
132157
"using-the-rest-api/authentication": {
133158
"slug": "authentication",
134159
"parent": "using-the-rest-api",

‎bin/regenerate.php‎

100644100755
Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,3 +1,4 @@
1+
#!/usr/bin/env php
12
<?php
23

34
require dirname( __DIR__ ) . '/vendor/autoload.php';

‎bin/templates/endpoint.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -10,7 +10,7 @@
1010
<div class="secondary">
1111
<h3>Example Request</h3>
1212

13-
<code>$ curl -X OPTIONS -i http://demo.wp-api.org/wp-json{{ attribute( routes | first, 'nicename' ) }}</code>
13+
<code>$ curl -X OPTIONS -i https://example.com/wp-json{{ attribute( routes | first, 'nicename' ) }}</code>
1414
</div>
1515
</section>
1616

‎bin/templates/reference-parts/delete-item.html‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -10,6 +10,6 @@ <h3>Definition</h3>
1010

1111
<h3>Example Request</h3>
1212

13-
<code>$ curl -X DELETE http://demo.wp-api.org/wp-json{{ route.nicename }}</code>
13+
<code>$ curl -X DELETE https://example.com/wp-json{{ route.nicename }}</code>
1414
</div>
1515
</section>

‎bin/templates/reference-parts/examples/update-post-curl.html‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1 +1 @@
1-
$ curl -X POST http://demo.wp-api.org/wp-json{{ route.nicename }} -d '{"title":"My New Title"}'
1+
$ curl -X POST https://example.com/wp-json{{ route.nicename }} -d '{"title":"My New Title"}'

‎bin/templates/reference-parts/get-item.html‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -10,6 +10,6 @@ <h3>Definition</h3>
1010

1111
<h3>Example Request</h3>
1212

13-
<code>$ curl http://demo.wp-api.org/wp-json{{ route.nicename }}</code>
13+
<code>$ curl https://example.com/wp-json{{ route.nicename }}</code>
1414
</div>
1515
</section>

‎bin/templates/reference-parts/list-item.html‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -10,6 +10,6 @@ <h3>Definition</h3>
1010

1111
<h3>Example Request</h3>
1212

13-
<code>$ curl http://demo.wp-api.org/wp-json{{ route.nicename }}</code>
13+
<code>$ curl https://example.com/wp-json{{ route.nicename }}</code>
1414
</div>
1515
</section>

‎extending-the-rest-api/adding-custom-endpoints.md‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -213,6 +213,8 @@ This callback can be registered as `permission_callback`, again in the endpoint
213213

214214
The permissions callback is run after remote authentication, which sets the current user. This means you can use `current_user_can` to check if the user that has been authenticated has the appropriate capability for the action, or any other check based on current user ID. Where possible, you should always use `current_user_can`; instead of checking if the user is logged in (authentication), check whether they can perform the action (authorization).
215215

216+
Once you register a `permission_callback`, you will need to authenticate your requests (for example by including a nonce parameter) or you will receive a `rest_forbidden` error. See [Authentication](https://developer.wordpress.org/rest-api/using-the-rest-api/authentication/) for more details.
217+
216218
Continuing with our previous example, we can make it so that only editors or above can view this author data. We can check a number of different capabilities here, but the best is `edit_others_posts`, which is really the core of what an editor is. To do this, we just need a callback here:
217219

218220
```php

‎extending-the-rest-api/modifying-responses.md‎

Lines changed: 17 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -34,7 +34,7 @@ There are two methods which can be used to add data to WordPress REST API respon
3434
Prior WordPress 4.9.8, meta fields set to `show_in_rest` using `register_meta` are registered for all objects of a given type. If one custom post type shows a meta field, all custom post types will show that meta field. 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.
3535
[/alert]
3636

37-
The disadvantage of `register_meta` is that it can only handle scalar values wehreas `register_rest_field` can handle other object types as well.
37+
The disadvantage of `register_meta` is that it can only handle scalar values whereas `register_rest_field` can handle other object types as well.
3838

3939

4040
## Adding Custom Fields to API Responses
@@ -100,8 +100,7 @@ For each object type &mdash; posts, or users, terms, comments, etc. &mdash; `$wp
100100

101101
## Working with registered meta in the REST API
102102

103-
The [`register_meta`](https://developer.wordpress.org/reference/functions/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. For this reason it is less broadly useful than `register_rest_field`.
104-
103+
The [`register_meta`](https://developer.wordpress.org/reference/functions/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.
105104

106105
### Read and write a post meta field in post responses
107106

@@ -111,7 +110,7 @@ The [`register_meta`](https://developer.wordpress.org/reference/functions/regist
111110
// for custom comment types, this is 'comment'. For user meta,
112111
// this is 'user'.
113112
$object_type = 'post';
114-
$args1 = array( // Validate and sanitize the meta value.
113+
$meta_args = array( // Validate and sanitize the meta value.
115114
// Note: currently (4.7) one of 'string', 'boolean', 'integer',
116115
// 'number' must be used as 'type'. The default is 'string'.
117116
'type' => 'string',
@@ -122,13 +121,26 @@ $args1 = array( // Validate and sanitize the meta value.
122121
// Show in the WP REST API response. Default: false.
123122
'show_in_rest' => true,
124123
);
125-
register_meta( $object_type, 'my_meta_key', $args1 );
124+
register_meta( $object_type, 'my_meta_key', $meta_args );
126125
```
127126

128127
This example shows how to allow reading and writing of a post meta field. This will allow that field to be updated via a POST request to `wp-json/wp/v2/posts/<post-id>` or created along with a post via a POST request to `wp-json/wp/v2/posts/`.
129128

130129
Note that for meta fields registered on custom post types, the post type must have `custom-fields` support. Otherwise the meta fields will not appear in the REST API.
131130

131+
### Post Type Specific Meta
132+
WordPress 4.9.8 adds support for registering meta for a specific post type or taxonomy by using the `register_post_meta` and `register_term_meta` functions. They follow the same rules as `register_meta` but accept a post type or taxonomy as their first parameter instead of an object type. The following code would register the `my_meta_key` example above, but only for the `page` custom post type.
133+
134+
```php
135+
$meta_args = array(
136+
'type' => 'string',
137+
'description' => 'A meta key associated with a string meta value.',
138+
'single' => true,
139+
'show_in_rest' => true,
140+
);
141+
register_post_meta( 'page', 'my_meta_key', $meta_args );
142+
```
143+
132144

133145
## Adding Links to the API Response
134146
WordPress generates a list of links associated with the queried resource to make it easier to navigate to related resources.

‎index.md‎

Lines changed: 10 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -1,19 +1,22 @@
11
# REST API Handbook
22

3-
The WordPress REST API provides API endpoints for WordPress data types that allow developers to interact with sites remotely by sending and receiving [JSON](https://en.wikipedia.org/wiki/JSON) (JavaScript Object Notation) objects. JSON is an open standard data format that is lightweight and human-readable, and looks like Objects do in JavaScript; hence the name. When you send content to or make a request to the API, the response will be returned in JSON. This enables developers to create, read and update WordPress content from client-side JavaScript or from external applications, even those written in languages beyond PHP.
3+
The WordPress REST API provides an interface for applications to interact with your WordPress site by sending and receiving data as [JSON](https://en.wikipedia.org/wiki/JSON) (JavaScript Object Notation) objects. It is the foundation of the [WordPress Block Editor](https://developer.wordpress.org/block-editor/), and can likewise enable your theme, plugin or custom application to present new, powerful interfaces for managing and publishing your site content.
44

5-
[info]Looking for a list of the other APIs available within WordPress? You can find the <a href="https://codex.wordpress.org/WordPress_APIs">documentation here</a>.[/info]
5+
An API is an Application Programming Interface. REST, standing for "REpresentational State Transfer," is a set of concepts for modeling and accessing your application's data as interrelated objects and collections. The WordPress REST API provides REST endpoints (URLs) representing the posts, pages, taxonomies, and other built-in WordPress data types. Your application can send and receive JSON data to these endpoints to query, modify & create content on your site. JSON is an open standard data format that is lightweight and human-readable, and looks like Objects do in JavaScript. When you request content from or send content to the API, the response will also be returned in JSON. Because JSON is widely supported in many programming languages, developers can build WordPress applications in client-side JavaScript (like the block editor), as mobile apps, or as desktop or command line tools.
66

7+
[info]The REST API is just one of many APIs provided by WordPress. You can find the [documentation on these additional APIs here](https://codex.wordpress.org/WordPress_APIs).[/info]
78

89
## Why use the WordPress REST API
910

10-
The WordPress REST API makes it easier than ever to use WordPress in new and exciting ways, such as creating Single Page Applications on top of WordPress. You could create a plugin to provide an entirely new admin experiences for WordPress, or create a brand new interactive front-end experience.
11+
WordPress already provides a rich set of tools and interfaces for building sites, and you should not feel pressured to use the REST API if your site is already working the way you expect. You do not need to use the REST API to build a WordPress theme or plugin.
1112

12-
You would not even have to write the applications in PHP: any programming language that can make HTTP requests and interpret JSON can interact with WordPress through the REST API, from Node.js to Java and beyond.
13+
However, if you do wish to write your theme, plugin, or external application as a client-side JavaScript application, or a standalone program in a language other than PHP, then your application will need a structured way to access content within your WordPress site. Any programming language which can make HTTP requests and interpret JSON can use the REST API to interact with WordPress, from PHP, Node.js, Go, and Java, to Swift, Kotlin, and beyond.
1314

14-
The WordPress REST API can also serve as a strong replacement for the admin-ajax API in core. By using the REST API, you can more easily structure the way you want to get data into and out of WordPress. AJAX calls can be greatly simplified by using the REST API, enabling you to spend less time accessing the data you need and more time creating better user experiences.
15+
Using the WordPress REST API you can create a plugin to provide an entirely new admin experiences for WordPress, build a brand new interactive front-end experience, or bring your WordPress content into completely separate applications. Even if you're using vanilla JavaScript or jQuery within a theme or plugin the REST API provides a more predictable and structured way to interact with your site's content than [`admin-ajax`](https://codex.wordpress.org/AJAX_in_Plugins), enabling you to spend less time accessing the data you need and more time creating better user experiences.
1516

16-
Our imagination is the only limit to what can be done with the WordPress REST API. The bottom line is, if you want a structured, extensible, and simple way to get data in and out of WordPress over HTTP, you probably want to use the REST API. For all of its simplicity the REST API can feel quite complex at first, and we will attempt to break it down into smaller components so that we can easily piece together the full puzzle.
17+
If you want a structured, extensible, and simple way to get data in and out of WordPress, you probably want to use the REST API.
18+
19+
For all of its simplicity the REST API can feel quite complex at first, so in this handbook we will attempt to break it down into smaller components to explain each part of the full puzzle.
1720

1821

1922
## Key Concepts
@@ -28,13 +31,12 @@ To get started with using the WordPress REST API we will break down some of the
2831

2932
Each of these concepts play a crucial role in using and understanding the WordPress REST API. Let's briefly break them down so that we can later explore each in greater depth.
3033

31-
3234
### Routes & Endpoints
3335

3436
A route, in the context of the WordPress REST API, is a URI which can be mapped to different HTTP methods. The mapping of an individual HTTP method to a route is known as an "endpoint". To clarify: If we make a `GET` request to `http://oursite.com/wp-json/`, we will get a JSON response showing us what routes are available, and within each route, what endpoints are available. `/wp-json/` is a route itself and when a `GET` request is made it matches to the endpoint that displays what is known as the index for the WordPress REST API. We will learn how to register our own routes and endpoints in the following sections.
3537

3638
If you get a `404` error when trying to access `http://oursite.com/wp-json/` URL you may try fixing your pretty permalinks.
37-
[info] If you're using [non-pretty permalinks](https://codex.wordpress.org/Using_Permalinks), you should pass the REST API route as a query string parameter (with `rest_route` parameter). The route `http://oursite.com/wp-json/` in the example above would hence be `http://oursite.com/?rest_route=/`.[/info]
39+
[info]If you're using [non-pretty permalinks](https://wordpress.org/support/article/using-permalinks/), you should pass the REST API route as a query string parameter. The route `http://oursite.com/wp-json/` in the example above would hence be `http://oursite.com/?rest_route=/`.[/info]
3840

3941
### Requests
4042

0 commit comments

Comments
 (0)