Skip to content

Commit 46bd463

Browse files
committed
Perform final sync from WXR
1 parent 8d18756 commit 46bd463

File tree

8 files changed

+52
-50
lines changed

8 files changed

+52
-50
lines changed

changelog.md

Lines changed: 7 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,12 @@
11
# Changelog
22

33
This document details changes to the WP REST API since its public release in version 4.7.0.
4+
## Version 4.8.1
5+
<ul>
6+
<li>Add a filter to allow modifying the response after embedded data is added. [#](https://core.trac.wordpress.org/changeset/41093)</li>
7+
<li>`wp-api.js` client: Correctly interpret `settings` resource as a model rather than a collection. [#](https://core.trac.wordpress.org/changeset/41126)</li>
8+
<li>Fix `PUT` (and other) requests for nginx servers by tweaking REST API URLs. [#](https://core.trac.wordpress.org/changeset/41140)</li>
9+
</ul>
410
## Version 4.8.0
511
<ul>
612
<li>Improve strings added after 4.7.0 string freeze. [#](https://core.trac.wordpress.org/changeset/40571), [#](https://core.trac.wordpress.org/changeset/40606)</li>
@@ -12,7 +18,7 @@ This document details changes to the WP REST API since its public release in ver
1218
<li>Add endpoint for proxying requests to external oEmbed providers, and use it in the media modal instead of the `parse-embed` AJAX action.  **This is the first usage of the WP REST API in `wp-admin`.** [#](http://core.trac.wordpress.org/changeset/40628)</li>
1319
<li>Do not set `X-WP-Deprecated*` headers as often. [#](https://core.trac.wordpress.org/changeset/40782)</li>
1420
<li>Avoid sending blank `Last-Modified` headers with authenticated requests. [#](https://core.trac.wordpress.org/changeset/40805)</li>
15-
<li>Fix changing parameters with `$request-&gt;set_param()` for some requests. [#](https://core.trac.wordpress.org/changeset/40815)</li>
21+
<li>Fix changing parameters with `$request->set_param()` for some requests. [#](https://core.trac.wordpress.org/changeset/40815)</li>
1622
<li>In the admin area, ensure the REST API endpoint URL is forced to `https` when necessary. [#](https://core.trac.wordpress.org/changeset/40843)</li>
1723
</ul>
1824
## Version 4.7.4

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

Lines changed: 19 additions & 18 deletions
Original file line numberDiff line numberDiff line change
@@ -45,7 +45,11 @@ add_action( 'rest_api_init', function () {
4545
} );
4646
```
4747

48-
Right now, we're only registering the one endpoint for the route. ("Route" is the URL, whereas "endpoint" is the function behind it that corresponds to a method *and* a URL. For more, see the [Glossary](/glossary.html).) If your site domain is `example.com` and you've kept the API path of `wp-json`, then the full URL would be `http://example.com/wp-json/myplugin/v1/author/(?P\d+)`. Each route can have any number of endpoints, and for each endpoint, you can define the HTTP methods allowed, a callback function for responding to the request and a permissions callback for creating custom permissions. In addition you can define allowed fields in the request and for each field specify a default value, a sanitization callback, a validation callback, and whether the field is required.
48+
Right now, we're only registering the one endpoint for the route. The term "route" refers to the URL, whereas "endpoint" refers to the function behind it that corresponds to a method *and* a URL (for more information, see the [Glossary](https://developer.wordpress.org/rest-api/extending-the-rest-api/glossary/)).
49+
50+
For example, if your site domain is `example.com` and you've kept the API path of `wp-json`, then the full URL would be `http://example.com/wp-json/myplugin/v1/author/(?P\d+)`.
51+
52+
Each route can have any number of endpoints, and for each endpoint, you can define the HTTP methods allowed, a callback function for responding to the request and a permissions callback for creating custom permissions. In addition you can define allowed fields in the request and for each field specify a default value, a sanitization callback, a validation callback, and whether the field is required.
4953

5054

5155
### Namespacing
@@ -54,7 +58,7 @@ Namespaces are the first part of the URL for the endpoint. They should be used a
5458

5559
Namespaces in general should follow the pattern of `vendor/v1`, where `vendor` is typically your plugin or theme slug, and `v1` represents the first version of the API. If you ever need to break compatibility with new endpoints, you can then bump this to `v2`.
5660

57-
The above scenario, two routes with the same name, from two different plugins, requires all vendors to use a unique namespace. Failing to do so is analagous to a failure to use a vendor function prefix, class prefix and/ or class namespace in a theme or plugin, which is very `_doing_it_wrong`.
61+
The above scenario, two routes with the same name, from two different plugins, requires all vendors to use a unique namespace. Failing to do so is analogous to a failure to use a vendor function prefix, class prefix and/ or class namespace in a theme or plugin, which is **very very bad**.
5862

5963
An added benefit of using namespaces is that clients can detect support for your custom API. The API index lists out the available namespaces on a site:
6064

@@ -72,8 +76,7 @@ An added benefit of using namespaces is that clients can detect support for your
7276
}
7377
```
7478

75-
If a client wants to check that your API exists on a site, they can check against this list. (For more information, see the [Discovery guide](/guide/discovery/).)
76-
79+
If a client wants to check that your API exists on a site, they can check against this list. (For more information, see the [Discovery guide](https://developer.wordpress.org/rest-api/using-the-rest-api/discovery/).)
7780

7881
### Arguments
7982

@@ -83,23 +86,23 @@ By default, routes receive all arguments passed in from the request. These are m
8386
<?php
8487
function my_awesome_func( WP_REST_Request $request ) {
8588
// You can access parameters via direct array access on the object:
86-
$param = $request['some_param'];
89+
$param = $request['some_param'];
8790

8891
// Or via the helper method:
89-
$param = $request->get_param( 'some_param' );
92+
$param = $request->get_param( 'some_param' );
9093

9194
// You can get the combined, merged set of parameters:
92-
$parameters = $request->get_params();
95+
$parameters = $request->get_params();
9396

9497
// The individual sets of parameters are also available, if needed:
95-
$parameters = $request->get_url_params();
98+
$parameters = $request->get_url_params();
9699
$parameters = $request->get_query_params();
97100
$parameters = $request->get_body_params();
98101
$parameters = $request->get_json_params();
99102
$parameters = $request->get_default_params();
100103

101104
// Uploads aren't merged in, but can be accessed separately:
102-
$parameters = $request->get_file_params();
105+
$parameters = $request->get_file_params();
103106
}
104107
```
105108

@@ -206,7 +209,7 @@ When wrapping existing callbacks, you should always use `rest_ensure_response()`
206209

207210
You can also register a permissions callback for the endpoint. This is a function that checks if the user can perform the action (reading, updating, etc) before the real callback is called. This allows the API to tell the client what actions they can perform on a given URL without needing to attempt the request first.
208211

209-
This callback can be registered as `permission_callback`, again in the endpoint options next to your `callback` option. This callback should return a boolean or a `WP_Error` instance. If this function returns true, the response will be proccessed. If it returns false, a default error message will be returned and the request will not proceed with processing. If it returns a `WP_Error`, that error will be returned to the client.
212+
This callback can be registered as `permission_callback`, again in the endpoint options next to your `callback` option. This callback should return a boolean or a `WP_Error` instance. If this function returns true, the response will be processed. If it returns false, a default error message will be returned and the request will not proceed with processing. If it returns a `WP_Error`, that error will be returned to the client.
210213

211214
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).
212215

@@ -320,7 +323,7 @@ class Slug_Custom_Route extends WP_REST_Controller {
320323
*/
321324
public function get_items( $request ) {
322325
$items = array(); //do a query, call another class, etc
323-
$data = array();
326+
$data = array();
324327
foreach( $items as $item ) {
325328
$itemdata = $this->prepare_item_for_response( $item, $request );
326329
$data[] = $this->prepare_response_for_collection( $itemdata );
@@ -337,14 +340,14 @@ class Slug_Custom_Route extends WP_REST_Controller {
337340
*/
338341
public function get_item( $request ) {
339342
//get parameters from request
340-
$params = $request->get_params();
343+
$params = $request->get_params();
341344
$item = array();//do a query, call another class, etc
342-
$data = $this->prepare_item_for_response( $item, $request );
345+
$data = $this->prepare_item_for_response( $item, $request );
343346

344347
//return a response or error based on some conditional
345-
if ( 1 == 1 ) {
348+
if ( 1 == 1 ) {
346349
return new WP_REST_Response( $data, 200 );
347-
}else{
350+
} else {
348351
return new WP_Error( 'code', __( 'message', 'text-domain' ) );
349352
}
350353
}
@@ -356,7 +359,6 @@ class Slug_Custom_Route extends WP_REST_Controller {
356359
* @return WP_Error|WP_REST_Request
357360
*/
358361
public function create_item( $request ) {
359-
360362
$item = $this->prepare_item_for_database( $request );
361363

362364
if ( function_exists( 'slug_some_function_to_create_item') ) {
@@ -386,7 +388,6 @@ class Slug_Custom_Route extends WP_REST_Controller {
386388
}
387389

388390
return new WP_Error( 'cant-update', __( 'message', 'text-domain'), array( 'status' => 500 ) );
389-
390391
}
391392

392393
/**
@@ -416,7 +417,7 @@ class Slug_Custom_Route extends WP_REST_Controller {
416417
*/
417418
public function get_items_permissions_check( $request ) {
418419
//return true; <--use to make readable by all
419-
return current_user_can( 'edit_something' );
420+
return current_user_can( 'edit_something' );
420421
}
421422

422423
/**

extending-the-rest-api/adding-rest-api-support-for-custom-content-types.md

Lines changed: 1 addition & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -127,10 +127,8 @@ function my_book_taxonomy() {
127127
}
128128
```
129129

130-
131130
## Adding REST API Support To Existing Content Types
132-
133-
When a custom post type or custom taxonomy has been added by code that you do not control, for example a theme or plugin you are using, you may need to add REST API support after it has alredy been registered. The arguments are the same as in the previous examples, but need to be added to the global `$wp_post_types` and `$wp_taxonomies` arrays.
131+
When a custom post type or custom taxonomy has been added by code that you do not control, for example a theme or plugin you are using, you may need to add REST API support after it has already been registered. The arguments are the same as in the previous examples, but need to be added to the global `$wp_post_types` and `$wp_taxonomies` arrays.
134132

135133
Here is an example of adding REST API support to an existing custom post type:
136134

extending-the-rest-api/routes-and-endpoints.md

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -166,7 +166,7 @@ function prefix_register_product_routes() {
166166
add_action( 'rest_api_init', 'prefix_register_product_routes' );
167167
```
168168

169-
The above example covers a lot. The important part to note is that in the second route we register, we add on a path variable `/(?P[\d]+)` to our resource path `/products`. The path variable is a regular expression. In this case it uses `[\d]+` to signify that should be any numerical character at least once. If you are using numeric IDs for your resources, then this is a great example of how to use a path variable. When using path variables, we now have to be careful around what can be matched as it is user input.
169+
The above example covers a lot. The important part to note is that in the second route we register, we add on a path variable `/(?P<id>[\d]+)` to our resource path `/products`. The path variable is a regular expression. In this case it uses `[\d]+` to signify that should be any numerical character at least once. If you are using numeric IDs for your resources, then this is a great example of how to use a path variable. When using path variables, we now have to be careful around what can be matched as it is user input.
170170

171171
The regex luckily will filter out anything that is not numerical. However, what if the product for the requested ID doesn't exist. We need to do error handling. You can see the basic way we are handling errors in the code example above. When you return a `WP_Error` in your endpoint callbacks the API server will automatically handle serving the error to the client.
172172

index.md

Lines changed: 1 addition & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -41,8 +41,7 @@ One of the primary classes in the  WordPress REST API infrastructure is `WP_RES
4141

4242
### Responses
4343

44-
Responses are the data you get back from the API. The `WP_REST_Response` provides a way to interact with the response data returned by endpoints. Responses can return the desired data, and they can also be used to return errors.
45-
44+
Responses are the data you get back from the API. The `WP_REST_Response` class provides a way to interact with the response data returned by endpoints. Responses can return the desired data, and they can also be used to return errors.
4645

4746
### Schema
4847

requests.md

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -456,7 +456,7 @@ function prefix_validate_requests( $requests, $request, $param_key ) {
456456
return new WP_Error( 'rest_invald_param', esc_html__( 'You must specify the method and route for each request.' ), array( 'status' => 400 ) );
457457
}
458458

459-
if ( isset( $request['params'] ) &amp;&amp; ! is_array( $request['params'] ) ) {
459+
if ( isset( $request['params'] ) && ! is_array( $request['params'] ) ) {
460460
return new WP_Error( 'rest_invald_param', esc_html__( 'You must specify the params for each request as an array of named key value pairs.' ), array( 'status' => 400 ) );
461461
}
462462
}

using-the-rest-api/authentication.md

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -60,7 +60,7 @@ While cookie authentication is the only authentication mechanism available nativ
6060

6161
[info]
6262

63-
There's also a <a href="https://github.com/WP-API/Basic-Auth">Basic Authentication</a> plugin.
63+
There's also a [Basic Authentication](https://github.com/WP-API/Basic-Auth) plugin.
6464

6565
Note that this plugin requires sending your username and password with every request, and should only be used for development and testing i.e. not in a production environment.
6666

using-the-rest-api/backbone-javascript-client.md

Lines changed: 21 additions & 23 deletions
Original file line numberDiff line numberDiff line change
@@ -38,7 +38,7 @@ Models:
3838
* Tag
3939
* Taxonomy
4040
* Type
41-
* User`
41+
* User
4242

4343
Collections:
4444
* Categories
@@ -139,66 +139,64 @@ post.fetch();
139139
// Get a collection of the post's categories (returns a promise)
140140
// Uses _embedded data if available, in which case promise resolves immediately.
141141
post.getCategories().done( function( postCategories ) {
142-
// ... do something with the categories.
143-
// The new post has an single Category: Uncategorized
144-
console.log( postCategories[0].name );
145-
// response -> "Uncategorized"
142+
// ... do something with the categories.
143+
// The new post has an single Category: Uncategorized
144+
console.log( postCategories[0].name );
145+
// response -> "Uncategorized"
146146
} );
147147

148148
// Get a posts author User model.
149149
post.getAuthorUser().done( function( user ){
150-
// ... do something with user
151-
console.log( user.get( 'name' ) );
150+
// ... do something with user
151+
console.log( user.get( "name" ) );
152152
} );
153153

154154
// Get a posts featured image Media model.
155155
post.getFeaturedImage().done( function( image ){
156-
// ... do something with image
157-
console.log( image );
156+
// ... do something with image
157+
console.log( image );
158158
} );
159159

160160
// Set the post categories.
161-
post.setCategories( [ 'apples', 'oranges' ] );
161+
post.setCategories( [ "apples", "oranges" ] );
162162

163163
// Get all the categories
164164
var allCategories = new wp.api.collections.Categories()
165165
allCategories.fetch();
166166

167-
var appleCategory = allCategories.findWhere( { slug: 'apples' } );
167+
var appleCategory = allCategories.findWhere( { slug: "apples" } );
168168

169169
// Add the category to the postCategories collection we previously fetched.
170-
appleCategory.set( 'parent_post', post.get( 'id' ) );
170+
appleCategory.set( "parent_post", post.get( "id" ) );
171171

172172
// Use the POST method so Backbone will not PUT it even though it has an id.
173-
postCategories.create( appleCategory.toJSON(), { type: 'POST' } );
173+
postCategories.create( appleCategory.toJSON(), { type: "POST" } );
174174

175175
// Remove the Uncategorized category
176176
postCategories.at( 0 ).destroy();
177177

178178
// Check the results - re-fetch
179179
postCategories = post.getCategories();
180180

181-
postCategories.at( 0 ).get( 'name' );
181+
postCategories.at( 0 ).get( "name" );
182182
// response -> "apples"
183183
```
184184

185-
186185
### Collection examples:
187-
188-
to get the last 10 posts:
186+
To get the last 10 posts:
189187

190188
```js
191189
var postsCollection = new wp.api.collections.Posts();
192190
postsCollection.fetch();
193191
```
194192

195-
to get the last 25 posts:
193+
To get the last 25 posts:
196194

197195
```js
198196
postsCollection.fetch( { data: { per_page: 25 } } );
199197
```
200198

201-
use filter to change the order & orderby options:
199+
Use filter to change the order & orderby options:
202200

203201
```js
204202
postsCollection.fetch( { data: { 'filter': { 'orderby': 'title', 'order': 'ASC' } } } );
@@ -210,13 +208,13 @@ All collections support pagination automatically, and you can get the next page
210208
postsCollection.more();
211209
```
212210

213-
to get page 5 of a collection:
211+
To get page 5 of a collection:
214212

215213
```js
216214
posts.fetch( { data: { page: 5 } } );
217215
```
218216

219-
check if the collection has any more posts:
217+
Check if the collection has any more posts:
220218

221219
```js
222220
posts.hasMore();
@@ -239,8 +237,8 @@ Revision collections can also be accessed via their parent's collection. This ex
239237
var post = new wp.api.models.Post( { id: 1 } );
240238
post.fetch();
241239
post.getRevisions().done( function( revisions ){
242-
console.log( revisions );
240+
console.log( revisions );
243241
});
244242
```
245243

246-
If you add custom endpoints to the api they will also become available as models/collections. For example, you will get new models and collections when you [add REST API support to your custom post type](http://v2.wp-api.org/extending/custom-content-types/). Note: because the schema is stored in the user's session cache to avoid re-fetching, you may need to open a new tab to get a new read of the Schema.
244+
If you add custom endpoints to the API they will also become available as models/collections. For example, you will get new models and collections when you [add REST API support to your custom post type](http://v2.wp-api.org/extending/custom-content-types/). Note: Because the schema is stored in the user's session cache to avoid re-fetching, you may need to open a new tab to get a new read of the Schema.

0 commit comments

Comments
 (0)