Document the new Resource Discovery feature in WordPress 5.5.

TimothyBJacobs · TimothyBJacobs · commit c7fa82c22dd9 · 2020-08-09T01:42:50.000-04:00
diff --git a/extending-the-rest-api/adding-custom-endpoints.md b/extending-the-rest-api/adding-custom-endpoints.md
@@ -257,6 +257,24 @@ add_action( 'rest_api_init', function () {
 } );
 ```
 
+### Discovery
+
+If you'd like to enable [Resource Discovery](https://developer.wordpress.org/rest-api/using-the-rest-api/discovery/#resource-discovery) for your custom endpoint, you can do so using the `rest_queried_resource_route` filter. For example, consider a [custom query var](https://developer.wordpress.org/reference/hooks/query_vars/) `my-route` that contains the id of your custom resource. The following code snippet would add a discovery link whenever the `my-route` query var is used.
+
+```php
+function my_plugin_rest_queried_resource_route( $route ) {
+    $id = get_query_var( 'my-route' );
+    if ( ! $route && $id ) {
+        $route = '/my-ns/v1/items/' . $id;
+    }
+
+    return $route;
+}
+add_filter( 'rest_queried_resource_route', 'my_plugin_rest_queried_resource_route' );
+```
+
+Note: If your endpoint is describing a custom post type or custom taxonomy you will most likely want to be using the `rest_route_for_post` or `rest_route_for_term` filters instead. 
+
 ## The Controller Pattern
 
 The controller pattern is a best practice for working with complex endpoints with the API.
diff --git a/extending-the-rest-api/adding-rest-api-support-for-custom-content-types.md b/extending-the-rest-api/adding-rest-api-support-for-custom-content-types.md
@@ -78,6 +78,18 @@ function my_book_cpt() {
 }
 ```
 
+If you are using a custom `rest_controller_class`, then the REST API is unable to automatically determine the route for a given post. In this case, you can use the `rest_route_for_post` filter to provide this information. This allows for your custom post type to be properly formatted in the Search endpoint and enables automated discovery links.
+
+```php
+function my_plugin_rest_route_for_post( $route, $post ) {
+    if ( $post->post_type === 'book' ) {
+        $route = '/wp/v2/books/' . $post->ID;
+    }
+ 
+    return $route;
+}
+add_filter( 'rest_route_for_post', 'my_plugin_rest_route_for_post', 10, 2 );
+``` 
 
 ## Registering A Custom Taxonomy With REST API Support
 
@@ -127,6 +139,19 @@ function my_book_taxonomy() {
 }
 ```
 
+If you are using a custom `rest_controller_class`, then the REST API is unable to automatically determine the route for a given term. In this case, you can use the `rest_route_for_term` filter to provide this information. This allows for your custom taxonomy to be properly formatted in the Search endpoint and enables automated discovery links.
+
+```php
+function my_plugin_rest_route_for_term( $route, $term ) {
+    if ( $term->taxonomy === 'genre' ) {
+        $route = '/wp/v2/genre/' . $term->term_id;
+    }
+ 
+    return $route;
+}
+add_filter( 'rest_route_for_term', 'my_plugin_rest_route_for_term', 10, 2 );
+``` 
+
 ## Adding REST API Support To Existing Content Types
 
 If you need to add REST API support for a custom post type or custom taxonomy you do not control, for example a theme or plugin you are using, you can use the `register_post_type_args` filter hook that exists since WordPress version 4.6.0.
diff --git a/using-the-rest-api/discovery.md b/using-the-rest-api/discovery.md
@@ -153,3 +153,14 @@ This would add the `testplugin/v1` namespace to the index:
 }
 ```
 
+## Resource Discovery
+
+As of [WordPress 5.5](https://core.trac.wordpress.org/changeset/48273) the REST API also provides a discovery mechanism for identifying the REST API route equivalent of the current document. A link is added with a `rel` of `alternate` and a `type` of `alternate/json` that points to a REST API url. The link is added both as a [`Link` header](#link-header) and a [`<link>` element](#element).
+
+For instance, in the `<head>` section of this page, the following `<link>` appears.
+
+```html
+<link rel="alternate" type="application/json" href="https://developer.wordpress.org/wp-json/wp/v2/rest-api-handbook/23085">
+```
+
+Links are added for post, pages, and other custom post types, as well as terms and author pages. Links are not currently output for post archives or search results.
