You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Copy file name to clipboardExpand all lines: changelog.md
+7-1Lines changed: 7 additions & 1 deletion
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -1,6 +1,12 @@
1
1
# Changelog
2
2
3
3
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>
4
10
## Version 4.8.0
5
11
<ul>
6
12
<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
12
18
<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>
13
19
<li>Do not set `X-WP-Deprecated*` headers as often. [#](https://core.trac.wordpress.org/changeset/40782)</li>
14
20
<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->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>
16
22
<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>
Copy file name to clipboardExpand all lines: extending-the-rest-api/adding-custom-endpoints.md
+19-18Lines changed: 19 additions & 18 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -45,7 +45,11 @@ add_action( 'rest_api_init', function () {
45
45
} );
46
46
```
47
47
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.
49
53
50
54
51
55
### Namespacing
@@ -54,7 +58,7 @@ Namespaces are the first part of the URL for the endpoint. They should be used a
54
58
55
59
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`.
56
60
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**.
58
62
59
63
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:
60
64
@@ -72,8 +76,7 @@ An added benefit of using namespaces is that clients can detect support for your
72
76
}
73
77
```
74
78
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/).)
77
80
78
81
### Arguments
79
82
@@ -83,23 +86,23 @@ By default, routes receive all arguments passed in from the request. These are m
83
86
<?php
84
87
function my_awesome_func( WP_REST_Request $request ) {
85
88
// You can access parameters via direct array access on the object:
86
-
$param = $request['some_param'];
89
+
$param = $request['some_param'];
87
90
88
91
// Or via the helper method:
89
-
$param = $request->get_param( 'some_param' );
92
+
$param = $request->get_param( 'some_param' );
90
93
91
94
// You can get the combined, merged set of parameters:
92
-
$parameters = $request->get_params();
95
+
$parameters = $request->get_params();
93
96
94
97
// The individual sets of parameters are also available, if needed:
95
-
$parameters = $request->get_url_params();
98
+
$parameters = $request->get_url_params();
96
99
$parameters = $request->get_query_params();
97
100
$parameters = $request->get_body_params();
98
101
$parameters = $request->get_json_params();
99
102
$parameters = $request->get_default_params();
100
103
101
104
// Uploads aren't merged in, but can be accessed separately:
102
-
$parameters = $request->get_file_params();
105
+
$parameters = $request->get_file_params();
103
106
}
104
107
```
105
108
@@ -206,7 +209,7 @@ When wrapping existing callbacks, you should always use `rest_ensure_response()`
206
209
207
210
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.
208
211
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.
210
213
211
214
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).
212
215
@@ -320,7 +323,7 @@ class Slug_Custom_Route extends WP_REST_Controller {
320
323
*/
321
324
public function get_items( $request ) {
322
325
$items = array(); //do a query, call another class, etc
Copy file name to clipboardExpand all lines: extending-the-rest-api/adding-rest-api-support-for-custom-content-types.md
+1-3Lines changed: 1 addition & 3 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -127,10 +127,8 @@ function my_book_taxonomy() {
127
127
}
128
128
```
129
129
130
-
131
130
## 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.
134
132
135
133
Here is an example of adding REST API support to an existing custom post type:
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.
170
170
171
171
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.
Copy file name to clipboardExpand all lines: index.md
+1-2Lines changed: 1 addition & 2 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -41,8 +41,7 @@ One of the primary classes in the WordPress REST API infrastructure is `WP_RES
41
41
42
42
### Responses
43
43
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.
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 ) );
Copy file name to clipboardExpand all lines: using-the-rest-api/authentication.md
+1-1Lines changed: 1 addition & 1 deletion
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -60,7 +60,7 @@ While cookie authentication is the only authentication mechanism available nativ
60
60
61
61
[info]
62
62
63
-
There's also a <ahref="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.
64
64
65
65
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.
@@ -210,13 +208,13 @@ All collections support pagination automatically, and you can get the next page
210
208
postsCollection.more();
211
209
```
212
210
213
-
to get page 5 of a collection:
211
+
To get page 5 of a collection:
214
212
215
213
```js
216
214
posts.fetch( { data: { page:5 } } );
217
215
```
218
216
219
-
check if the collection has any more posts:
217
+
Check if the collection has any more posts:
220
218
221
219
```js
222
220
posts.hasMore();
@@ -239,8 +237,8 @@ Revision collections can also be accessed via their parent's collection. This ex
239
237
var post =newwp.api.models.Post( { id:1 } );
240
238
post.fetch();
241
239
post.getRevisions().done( function( revisions ){
242
-
console.log( revisions );
240
+
console.log( revisions );
243
241
});
244
242
```
245
243
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