Skip to content

Commit c368c2b

Browse files
Document the new doing it wrong notice for missing permission callbacks.
1 parent 93b7075 commit c368c2b

File tree

1 file changed

+17
-1
lines changed

1 file changed

+17
-1
lines changed

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

Lines changed: 17 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -207,7 +207,7 @@ When wrapping existing callbacks, you should always use `rest_ensure_response()`
207207

208208
### Permissions Callback
209209

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.
210+
You must 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.
211211

212212
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.
213213

@@ -237,6 +237,22 @@ add_action( 'rest_api_init', function () {
237237

238238
Note that the permission callback also receives the Request object as the first parameter, so you can do checks based on request arguments if you need to.
239239

240+
As of [WordPress 5.5](https://core.trac.wordpress.org/changeset/48526), if a `permission_callback` is not provided, the REST API will issue a `_doing_it_wrong` notice.
241+
242+
> The REST API route definition for myplugin/v1/author is missing the required permission_callback argument. For REST API routes that are intended to be public, use __return_true as the permission callback.
243+
244+
If your REST API endpoint is public, you can use `__return_true` as the permission callback.
245+
246+
```php
247+
<?php
248+
add_action( 'rest_api_init', function () {
249+
register_rest_route( 'myplugin/v1', '/author/(?P<id>\d+)', array(
250+
'methods' => 'GET',
251+
'callback' => 'my_awesome_func',
252+
'permission_callback' => '__return_true',
253+
) );
254+
} );
255+
```
240256

241257
## The Controller Pattern
242258

0 commit comments

Comments
 (0)