├── .gitignore
├── bin
    ├── templates
    │   ├── reference-parts
    │   │   ├── examples
    │   │   │   ├── update-post-curl.html
    │   │   │   └── update-comment-curl.html
    │   │   ├── create-item.html
    │   │   ├── delete-item.html
    │   │   ├── update-item.html
    │   │   ├── get-item.html
    │   │   ├── list-item.html
    │   │   ├── args-list.html
    │   │   └── schema.html
    │   └── endpoint.md
    ├── generate-manifest.php
    ├── parse-wxr.php
    └── regenerate.php
├── composer.json
├── README.md
├── reference
    ├── navigation-fallbacks.md
    ├── block-pattern-categories.md
    ├── rendered-blocks.md
    ├── wp_global_styles.md
    ├── menu-locations.md
    ├── widget-types.md
    ├── search-results.md
    ├── wp-site-health-tests.md
    ├── post-statuses.md
    ├── block-patterns.md
    ├── wp_global_styles-revisions.md
    ├── block-directory-items.md
    ├── pattern-directory-items.md
    ├── taxonomies.md
    ├── sidebars.md
    ├── themes.md
    ├── post-types.md
    ├── widgets.md
    ├── application-passwords.md
    ├── plugins.md
    └── nav_menu_item-revisions.md
├── extending-the-rest-api.md
├── using-the-rest-api.md
├── using-the-rest-api
    ├── client-libraries.md
    ├── pagination.md
    ├── linking-and-embedding.md
    ├── authentication.md
    ├── global-parameters.md
    ├── discovery.md
    └── backbone-javascript-client.md
├── key-concepts.md
├── glossary.md
├── index.md
├── reference.md
├── frequently-asked-questions.md
└── extending-the-rest-api
    └── adding-rest-api-support-for-custom-content-types.md


/.gitignore:
--------------------------------------------------------------------------------
1 | # Ignore Composer files
2 | .idea/
3 | vendor/
4 | 


--------------------------------------------------------------------------------
/bin/templates/reference-parts/examples/update-post-curl.html:
--------------------------------------------------------------------------------
1 | $ curl -X POST https://example.com/wp-json{{ route.nicename }} -d '{"title":"My New Title"}'
2 | 


--------------------------------------------------------------------------------
/bin/templates/reference-parts/examples/update-comment-curl.html:
--------------------------------------------------------------------------------
1 | $ curl -X POST https://example.com/wp-json{{ route.nicename }} -d '{"content":"My updated comment"}'
2 | 


--------------------------------------------------------------------------------
/composer.json:
--------------------------------------------------------------------------------
 1 | {
 2 |     "name": "wp-api/docs",
 3 |     "description": "The WordPress REST API Handbook",
 4 |     "require": {
 5 |         "rmccue/requests": "^2.0",
 6 |         "twig/twig": "^3.0"
 7 |     },
 8 |     "scripts": {
 9 |         "regenerate": "php bin/regenerate.php"
10 |     }
11 | }
12 | 


--------------------------------------------------------------------------------
/bin/templates/reference-parts/create-item.html:
--------------------------------------------------------------------------------
 1 | <section class="route">
 2 | 	<div class="primary">
 3 | 		<h2>Create a {{ name | title }}</h2>
 4 | 		{{ include( 'reference-parts/args-list.html', { args: endpoint.args, link: true } ) }}
 5 | 	</div>
 6 | 	<div class="secondary">
 7 | 		<h3>Definition</h3>
 8 | 
 9 | 		<code>POST {{ route.nicename }}</code>
10 | 	</div>
11 | </section>
12 | 


--------------------------------------------------------------------------------
/bin/templates/endpoint.md:
--------------------------------------------------------------------------------
 1 | ---
 2 | ---
 3 | 
 4 | # {{ plural | title }}
 5 | 
 6 | <section class="route">
 7 | 	<div class="primary">
 8 | 		{{ include('reference-parts/schema.html') }}
 9 | 	</div>
10 | </section>
11 | 
12 | <div>
13 | {%- for route in routes -%}
14 | 	{%- for endpoint in route.endpoints -%}
15 | 		{{- include( 'reference-parts/' ~ endpoint.type ~ '.html' ) -}}
16 | 	{%- endfor -%}
17 | {%- endfor -%}
18 | </div>
19 | 


--------------------------------------------------------------------------------
/bin/templates/reference-parts/delete-item.html:
--------------------------------------------------------------------------------
 1 | <section class="route">
 2 | 	<div class="primary">
 3 | 		<h2>Delete a {{ name | title }}</h2>
 4 | 		{{ include( 'reference-parts/args-list.html', { args: endpoint.args } ) }}
 5 | 	</div>
 6 | 	<div class="secondary">
 7 | 		<h3>Definition</h3>
 8 | 
 9 | 		<code>DELETE {{ route.nicename }}</code>
10 | 
11 | 		<h3>Example Request</h3>
12 | 
13 | 		<code>$ curl -X DELETE https://example.com/wp-json{{ route.nicename }}</code>
14 | 	</div>
15 | </section>
16 | 


--------------------------------------------------------------------------------
/bin/templates/reference-parts/update-item.html:
--------------------------------------------------------------------------------
 1 | <section class="route">
 2 | 	<div class="primary">
 3 | 		<h2>Update a {{ name | title }}</h2>
 4 | 		{{ include( 'reference-parts/args-list.html', { args: endpoint.args, link: true } ) }}
 5 | 	</div>
 6 | 	<div class="secondary">
 7 | 		<h3>Definition</h3>
 8 | 
 9 | 		<code>POST {{ route.nicename }}</code>
10 | 
11 | 		<h3>Example Request</h3>
12 | 
13 | 		<code>{{ include( 'reference-parts/examples/update-' ~ route.schema.title ~ '-curl.html', ignore_missing = true ) }}</code>
14 | 	</div>
15 | </section>
16 | 


--------------------------------------------------------------------------------
/bin/templates/reference-parts/get-item.html:
--------------------------------------------------------------------------------
 1 | <section class="route">
 2 | 	<div class="primary">
 3 | 		<h2>Retrieve a {{ name | title }}</h2>
 4 | 
 5 | 		<h3>Definition & Example Request</h3>
 6 | 
 7 | 		<code>GET {{ route.nicename }}</code>
 8 | 
 9 | 		<p>Query this endpoint to retrieve a specific {{ name }} record.</p>
10 | 
11 | 		<code>$ curl https://example.com/wp-json{{ route.nicename }}</code>
12 | 	</div>
13 | 	<div class="secondary">
14 | 		{{ include( 'reference-parts/args-list.html', { args: endpoint.args, link: false } ) }}
15 | 	</div>
16 | </section>
17 | 


--------------------------------------------------------------------------------
/bin/templates/reference-parts/list-item.html:
--------------------------------------------------------------------------------
 1 | <section class="route">
 2 | 	<div class="primary">
 3 | 		<h2>List {{ plural | title }}</h2>
 4 | 		<p>Query this endpoint to retrieve a collection of {{ plural }}. The response you receive can be controlled and filtered using the URL query parameters below.</p>
 5 | 
 6 | 		<h3>Definition</h3>
 7 | 
 8 | 		<code>GET {{ route.nicename }}</code>
 9 | 
10 | 		<h3>Example Request</h3>
11 | 
12 | 		<code>$ curl https://example.com/wp-json{{ route.nicename }}</code>
13 | 	</div>
14 | 	<div class="secondary">
15 | 		{{ include( 'reference-parts/args-list.html', { args: endpoint.args, link: false } ) }}
16 | 	</div>
17 | </section>
18 | 


--------------------------------------------------------------------------------
/bin/templates/reference-parts/args-list.html:
--------------------------------------------------------------------------------
 1 | {% if args|length > 0 %}
 2 | 	<h3>Arguments</h3>
 3 | 	<table class="arguments">
 4 | 		{% for key, arg in args %}
 5 | 			<tr>
 6 | 				<td>
 7 | 					{% if link %}
 8 | 						<code><a href="#schema-{{ key }}">{{ key }}</a></code><br />
 9 | 					{% else %}
10 | 						<code>{{ key }}</code><br />
11 | 					{% endif %}
12 | 				</td>
13 | 				<td>
14 | 					{% if arg.description %}
15 | 						<p>{{ arg.description }}</p>
16 | 					{% endif %}
17 | 					{% if arg.required %}
18 | 						<p class="required">
19 | 							Required: {{ arg.required }}
20 | 						</p>
21 | 					{% endif %}
22 | 					{% if arg.default %}
23 | 						<p class="default">
24 | 							Default: <code>{{ arg.default }}</code>
25 | 						</p>
26 | 					{% endif %}
27 | 					{% if arg.enum %}
28 | 						<p>One of: <code>{{ arg.enum | e | join("</code>, <code>") | raw }}</code></p>
29 | 					{% endif %}
30 | 				</td>
31 | 			</tr>
32 | 		{% endfor %}
33 | 	</table>
34 | {% else %}
35 | 	<p>There are no arguments for this endpoint.</p>
36 | {% endif %}
37 | 


--------------------------------------------------------------------------------
/bin/generate-manifest.php:
--------------------------------------------------------------------------------
 1 | #!/usr/bin/env php
 2 | <?php
 3 | 
 4 | $root = dirname( __DIR__ );
 5 | $repo = 'WP-API/docs';
 6 | 
 7 | $manifest = array();
 8 | $paths = array(
 9 | 	$root . '/*.md',
10 | 	$root . '/*/*.md',
11 | 	$root . '/*/*/*.md',
12 | );
13 | $excludes = array(
14 | 	$root . '/README.md',
15 | 	$root . '/bin/templates/endpoint.md',
16 | );
17 | foreach ( $paths as $path ) {
18 | 	foreach ( glob( $path ) as $file ) {
19 | 		if ( in_array( $file, $excludes ) ) {
20 | 			continue;
21 | 		}
22 | 
23 | 		$slug = basename( $file, '.md' );
24 | 		$key = str_replace( array( $root . '/', '.md' ), '', $file );
25 | 		$parent = null;
26 | 		if ( stripos( $key, '/' ) ) {
27 | 			$bits = explode( '/', $key );
28 | 			array_pop( $bits );
29 | 			$parent = implode( '/', $bits );
30 | 		}
31 | 		$manifest[ $key ] = array(
32 | 			'slug'            => $slug,
33 | 			'parent'          => $parent,
34 | 			'markdown_source' => sprintf( 'https://github.com/%s/blob/master/%s.md', $repo, $key ),
35 | 		);
36 | 	}
37 | }
38 | 
39 | file_put_contents( $root . '/bin/manifest.json', json_encode( (object) $manifest, JSON_PRETTY_PRINT | JSON_UNESCAPED_SLASHES ) );
40 | 
41 | $count = count( $manifest );
42 | echo "Generated manifest.json of {$count} pages\n";
43 | 


--------------------------------------------------------------------------------
/README.md:
--------------------------------------------------------------------------------
 1 | # API Docs
 2 | 
 3 | This repo contains the source for [documentation for the API](https://developer.wordpress.org/rest-api/) on developer.wordpress.org (DevHub).
 4 | 
 5 | ## Adding/Removing Files
 6 | 
 7 | When creating new files, these must be added to the manifest. Run `bin/generate-manifest.php` to update this.
 8 | 
 9 | Removing files also requires regenerating the manifest. After deletion and sync with DevHub, the page also needs to be manually deleted from DevHub.
10 | 
11 | ## Refreshing the Templated API Reference
12 | 
13 | The reference section is created by parsing the output of a site's schema as retrieved from that site's REST API index route. The current method used to generate this approach is as follows:
14 | 
15 | - Create a local WordPress environment (always use the current or Release Candidate version of WordPress) using the local environment tool of your choice.
16 | - Edit `/etc/hosts` to map the domain `example.com` to the IP of that WordPress instance, and ensure the site is configured to run at `example.com`.
17 | - Run `composer install` in this project's root directory to install dependencies. 
18 | - Run `composer run-script regenerate` in this project's root directory to run the asset regeneration script.
19 | - Use `git status` and `git diff` to validate that the files were updated as expected.
20 | 


--------------------------------------------------------------------------------
/bin/templates/reference-parts/schema.html:
--------------------------------------------------------------------------------
 1 | <h2>Schema</h2>
 2 | <p>The schema defines all the fields that exist within a {{ name }} record. Any response from these endpoints can be expected to contain the fields below unless the `_filter` query parameter is used or the schema field only appears in a specific context.</p>
 3 | <table class="attributes">
 4 | 	{% for key, property in schema.properties %}
 5 | 		<tr id="schema-{{ key }}">
 6 | 			<td>
 7 | 				<code>{{ key }}</code>
 8 | 			</td>
 9 | 			<td>
10 | 				<p>{{ property.description }}</p>
11 | 				<p class="type">
12 | 					JSON data type: {{ property.type | join(' or ') }}{% if property.format %},
13 | 					{% if property.format == 'date-time' %}
14 | 						Format: datetime (<a href="https://core.trac.wordpress.org/ticket/41032">details</a>)
15 | 					{% elseif property.format == 'uri' %}
16 | 						Format: uri
17 | 					{% else %}
18 | 						Format: {{ property.format }}
19 | 					{% endif %}{% endif %}
20 | 				</p>
21 | 				{% if property.readonly %}
22 | 					<p class="read-only">Read only</p>
23 | 				{% endif %}
24 | 				<p class="context">Context: <code>{{ property.context | e | join("</code>, <code>") | raw }}</code></p>
25 | 				{% if property.enum %}
26 | 					<p>One of: <code>{{ property.enum | e | join("</code>, <code>") | raw }}</code></p>
27 | 				{% endif %}
28 | 			</td>
29 | 		</tr>
30 | 	{% endfor %}
31 | </table>
32 | 


--------------------------------------------------------------------------------
/reference/navigation-fallbacks.md:
--------------------------------------------------------------------------------
 1 | ---
 2 | ---
 3 | 
 4 | # Navigation Fallbacks
 5 | 
 6 | <section class="route">
 7 | 	<div class="primary">
 8 | 		<h2>Schema</h2>
 9 | <p>The schema defines all the fields that exist within a navigation fallback record. Any response from these endpoints can be expected to contain the fields below unless the `_filter` query parameter is used or the schema field only appears in a specific context.</p>
10 | <table class="attributes">
11 | 			<tr id="schema-id">
12 | 			<td>
13 | 				<code>id</code>
14 | 			</td>
15 | 			<td>
16 | 				<p>The unique identifier for the Navigation Menu.</p>
17 | 				<p class="type">
18 | 					JSON data type: integer				</p>
19 | 									<p class="read-only">Read only</p>
20 | 								<p class="context">Context: <code>view</code>, <code>edit</code>, <code>embed</code></p>
21 | 							</td>
22 | 		</tr>
23 | 	</table>
24 | 
25 | 	</div>
26 | </section>
27 | 
28 | <div><section class="route">
29 | 	<div class="primary">
30 | 		<h2>Retrieve a Navigation Fallback</h2>
31 | 
32 | 		<h3>Definition & Example Request</h3>
33 | 
34 | 		<code>GET /wp-block-editor/v1/navigation-fallback</code>
35 | 
36 | 		<p>Query this endpoint to retrieve a specific navigation fallback record.</p>
37 | 
38 | 		<code>$ curl https://example.com/wp-json/wp-block-editor/v1/navigation-fallback</code>
39 | 	</div>
40 | 	<div class="secondary">
41 | 			<p>There are no arguments for this endpoint.</p>
42 | 
43 | 	</div>
44 | </section>
45 | </div>
46 | 


--------------------------------------------------------------------------------
/extending-the-rest-api.md:
--------------------------------------------------------------------------------
 1 | # Extending the REST API
 2 | 
 3 | ## Guides
 4 | 
 5 | [Modifying responses](https://developer.wordpress.org/rest-api/extending-the-rest-api/modifying-responses/): add fields to REST API response objects using `register_meta` or `register_rest_field`
 6 | 
 7 | [Adding Endpoints](https://developer.wordpress.org/rest-api/extending-the-rest-api/adding-custom-endpoints/): create custom REST API endpoints for your plugin or application
 8 | 
 9 | [Working with Custom Content Types](https://developer.wordpress.org/rest-api/extending-the-rest-api/adding-rest-api-support-for-custom-content-types/): learn how to interact with your [custom post types](https://developer.wordpress.org/plugins/post-types/) and [custom taxonomies](https://developer.wordpress.org/plugins/post-types/) through the REST API
10 | 
11 | 
12 | ## Resources
13 | 
14 | [Defining your API Schema](https://developer.wordpress.org/rest-api/extending-the-rest-api/schema/): define the schema for your REST API resources and their arguments
15 | 
16 | [Glossary](https://developer.wordpress.org/rest-api/glossary/): get up to speed with phrases used throughout our documentation
17 | 
18 | [Routes & Endpoints](https://developer.wordpress.org/rest-api/extending-the-rest-api/routes-and-endpoints/): dive deeper into the nuances of REST API routes and the endpoints they provide
19 | 
20 | [Controller Classes](https://developer.wordpress.org/rest-api/extending-the-rest-api/controller-classes/): discover how to structure and extend REST API endpoint controller classes
21 | 
22 | 
23 | [Frequently Asked Questions](https://developer.wordpress.org/rest-api/frequently-asked-questions/): see some of the most frequent inquiries about the REST API and learn how to solve common problems
24 | 


--------------------------------------------------------------------------------
/using-the-rest-api.md:
--------------------------------------------------------------------------------
 1 | # Using the REST API
 2 | 
 3 | These articles explore the basic structure of the WordPress REST API.
 4 | 
 5 | [Global Parameters](https://developer.wordpress.org/rest-api/using-the-rest-api/global-parameters/): learn about the global REST API query parameters that apply to every endpoint
 6 | 
 7 | [Pagination](https://developer.wordpress.org/rest-api/using-the-rest-api/pagination/): work with large collections of resources & control how many records you receive from the REST API
 8 | 
 9 | [Linking & Embedding](https://developer.wordpress.org/rest-api/using-the-rest-api/linking-and-embedding/): understand how to read and modify connections between different objects, and embed related resources such as author and media data in the REST API's responses
10 | 
11 | [Discovery](https://developer.wordpress.org/rest-api/using-the-rest-api/discovery/): determine what REST API resources a site supports, and where they are located
12 | 
13 | [Authentication](https://developer.wordpress.org/rest-api/using-the-rest-api/authentication/): authorize your REST API requests so that you can create, update and delete your data
14 | 
15 | [Frequently Asked Questions](https://developer.wordpress.org/rest-api/frequently-asked-questions/): see some of the most frequent inquiries about the REST API and learn how to solve common problems
16 | 
17 | 
18 | ## Resources & Utilities
19 | 
20 | [Backbone.js Client](https://developer.wordpress.org/rest-api/using-the-rest-api/backbone-javascript-client/): interact with the API from within WP-Admin using Backbone models & collections
21 | 
22 | [Client Libraries](https://developer.wordpress.org/rest-api/using-the-rest-api/client-libraries/): utilities in a variety of programming languages that simplify interacting with the API
23 | 


--------------------------------------------------------------------------------
/bin/parse-wxr.php:
--------------------------------------------------------------------------------
 1 | <?php
 2 | 
 3 | $root = dirname( __DIR__ );
 4 | $reader = simplexml_load_file( __DIR__ . '/import.xml' );
 5 | 
 6 | // HTML is valid Markdown, but we should replace for comfort's sake.
 7 | $markdown_map = [
 8 | 	'<h2>'      => '## ',
 9 | 	'</h2>'     => '',
10 | 	'<h3>'      => '### ',
11 | 	'</h3>'     => '',
12 | 	'[php]'     => '```php',
13 | 	'&lt;?php'  => '<' . '?php',
14 | 	'[/php]'    => '```',
15 | 	'<code>'    => '`',
16 | 	'</code>'   => '`',
17 | 	'<em>'      => '*',
18 | 	'</em>'     => '*',
19 | 	'<strong>'  => '**',
20 | 	'</strong>' => '**',
21 | 	'“'         => '"',
22 | 	'”'         => '"',
23 | 	'’'         => "'",
24 | 	'&lt;'      => '<',
25 | 	'&gt;'      => '>',
26 | 	'&quot;'    => '"',
27 | 	'&amp;'     => '&',
28 | ];
29 | 
30 | foreach ( $reader->channel->item as $item ) {
31 | 	$title = (string) $item->title;
32 | 	$url = (string) $item->link;
33 | 	$content = (string) $item->children( 'http://purl.org/rss/1.0/modules/content/' )->encoded;
34 | 
35 | 	$wxr_item = $item->children( 'http://wordpress.org/export/1.2/' );
36 | 
37 | 	$status = (string) $wxr_item->status;
38 | 	if ( $status !== 'publish' ) {
39 | 		printf( "Skipping draft %s\n", $title );
40 | 		continue;
41 | 	}
42 | 
43 | 	$slug = str_replace( 'https://developer.wordpress.org/rest-api/', '', $url );
44 | 	if ( empty( $slug ) ) {
45 | 		$slug = 'index';
46 | 	}
47 | 
48 | 	$slug = rtrim( $slug, '/' ) . '.md';
49 | 
50 | 	$path = $root . '/' . $slug;
51 | 	if ( ! file_exists( dirname( $path ) ) ) {
52 | 		mkdir( dirname( $path ), 0755, true );
53 | 	}
54 | 	printf( "Creating %s: %s\n", $title, $path );
55 | 
56 | 	$markdowned = str_replace(
57 | 		array_keys( $markdown_map ),
58 | 		array_values( $markdown_map ),
59 | 		$content
60 | 	);
61 | 	$markdowned = preg_replace(
62 | 		'#<a href="([^"]+)">([^<]+)</a>#i',
63 | 		'[\2](\1)',
64 | 		$markdowned
65 | 	);
66 | 	$data = sprintf( "# %s\n\n%s\n", $title, $markdowned );
67 | 	// echo str_replace( "\n", "\n\t", $data ) . "\n\n";
68 | 	file_put_contents( $path, $data );
69 | }
70 | 


--------------------------------------------------------------------------------
/reference/block-pattern-categories.md:
--------------------------------------------------------------------------------
 1 | ---
 2 | ---
 3 | 
 4 | # Block Pattern Categories
 5 | 
 6 | <section class="route">
 7 | 	<div class="primary">
 8 | 		<h2>Schema</h2>
 9 | <p>The schema defines all the fields that exist within a block pattern category record. Any response from these endpoints can be expected to contain the fields below unless the `_filter` query parameter is used or the schema field only appears in a specific context.</p>
10 | <table class="attributes">
11 | 			<tr id="schema-name">
12 | 			<td>
13 | 				<code>name</code>
14 | 			</td>
15 | 			<td>
16 | 				<p>The category name.</p>
17 | 				<p class="type">
18 | 					JSON data type: string				</p>
19 | 									<p class="read-only">Read only</p>
20 | 								<p class="context">Context: <code>view</code>, <code>edit</code>, <code>embed</code></p>
21 | 							</td>
22 | 		</tr>
23 | 			<tr id="schema-label">
24 | 			<td>
25 | 				<code>label</code>
26 | 			</td>
27 | 			<td>
28 | 				<p>The category label, in human readable format.</p>
29 | 				<p class="type">
30 | 					JSON data type: string				</p>
31 | 									<p class="read-only">Read only</p>
32 | 								<p class="context">Context: <code>view</code>, <code>edit</code>, <code>embed</code></p>
33 | 							</td>
34 | 		</tr>
35 | 			<tr id="schema-description">
36 | 			<td>
37 | 				<code>description</code>
38 | 			</td>
39 | 			<td>
40 | 				<p>The category description, in human readable format.</p>
41 | 				<p class="type">
42 | 					JSON data type: string				</p>
43 | 									<p class="read-only">Read only</p>
44 | 								<p class="context">Context: <code>view</code>, <code>edit</code>, <code>embed</code></p>
45 | 							</td>
46 | 		</tr>
47 | 	</table>
48 | 
49 | 	</div>
50 | </section>
51 | 
52 | <div><section class="route">
53 | 	<div class="primary">
54 | 		<h2>Retrieve a Block Pattern Category</h2>
55 | 
56 | 		<h3>Definition & Example Request</h3>
57 | 
58 | 		<code>GET /wp/v2/block-patterns/categories</code>
59 | 
60 | 		<p>Query this endpoint to retrieve a specific block pattern category record.</p>
61 | 
62 | 		<code>$ curl https://example.com/wp-json/wp/v2/block-patterns/categories</code>
63 | 	</div>
64 | 	<div class="secondary">
65 | 			<p>There are no arguments for this endpoint.</p>
66 | 
67 | 	</div>
68 | </section>
69 | </div>
70 | 


--------------------------------------------------------------------------------
/reference/rendered-blocks.md:
--------------------------------------------------------------------------------
 1 | ---
 2 | ---
 3 | 
 4 | # Rendered Blocks
 5 | 
 6 | <section class="route">
 7 | 	<div class="primary">
 8 | 		<h2>Schema</h2>
 9 | <p>The schema defines all the fields that exist within a Rendered Block record. Any response from these endpoints can be expected to contain the fields below unless the `_filter` query parameter is used or the schema field only appears in a specific context.</p>
10 | <table class="attributes">
11 | 			<tr id="schema-rendered">
12 | 			<td>
13 | 				<code>rendered</code>
14 | 			</td>
15 | 			<td>
16 | 				<p>The rendered block.</p>
17 | 				<p class="type">
18 | 					JSON data type: string				</p>
19 | 								<p class="context">Context: <code>edit</code></p>
20 | 							</td>
21 | 		</tr>
22 | 	</table>
23 | 
24 | 	</div>
25 | </section>
26 | 
27 | <div><section class="route">
28 | 	<div class="primary">
29 | 		<h2>Create a Rendered Block</h2>
30 | 			<h3>Arguments</h3>
31 | 	<table class="arguments">
32 | 					<tr>
33 | 				<td>
34 | 											<code><a href="#schema-name">name</a></code><br />
35 | 									</td>
36 | 				<td>
37 | 											<p>Unique registered name for the block.</p>
38 | 																								</td>
39 | 			</tr>
40 | 					<tr>
41 | 				<td>
42 | 											<code><a href="#schema-context">context</a></code><br />
43 | 									</td>
44 | 				<td>
45 | 											<p>Scope under which the request is made; determines fields present in response.</p>
46 | 																					<p class="default">
47 | 							Default: <code>view</code>
48 | 						</p>
49 | 																<p>One of: <code>edit</code></p>
50 | 									</td>
51 | 			</tr>
52 | 					<tr>
53 | 				<td>
54 | 											<code><a href="#schema-attributes">attributes</a></code><br />
55 | 									</td>
56 | 				<td>
57 | 											<p>Attributes for the block.</p>
58 | 																								</td>
59 | 			</tr>
60 | 					<tr>
61 | 				<td>
62 | 											<code><a href="#schema-post_id">post_id</a></code><br />
63 | 									</td>
64 | 				<td>
65 | 											<p>ID of the post context.</p>
66 | 																								</td>
67 | 			</tr>
68 | 			</table>
69 | 
70 | 	</div>
71 | 	<div class="secondary">
72 | 		<h3>Definition</h3>
73 | 
74 | 		<code>POST /wp/v2/block-renderer/&lt;name&gt;</code>
75 | 	</div>
76 | </section>
77 | </div>
78 | 


--------------------------------------------------------------------------------
/using-the-rest-api/client-libraries.md:
--------------------------------------------------------------------------------
 1 | # Client Libraries
 2 | 
 3 | The API can be used from any application by sending basic HTTP requests; however, client libraries simplify the process of querying or creating specific resources. These libraries make it easy to connect an external application to the WordPress REST API using a variety of programming languages.
 4 | 
 5 | [alert]Aside from the Backbone.js client, these libraries are not part of WordPress core, and are not necessarily maintained or endorsed by the WordPress REST API team.[/alert]
 6 | 
 7 | [info]To perform authenticated requests from outside of the WordPress admin, themes, or plugins, a separate <a href="https://developer.wordpress.org/rest-api/authentication/#authentication-plugins">authentication plugin</a> is required.[/info]
 8 | 
 9 | ## PHP
10 | 
11 | [Requests](https://github.com/WordPress/Requests) for PHP is a general purpose HTTP request library. While not specifically designed for the WordPress REST API, it is a great tool for interacting with any HTTP API.
12 | 
13 | [WordPress-PHP-SDK](https://github.com/madeITBelgium/WordPress-PHP-SDK) is a PHP SDK for the WordPress REST API, which can be installed using [composer](https://getcomposer.org/).
14 | 
15 | [WordPress-SDK](https://github.com/storipress/wordpress-sdk) is a Laravel package for the WordPress REST API, which can be installed using [composer](https://getcomposer.org).
16 | 
17 | ## JavaScript
18 | 
19 | The [Backbone.js client](https://developer.wordpress.org/rest-api/backbone-javascript-client/) is built in to WordPress core and provides Backbone.js models &amp; collections for working with REST API resources.
20 | 
21 | [node-wpapi](http://wp-api.org/node-wpapi) is an isomorphic JavaScript client library for querying or writing to the REST API using an intuitive chaining syntax. It can be used with Node.js or with client-side JavaScript applications.
22 | 
23 | [ember-wordpress](https://github.com/oskarrough/ember-wordpress) provides a connection between Ember Data and the REST API
24 | 
25 | 
26 | ## Ruby
27 | 
28 | [wp-api-client](https://github.com/duncanjbrown/wp-api-client): a read-only REST API client written in Ruby.
29 | 
30 | ## C# / .NET
31 | [WordPressPCL](https://github.com/wp-net/WordPressPCL): a full REST API client written in C#.
32 | 
33 | ## Dart / Flutter
34 | [wordpress_client](https://pub.dev/packages/wordpress_client): A library exposing a fluent api to interact with the WordPress REST API.
35 | 


--------------------------------------------------------------------------------
/using-the-rest-api/pagination.md:
--------------------------------------------------------------------------------
 1 | # Pagination
 2 | 
 3 | WordPress sites can have a lot of content—far more than you'd want to pull down in a single request. The API endpoints default to providing a limited number of items per request, the same way that a WordPress site will default to 10 posts per page in archive views.
 4 | 
 5 | 
 6 | ## Pagination Parameters
 7 | 
 8 | Any API response which contains multiple resources supports several common query parameters to handle paging through the response data:
 9 | 
10 | * `?page=`: specify the page of results to return.
11 | 	* For example, `/wp/v2/posts?page=2` is the second page of posts results
12 | 	* By retrieving `/wp/v2/posts`, then `/wp/v2/posts?page=2`, and so on, you may access every available post through the API, one page at a time.
13 | 
14 | * `?per_page=`: specify the number of records to return in one request, specified as an integer from 1 to 100.
15 |  	* For example, `/wp/v2/posts?per_page=1` will return only the first post in the collection
16 | 
17 | * `?offset=`: specify an arbitrary offset at which to start retrieving posts
18 |  	* For example, `/wp/v2/posts?offset=6` will use the default number of posts per page, but start at the 6th post in the collection
19 |  	* `?per_page=5&page=4` is equivalent to `?per_page=5&offset=15`
20 | 
21 | [tip]
22 | Large queries can hurt site performance, so <code>per_page</code> is <strong>capped at 100 records</strong>. If you wish to retrieve more than 100 records, for example to build a client-side list of all available categories, you may make multiple API requests and combine the results within your application.
23 | [/tip]
24 | 
25 | To determine how many pages of data are available, the API returns two header fields with every paginated response:
26 | 
27 | * `X-WP-Total`: the total number of records in the collection
28 | * `X-WP-TotalPages`: the total number of pages encompassing all available records
29 | 
30 | By inspecting these header fields you can determine how much more data is available within the API.
31 | 
32 | 
33 | ## Ordering Results
34 | 
35 | In addition to the pagination query parameters detailed above, several other parameters control the order of the returned results:
36 | 
37 | * `?order=`: control whether results are returned in ascending or descending order
38 | 	* Valid values are `?order=asc` (for ascending order) and `?order=desc` (for descending order).
39 | 	* All native collections are returned in descending order by default.
40 | * `?orderby=`: control the field by which the collection is sorted
41 | 	* The valid values for `orderby` will vary depending on the queried resource; for the `/wp/v2/posts` collection, the valid values are "date," "relevance," "id," "include," "title," and "slug"
42 | 	* See the [REST API reference](https://developer.wordpress.org/rest-api/reference) for the values supported by other collections
43 | 	* All collections with dated resources default to `orderby=date`
44 | 


--------------------------------------------------------------------------------
/reference/wp_global_styles.md:
--------------------------------------------------------------------------------
  1 | ---
  2 | ---
  3 | 
  4 | # Global_Styles
  5 | 
  6 | <section class="route">
  7 | 	<div class="primary">
  8 | 		<h2>Schema</h2>
  9 | <p>The schema defines all the fields that exist within a global_styles record. Any response from these endpoints can be expected to contain the fields below unless the `_filter` query parameter is used or the schema field only appears in a specific context.</p>
 10 | <table class="attributes">
 11 | 			<tr id="schema-id">
 12 | 			<td>
 13 | 				<code>id</code>
 14 | 			</td>
 15 | 			<td>
 16 | 				<p>ID of global styles config.</p>
 17 | 				<p class="type">
 18 | 					JSON data type: string				</p>
 19 | 									<p class="read-only">Read only</p>
 20 | 								<p class="context">Context: <code>embed</code>, <code>view</code>, <code>edit</code></p>
 21 | 							</td>
 22 | 		</tr>
 23 | 			<tr id="schema-styles">
 24 | 			<td>
 25 | 				<code>styles</code>
 26 | 			</td>
 27 | 			<td>
 28 | 				<p>Global styles.</p>
 29 | 				<p class="type">
 30 | 					JSON data type: object				</p>
 31 | 								<p class="context">Context: <code>view</code>, <code>edit</code></p>
 32 | 							</td>
 33 | 		</tr>
 34 | 			<tr id="schema-settings">
 35 | 			<td>
 36 | 				<code>settings</code>
 37 | 			</td>
 38 | 			<td>
 39 | 				<p>Global settings.</p>
 40 | 				<p class="type">
 41 | 					JSON data type: object				</p>
 42 | 								<p class="context">Context: <code>view</code>, <code>edit</code></p>
 43 | 							</td>
 44 | 		</tr>
 45 | 			<tr id="schema-title">
 46 | 			<td>
 47 | 				<code>title</code>
 48 | 			</td>
 49 | 			<td>
 50 | 				<p>Title of the global styles variation.</p>
 51 | 				<p class="type">
 52 | 					JSON data type: object or string				</p>
 53 | 								<p class="context">Context: <code>embed</code>, <code>view</code>, <code>edit</code></p>
 54 | 							</td>
 55 | 		</tr>
 56 | 	</table>
 57 | 
 58 | 	</div>
 59 | </section>
 60 | 
 61 | <div><section class="route">
 62 | 	<div class="primary">
 63 | 		<h2>Retrieve a Global_Styles</h2>
 64 | 
 65 | 		<h3>Definition & Example Request</h3>
 66 | 
 67 | 		<code>GET /wp/v2/global-styles/&lt;id&gt;</code>
 68 | 
 69 | 		<p>Query this endpoint to retrieve a specific global_styles record.</p>
 70 | 
 71 | 		<code>$ curl https://example.com/wp-json/wp/v2/global-styles/&lt;id&gt;</code>
 72 | 	</div>
 73 | 	<div class="secondary">
 74 | 			<h3>Arguments</h3>
 75 | 	<table class="arguments">
 76 | 					<tr>
 77 | 				<td>
 78 | 											<code>id</code><br />
 79 | 									</td>
 80 | 				<td>
 81 | 											<p>The id of a template</p>
 82 | 																								</td>
 83 | 			</tr>
 84 | 			</table>
 85 | 
 86 | 	</div>
 87 | </section>
 88 | <section class="route">
 89 | 	<div class="primary">
 90 | 		<h2>Update a Global_Styles</h2>
 91 | 			<h3>Arguments</h3>
 92 | 	<table class="arguments">
 93 | 					<tr>
 94 | 				<td>
 95 | 											<code><a href="#schema-styles">styles</a></code><br />
 96 | 									</td>
 97 | 				<td>
 98 | 											<p>Global styles.</p>
 99 | 																								</td>
100 | 			</tr>
101 | 					<tr>
102 | 				<td>
103 | 											<code><a href="#schema-settings">settings</a></code><br />
104 | 									</td>
105 | 				<td>
106 | 											<p>Global settings.</p>
107 | 																								</td>
108 | 			</tr>
109 | 					<tr>
110 | 				<td>
111 | 											<code><a href="#schema-title">title</a></code><br />
112 | 									</td>
113 | 				<td>
114 | 											<p>Title of the global styles variation.</p>
115 | 																								</td>
116 | 			</tr>
117 | 			</table>
118 | 
119 | 	</div>
120 | 	<div class="secondary">
121 | 		<h3>Definition</h3>
122 | 
123 | 		<code>POST /wp/v2/global-styles/&lt;id&gt;</code>
124 | 
125 | 		<h3>Example Request</h3>
126 | 
127 | 		<code></code>
128 | 	</div>
129 | </section>
130 | </div>
131 | 


--------------------------------------------------------------------------------
/reference/menu-locations.md:
--------------------------------------------------------------------------------
  1 | ---
  2 | ---
  3 | 
  4 | # Menu Locations
  5 | 
  6 | <section class="route">
  7 | 	<div class="primary">
  8 | 		<h2>Schema</h2>
  9 | <p>The schema defines all the fields that exist within a menu location record. Any response from these endpoints can be expected to contain the fields below unless the `_filter` query parameter is used or the schema field only appears in a specific context.</p>
 10 | <table class="attributes">
 11 | 			<tr id="schema-name">
 12 | 			<td>
 13 | 				<code>name</code>
 14 | 			</td>
 15 | 			<td>
 16 | 				<p>The name of the menu location.</p>
 17 | 				<p class="type">
 18 | 					JSON data type: string				</p>
 19 | 									<p class="read-only">Read only</p>
 20 | 								<p class="context">Context: <code>embed</code>, <code>view</code>, <code>edit</code></p>
 21 | 							</td>
 22 | 		</tr>
 23 | 			<tr id="schema-description">
 24 | 			<td>
 25 | 				<code>description</code>
 26 | 			</td>
 27 | 			<td>
 28 | 				<p>The description of the menu location.</p>
 29 | 				<p class="type">
 30 | 					JSON data type: string				</p>
 31 | 									<p class="read-only">Read only</p>
 32 | 								<p class="context">Context: <code>embed</code>, <code>view</code>, <code>edit</code></p>
 33 | 							</td>
 34 | 		</tr>
 35 | 			<tr id="schema-menu">
 36 | 			<td>
 37 | 				<code>menu</code>
 38 | 			</td>
 39 | 			<td>
 40 | 				<p>The ID of the assigned menu.</p>
 41 | 				<p class="type">
 42 | 					JSON data type: integer				</p>
 43 | 									<p class="read-only">Read only</p>
 44 | 								<p class="context">Context: <code>embed</code>, <code>view</code>, <code>edit</code></p>
 45 | 							</td>
 46 | 		</tr>
 47 | 	</table>
 48 | 
 49 | 	</div>
 50 | </section>
 51 | 
 52 | <div><section class="route">
 53 | 	<div class="primary">
 54 | 		<h2>Retrieve a Menu Location</h2>
 55 | 
 56 | 		<h3>Definition & Example Request</h3>
 57 | 
 58 | 		<code>GET /wp/v2/menu-locations</code>
 59 | 
 60 | 		<p>Query this endpoint to retrieve a specific menu location record.</p>
 61 | 
 62 | 		<code>$ curl https://example.com/wp-json/wp/v2/menu-locations</code>
 63 | 	</div>
 64 | 	<div class="secondary">
 65 | 			<h3>Arguments</h3>
 66 | 	<table class="arguments">
 67 | 					<tr>
 68 | 				<td>
 69 | 											<code>context</code><br />
 70 | 									</td>
 71 | 				<td>
 72 | 											<p>Scope under which the request is made; determines fields present in response.</p>
 73 | 																					<p class="default">
 74 | 							Default: <code>view</code>
 75 | 						</p>
 76 | 																<p>One of: <code>view</code>, <code>embed</code>, <code>edit</code></p>
 77 | 									</td>
 78 | 			</tr>
 79 | 			</table>
 80 | 
 81 | 	</div>
 82 | </section>
 83 | <section class="route">
 84 | 	<div class="primary">
 85 | 		<h2>Retrieve a Menu Location</h2>
 86 | 
 87 | 		<h3>Definition & Example Request</h3>
 88 | 
 89 | 		<code>GET /wp/v2/menu-locations/&lt;location&gt;</code>
 90 | 
 91 | 		<p>Query this endpoint to retrieve a specific menu location record.</p>
 92 | 
 93 | 		<code>$ curl https://example.com/wp-json/wp/v2/menu-locations/&lt;location&gt;</code>
 94 | 	</div>
 95 | 	<div class="secondary">
 96 | 			<h3>Arguments</h3>
 97 | 	<table class="arguments">
 98 | 					<tr>
 99 | 				<td>
100 | 											<code>location</code><br />
101 | 									</td>
102 | 				<td>
103 | 											<p>An alphanumeric identifier for the menu location.</p>
104 | 																								</td>
105 | 			</tr>
106 | 					<tr>
107 | 				<td>
108 | 											<code>context</code><br />
109 | 									</td>
110 | 				<td>
111 | 											<p>Scope under which the request is made; determines fields present in response.</p>
112 | 																					<p class="default">
113 | 							Default: <code>view</code>
114 | 						</p>
115 | 																<p>One of: <code>view</code>, <code>embed</code>, <code>edit</code></p>
116 | 									</td>
117 | 			</tr>
118 | 			</table>
119 | 
120 | 	</div>
121 | </section>
122 | </div>
123 | 


--------------------------------------------------------------------------------
/key-concepts.md:
--------------------------------------------------------------------------------
 1 | # Key Concepts
 2 | 
 3 | In this page we'll break down some of the key concepts and terms associated with the REST API: **Routes & Endpoints,** **Requests**, **Responses**, **Schema**, and **Controller Classes**. Each of these concepts play a crucial role in understanding, using, and extending the WordPress REST API, and each is explored in greater depth within this handbook.
 4 | 
 5 | ## Routes & Endpoints
 6 | 
 7 | In the context of the WordPress REST API a **route** 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**.
 8 | 
 9 | As an example, if we make a `GET` request to the URI <code>http://oursite.com/wp-json/</code> we are returned a JSON response showing what routes are available, and what endpoints are available within each route. 
10 | 
11 | `/wp-json/` is a route, and when that route receives a `GET` request then that request is handled by the endpoint which displays what is known as the index for the WordPress REST API. 
12 | 
13 | The route `wp-json/wp/v2/posts` by contrast has a `GET` endpoint which returns a list of posts, but also a `POST` endpoint which accepts authenticated requests to create new posts.
14 | 
15 | We will learn how to register our own routes and endpoints in the following sections.
16 | 
17 | [info]If you are 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 <code>http://oursite.com/wp-json/</code> in the example above would hence be <code>http://oursite.com/?rest_route=/</code>.[/info]
18 | 
19 | If you get a `404` error when trying to access <code>http://oursite.com/wp-json/</code>, consider enabling pretty permalinks or try using the `rest_route` parameter instead.
20 | 
21 | ## Requests
22 | 
23 | A REST API request is represented within WordPress by an instance of the `WP_REST_Request` class, which is used to store and retrieve information for the current request. A `WP_REST_Request` object is automatically generated when you make an HTTP request to a registered API route. 
24 | 
25 | The data specified in this object (derived from the route URI or the JSON payload sent as a part of the request) determines what response you will get back out of the API.
26 | 
27 | Requests are usually submitted remotely via HTTP but may also be made internally from PHP within WordPress plugin or theme code. There are a lot of neat things you can do using this class, detailed further elsewhere in the handbook.
28 | 
29 | ## Responses
30 | 
31 | 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 return the requested data, or can also be used to return errors if something goes wrong while fulfilling the request.
32 | 
33 | ## Schema
34 | 
35 | Each endpoint requires a particular structure of input data, and returns data using a defined and predictable structure. Those data structures are defined in the API Schema. 
36 | 
37 | The schema structures API data and provides a comprehensive list of all of the properties the API can return and which input parameters it can accept. 
38 | 
39 | Well-defined schema also provides one layer of security within the API, as it enables us to validate and sanitize the requests being made to the API. The [Schema section](https://developer.wordpress.org/rest-api/extending-the-rest-api/schema/) explores this large topic further.
40 | 
41 | 
42 | ## Controller Classes
43 | 
44 | Controller classes unify and coordinate all these various moving parts within a REST API response cycle. With a controller class you can manage the registration of routes & endpoints, handle requests, utilize schema, and generate API responses. 
45 | 
46 | A single class usually contains all of the logic for a given route, and a given route usually represents a specific type of data object within your WordPress site (like a custom post type or taxonomy).


--------------------------------------------------------------------------------
/using-the-rest-api/linking-and-embedding.md:
--------------------------------------------------------------------------------
 1 | # Linking and Embedding
 2 | 
 3 | The WP REST API incorporates hyperlinking throughout the API to allow discoverability and browsability, as well as embedding related resources together in one response. While the REST API does not completely conform to the entire [HAL standard](https://en.wikipedia.org/wiki/Hypertext_Application_Language), it implements the `._links` and `._embedded` properties from that standard as described below.
 4 | 
 5 | 
 6 | ## Links
 7 | 
 8 | The `_links` property of the response object contains a map of links to other API resources, grouped by "relation." The relation specifies how the linked resource relates to the primary resource. 
 9 | 
10 | Examples include: 
11 | - `author` - describing a relationship between a resource and its author
12 | - `wp:term` - describing the relationship between a post and its tags or categories 
13 | 
14 | The relation is either a 
15 | - [standardized relation](http://www.iana.org/assignments/link-relations/link-relations.xhtml#link-relations-1)
16 | - a `URI relation` - like <code>https://api.w.org/term</code>
17 | - or a `Compact URI relation` - like `wp:term`
18 | 
19 |  Compact URI relations can be normalized to full URI relations to ensure full compatibility if required. This is similar to HTML `<link>` tags, or `<a rel="">` links.
20 | 
21 | The links are an object containing a `href` property with an absolute URL to the resource, as well as other optional properties. These include content types, disambiguation information, and data on actions that can be taken with the link.
22 | 
23 | For collection responses (those that return a list of objects rather than a top-level object), each item contains links, and the top-level response includes links via the `Link` header instead.
24 | 
25 | [info]
26 | If your client library does not allow accessing headers, you can use the <a href="https://developer.wordpress.org/rest-api/global-parameters/#envelope"><code>_envelope</code></a> parameter to include the headers as body data instead.
27 | [/info]
28 | 
29 | 
30 | ### Example Response
31 | 
32 | A typical single post request (`/wp/v2/posts/42`):
33 | 
34 | ```js
35 | {
36 |   "id": 42,
37 |   "_links": {
38 |     "collection": [
39 |       {
40 |         "href": "https://example.com/wp-json/wp/v2/posts"
41 |       }
42 |     ],
43 |     "author": [
44 |       {
45 |         "href": "https://example.com/wp-json/wp/v2/users/1",
46 |         "embeddable": true
47 |       }
48 |     ]
49 |   }
50 | }
51 | ```
52 | 
53 | 
54 | ## Embedding
55 | 
56 | Optionally, some linked resources may be included in the response to reduce the number of HTTP requests required. These resources are "embedded" into the main response.
57 | 
58 | Embedding is triggered by setting the [`_embed` query parameter](https://developer.wordpress.org/rest-api/using-the-rest-api/global-parameters/#_embed) on the request. This will then include embedded resources under the `_embedded` key adjacent to the `_links` key. The layout of this object mirrors the `_links` object, but includes the embedded resource in place of the link properties.
59 | 
60 | Only links with the `embeddable` flag set to `true` can be embedded, and `_embed` will cause all embeddable links to be embedded. Only relations containing embedded responses are included in `_embedded`, however relations with mixed embeddable and unembeddable links will contain dummy responses for the unembeddable links to ensure numeric indexes match those in `_links`.
61 | 
62 | When embedding a collection response, for instance `/wp/v2/posts?author=1`, the embedded collection will have the default pagination limits applied.
63 | 
64 | ### Example Response
65 | 
66 | ```js
67 | {
68 |   "id": 42,
69 |   "_links": {
70 |     "collection": [
71 |       {
72 |         "href": "https://example.com/wp-json/wp/v2/posts"
73 |       }
74 |     ],
75 |     "author": [
76 |       {
77 |         "href": "https://example.com/wp-json/wp/v2/users/1",
78 |         "embeddable": true
79 |       }
80 |     ]
81 |   },
82 |   "_embedded": {
83 |     "author": {
84 |       "id": 1,
85 |       "name": "admin",
86 |       "description": "Site administrator"
87 |     }
88 |   }
89 | }
90 | ```


--------------------------------------------------------------------------------
/glossary.md:
--------------------------------------------------------------------------------
 1 | # Glossary
 2 | 
 3 | New to REST APIs? Get up to speed with phrases used throughout our documentation.
 4 | 
 5 | 
 6 | <h2 id="controller">Controller</h2>
 7 | 
 8 | [Model-View-Controller](http://en.wikipedia.org/wiki/Model-view-controller) is a standard pattern in software development. If you aren't already familiar with it, you should do a bit of reading to get up to speed.
 9 | 
10 | Within WP-API, we've adopted the controller concept to have a standard pattern for the classes representing our resource endpoints. All resource endpoints extend `WP_REST_Controller` to ensure they implement common methods.
11 | 
12 | 
13 | <h2 id="head-get-post-put-and-delete-requests">HEAD, GET, POST, PUT, and DELETE Requests</h2>
14 | 
15 | These "HTTP verbs" represent the *type* of action a HTTP client might perform against a resource. For instance, `GET` requests are used to fetch a Post's data, whereas `DELETE` requests are used to delete a Post. They're collectively called "HTTP verbs" because they're standardized across the web.
16 | 
17 | If you're familiar with WordPress functions, a `GET` request is the equivalent of `wp_remote_get()`, and a `POST` request is the same as `wp_remote_post()`.
18 | 
19 | 
20 | <h2 id="http-client">HTTP Client</h2>
21 | 
22 | The phrase "HTTP Client" refers to the tool you use to interact with WP-API. You might use [Postman](https://chrome.google.com/webstore/detail/postman-rest-client/fdmmgilgnpjigdojojpjoooidkmcomcm?hl=en) (Chrome) or [REST Easy](https://github.com/nathan-osman/REST-Easy) (Firefox) to test requests in your browser, or [httpie](https://github.com/jakubroztocil/httpie) to test requests at the commandline.
23 | 
24 | WordPress itself provides a HTTP Client in the [`WP_HTTP` class](https://developer.wordpress.org/plugins/http-api/) and related functions (e.g. `wp_remote_get()`). This can be used to access one WordPress site from another.
25 | 
26 | 
27 | <h2 id="resource">Resource</h2>
28 | 
29 | A "Resource" is a *discrete entity* within WordPress. You may know these resources already as Posts, Pages, Comments, Users, Terms, and so on. WP-API permits HTTP clients to perform CRUD operations against resources (CRUD stands for Create, Read, Update, and Delete).
30 | 
31 | Pragmatically, here's how you'd typically interact with WP-API resources:
32 | 
33 | * `GET /wp-json/wp/v2/posts` to get a collection of Posts. This is roughly equivalent to using `WP_Query`.
34 | * `GET /wp-json/wp/v2/posts/123` to get a single Post with ID 123. This is roughly equivalent to using `get_post()`.
35 | * `POST /wp-json/wp/v2/posts` to create a new Post. This is roughly equivalent to using `wp_insert_post()`.
36 | * `DELETE /wp-json/wp/v2/posts/123` to delete Post with ID 123. This is roughly equivalent to `wp_delete_post()`.
37 | 
38 | 
39 | <h2 id="routes--endpoints">Routes / Endpoints</h2>
40 | 
41 | Endpoints are functions available through the API. This can be things like retrieving the API index, updating a post, or deleting a comment. Endpoints perform a specific function, taking some number of parameters and return data to the client.
42 | 
43 | A route is the "name" you use to access endpoints, used in the URL. A route can have multiple endpoints associated with it, and which is used depends on the HTTP verb.
44 | 
45 | For example, with the URL `http://example.com/wp-json/wp/v2/posts/123`:
46 | 
47 | * The "route" is `wp/v2/posts/123` - The route doesn't include `wp-json` because `wp-json` is the base path for the API itself.
48 | * This route has 3 endpoints:
49 |   * `GET` triggers a `get_item` method, returning the post data to the client.
50 |   * `PUT` triggers an `update_item` method, taking the data to update, and returning the updated post data.
51 |   * `DELETE` triggers a `delete_item` method, returning the now-deleted post data to the client.
52 | 
53 | **Note:** On sites without pretty permalinks, the route is instead added to the URL as the `rest_route` parameter. For the above example, the full URL would then be `http://example.com/?rest_route=wp/v2/posts/123`
54 | 
55 | 
56 | <h2 id="schema">Schema</h2>
57 | 
58 | A "schema" is a representation of the format for WP-API's response data. For instance, the Post schema communicates that a request to get a Post will return `id`, `title`, `content`, `author`, and other fields. Our schemas also indicate the type each field is, provide a human-readable description, and show which contexts the field will be returned in.
59 | 


--------------------------------------------------------------------------------
/reference/widget-types.md:
--------------------------------------------------------------------------------
  1 | ---
  2 | ---
  3 | 
  4 | # Widget Types
  5 | 
  6 | <section class="route">
  7 | 	<div class="primary">
  8 | 		<h2>Schema</h2>
  9 | <p>The schema defines all the fields that exist within a widget type record. Any response from these endpoints can be expected to contain the fields below unless the `_filter` query parameter is used or the schema field only appears in a specific context.</p>
 10 | <table class="attributes">
 11 | 			<tr id="schema-id">
 12 | 			<td>
 13 | 				<code>id</code>
 14 | 			</td>
 15 | 			<td>
 16 | 				<p>Unique slug identifying the widget type.</p>
 17 | 				<p class="type">
 18 | 					JSON data type: string				</p>
 19 | 									<p class="read-only">Read only</p>
 20 | 								<p class="context">Context: <code>embed</code>, <code>view</code>, <code>edit</code></p>
 21 | 							</td>
 22 | 		</tr>
 23 | 			<tr id="schema-name">
 24 | 			<td>
 25 | 				<code>name</code>
 26 | 			</td>
 27 | 			<td>
 28 | 				<p>Human-readable name identifying the widget type.</p>
 29 | 				<p class="type">
 30 | 					JSON data type: string				</p>
 31 | 									<p class="read-only">Read only</p>
 32 | 								<p class="context">Context: <code>embed</code>, <code>view</code>, <code>edit</code></p>
 33 | 							</td>
 34 | 		</tr>
 35 | 			<tr id="schema-description">
 36 | 			<td>
 37 | 				<code>description</code>
 38 | 			</td>
 39 | 			<td>
 40 | 				<p>Description of the widget.</p>
 41 | 				<p class="type">
 42 | 					JSON data type: string				</p>
 43 | 								<p class="context">Context: <code>view</code>, <code>edit</code>, <code>embed</code></p>
 44 | 							</td>
 45 | 		</tr>
 46 | 			<tr id="schema-is_multi">
 47 | 			<td>
 48 | 				<code>is_multi</code>
 49 | 			</td>
 50 | 			<td>
 51 | 				<p>Whether the widget supports multiple instances</p>
 52 | 				<p class="type">
 53 | 					JSON data type: boolean				</p>
 54 | 									<p class="read-only">Read only</p>
 55 | 								<p class="context">Context: <code>view</code>, <code>edit</code>, <code>embed</code></p>
 56 | 							</td>
 57 | 		</tr>
 58 | 			<tr id="schema-classname">
 59 | 			<td>
 60 | 				<code>classname</code>
 61 | 			</td>
 62 | 			<td>
 63 | 				<p>Class name</p>
 64 | 				<p class="type">
 65 | 					JSON data type: string				</p>
 66 | 									<p class="read-only">Read only</p>
 67 | 								<p class="context">Context: <code>embed</code>, <code>view</code>, <code>edit</code></p>
 68 | 							</td>
 69 | 		</tr>
 70 | 	</table>
 71 | 
 72 | 	</div>
 73 | </section>
 74 | 
 75 | <div><section class="route">
 76 | 	<div class="primary">
 77 | 		<h2>Retrieve a Widget Type</h2>
 78 | 
 79 | 		<h3>Definition & Example Request</h3>
 80 | 
 81 | 		<code>GET /wp/v2/widget-types</code>
 82 | 
 83 | 		<p>Query this endpoint to retrieve a specific widget type record.</p>
 84 | 
 85 | 		<code>$ curl https://example.com/wp-json/wp/v2/widget-types</code>
 86 | 	</div>
 87 | 	<div class="secondary">
 88 | 			<h3>Arguments</h3>
 89 | 	<table class="arguments">
 90 | 					<tr>
 91 | 				<td>
 92 | 											<code>context</code><br />
 93 | 									</td>
 94 | 				<td>
 95 | 											<p>Scope under which the request is made; determines fields present in response.</p>
 96 | 																					<p class="default">
 97 | 							Default: <code>view</code>
 98 | 						</p>
 99 | 																<p>One of: <code>view</code>, <code>embed</code>, <code>edit</code></p>
100 | 									</td>
101 | 			</tr>
102 | 			</table>
103 | 
104 | 	</div>
105 | </section>
106 | <section class="route">
107 | 	<div class="primary">
108 | 		<h2>Retrieve a Widget Type</h2>
109 | 
110 | 		<h3>Definition & Example Request</h3>
111 | 
112 | 		<code>GET /wp/v2/widget-types/&lt;id&gt;</code>
113 | 
114 | 		<p>Query this endpoint to retrieve a specific widget type record.</p>
115 | 
116 | 		<code>$ curl https://example.com/wp-json/wp/v2/widget-types/&lt;id&gt;</code>
117 | 	</div>
118 | 	<div class="secondary">
119 | 			<h3>Arguments</h3>
120 | 	<table class="arguments">
121 | 					<tr>
122 | 				<td>
123 | 											<code>id</code><br />
124 | 									</td>
125 | 				<td>
126 | 											<p>The widget type id.</p>
127 | 																								</td>
128 | 			</tr>
129 | 					<tr>
130 | 				<td>
131 | 											<code>context</code><br />
132 | 									</td>
133 | 				<td>
134 | 											<p>Scope under which the request is made; determines fields present in response.</p>
135 | 																					<p class="default">
136 | 							Default: <code>view</code>
137 | 						</p>
138 | 																<p>One of: <code>view</code>, <code>embed</code>, <code>edit</code></p>
139 | 									</td>
140 | 			</tr>
141 | 			</table>
142 | 
143 | 	</div>
144 | </section>
145 | </div>
146 | 


--------------------------------------------------------------------------------
/using-the-rest-api/authentication.md:
--------------------------------------------------------------------------------
 1 | # Authentication
 2 | 
 3 | ## Cookie Authentication
 4 | 
 5 | Cookie authentication is the standard authentication method included with WordPress. When you log in to your dashboard, this sets up the cookies correctly for you, so plugin and theme developers need only to have a logged-in user.
 6 | 
 7 | However, the REST API includes a technique called [nonces](https://developer.wordpress.org/apis/security/nonces/) to avoid [CSRF](http://en.wikipedia.org/wiki/Cross-site_request_forgery) issues. This prevents other sites from forcing you to perform actions without explicitly intending to do so. This requires slightly special handling for the API.
 8 | 
 9 | For developers using the built-in Javascript API, this is handled automatically for you. This is the recommended way to use the API for plugins and themes. Custom data models can extend `wp.api.models.Base` to ensure this is sent correctly for any custom requests.
10 | 
11 | For developers making manual Ajax requests, the nonce will need to be passed with each request. The API uses nonces with the action set to `wp_rest`. These can then be passed to the API via the `_wpnonce` data parameter (either POST data or in the query for GET requests), or via the `X-WP-Nonce` header. If no nonce is provided the API will set the current user to 0, turning the request into an **unauthenticated request**, even if you're logged into WordPress.
12 | 
13 | Note: Until recently, most software had spotty support for `DELETE` requests. For instance, PHP doesn't transform the request body of a `DELETE` request into a super global. As such, supplying the nonce as a header is the most reliable approach.
14 | 
15 | It is important to keep in mind that this authentication method relies on WordPress cookies. As a result this method is only applicable when the REST API is used inside of WordPress and the current user is logged in. In addition, the current user must have the appropriate capability to perform the action being performed.
16 | 
17 | As an example, this is how the built-in Javascript client creates the nonce:
18 | 
19 | ```php
20 | <?php
21 | wp_localize_script( 'wp-api', 'wpApiSettings', array(
22 | 	'root' => esc_url_raw( rest_url() ),
23 | 	'nonce' => wp_create_nonce( 'wp_rest' )
24 | ) );
25 | ```
26 | 
27 | This is then used in the base model:
28 | 
29 | ```js
30 | options.beforeSend = function(xhr) {
31 | 	xhr.setRequestHeader('X-WP-Nonce', wpApiSettings.nonce);
32 | 
33 | 	if (beforeSend) {
34 | 		return beforeSend.apply(this, arguments);
35 | 	}
36 | };
37 | ```
38 | 
39 | Here is an example of editing the title of a post, using jQuery AJAX:
40 | 
41 | ```js
42 | $.ajax( {
43 | 	url: wpApiSettings.root + 'wp/v2/posts/1',
44 | 	method: 'POST',
45 | 	beforeSend: function ( xhr ) {
46 | 		xhr.setRequestHeader( 'X-WP-Nonce', wpApiSettings.nonce );
47 | 	},
48 | 	data:{
49 | 		'title' : 'Hello Moon'
50 | 	}
51 | } ).done( function ( response ) {
52 | 	console.log( response );
53 | } );
54 | ```
55 | 
56 | Note that you do not need to verify that the nonce is valid inside your custom end point. This is automatically done for you in `rest_cookie_check_errors()`.
57 | 
58 | ## Basic Authentication with Application Passwords
59 | 
60 | As of 5.6, WordPress has shipped with [Application Passwords](https://make.wordpress.org/core/2020/11/05/application-passwords-integration-guide/), which can be generated from an Edit User page (wp-admin -> Users -> Edit User). 
61 | 
62 | The credentials can be passed along to REST API requests served over https:// using [Basic Auth](https://ec.haxx.se/libcurl-http/auth.html#basic) / [RFC 7617](https://tools.ietf.org/html/rfc7617) — [here’s the documentation for how to use it with cURL](https://ec.haxx.se/http/auth.html).
63 | 
64 | For a simple command-line script example, just swap out USERNAME, PASSWORD, and HOSTNAME in this with their respective values:
65 | 
66 | ```
67 | curl --user "USERNAME:PASSWORD" https://HOSTNAME/wp-json/wp/v2/users?context=edit
68 | ```
69 | 
70 | ## Authentication Plugins
71 | 
72 | Plugins may be added to support alternative modes of authentication that will work from remote applications. Some example plugins are [OAuth 1.0a Server](https://wordpress.org/plugins/rest-api-oauth1/) and [JSON Web Tokens](https://wordpress.org/plugins/jwt-authentication-for-wp-rest-api/).
73 | 
74 | [info]
75 | 
76 | There's also a [Basic Authentication](https://github.com/WP-API/Basic-Auth) plugin.
77 | 
78 | 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. Using Application Passwords (see above) is preferred.
79 | 
80 | [/info]
81 | 


--------------------------------------------------------------------------------
/index.md:
--------------------------------------------------------------------------------
 1 | # REST API Handbook
 2 | 
 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.
 4 | 
 5 | Using the WordPress REST API you can create a plugin to provide an entirely new admin experience for WordPress, build a brand new interactive front-end experience, or bring your WordPress content into completely separate applications.
 6 | 
 7 | The REST API is a developer-oriented feature of WordPress. It provides data access to the content of your site, and implements the same authentication restrictions -- content that is public on your site is generally publicly accessible via the REST API, while private content, password-protected content, internal users, custom post types, and metadata is only available with authentication or if you specifically set it to be so. If you are not a developer, the most important thing to understand about the API is that it enables the block editor and modern plugin interfaces without compromising the security or privacy of your site.
 8 | 
 9 | ## What Is A REST API?
10 | 
11 | 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 and 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.
12 | 
13 | [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]
14 | 
15 | ## Using the WordPress REST API 
16 | 
17 | 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.
18 | 
19 | 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.
20 | 
21 | 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.
22 | 
23 | 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.
24 | 
25 | 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.
26 | 
27 | ## Next Steps
28 | 
29 | Familiarize yourself with the [key technical concepts](https://developer.wordpress.org/rest-api/key-concepts/) behind how the REST API functions.
30 | 
31 | Learn more about how to interact with API resources and query for specific data in the [Using the REST API](https://developer.wordpress.org/rest-api/using-the-rest-api/) section.
32 | 
33 | Once you're comfortable with the default workings of the default routes and methods, discover how to add new data to the API or enhance and manipulate existing response objects in the [Extending the REST API](https://developer.wordpress.org/rest-api/extending-the-rest-api/) section.
34 | 
35 | For a comprehensive overview of the resources and routes available by default, review the [API reference](https://developer.wordpress.org/rest-api/reference/).
36 | 


--------------------------------------------------------------------------------
/bin/regenerate.php:
--------------------------------------------------------------------------------
  1 | #!/usr/bin/env php
  2 | <?php
  3 | 
  4 | namespace WPAPI\Docs\Regenerate;
  5 | 
  6 | use Twig;
  7 | use WpOrg\Requests\Requests;
  8 | 
  9 | require dirname( __DIR__ ) . '/vendor/autoload.php';
 10 | 
 11 | // This assumes you have a local WP VM running the latest stable WP, mapped to
 12 | // use the domain name example.com using /etc/hosts. http://demo.wp-api.org is
 13 | // also available, though may be outdated.
 14 | const SITE_URL = 'http://example.com';
 15 | 
 16 | function update_route( $route ) {
 17 | 	foreach ( $route['endpoints'] as &$endpoint ) {
 18 | 		if ( in_array( 'POST', $endpoint['methods'] ) ) {
 19 | 			if ( ! in_array( 'PUT', $endpoint['methods'] ) ) {
 20 | 				$endpoint['type'] = 'create-item';
 21 | 			} else {
 22 | 				$endpoint['type'] = 'update-item';
 23 | 			}
 24 | 		} elseif ( in_array( 'DELETE', $endpoint['methods'] ) ) {
 25 | 			$endpoint['type'] = 'delete-item';
 26 | 		} elseif ( isset( $endpoint['args']['page'] ) ) {
 27 | 			$endpoint['type'] = 'list-item';
 28 | 		} else {
 29 | 			$endpoint['type'] = 'get-item';
 30 | 		}
 31 | 	}
 32 | 
 33 | 	return $route;
 34 | }
 35 | 
 36 | /**
 37 |  * Ingest a title string and ensure any kebab-casing or wp_-prefixing is removed.
 38 |  */
 39 | function cleanup_name( string $name ) : string {
 40 | 	return preg_replace( '/WP_/i', '', implode( ' ', explode( '-', $name ) ) );
 41 | }
 42 | 
 43 | function add_simple_schemas() {
 44 | 	$objects = [];
 45 | 
 46 | 	$response = Requests::get( SITE_URL . '?rest_route=/&context=help' );
 47 | 
 48 | 	$parsed_data = json_decode( $response->body, true );
 49 | 
 50 | 	foreach ( $parsed_data['routes'] as $key => $route ) {
 51 | 		if ( ! isset( $route['schema'] ) ) {
 52 | 			continue;
 53 | 		}
 54 | 
 55 | 		# make a readable route name from the route regex
 56 | 		$route_nicename = preg_replace( '/\(\?P<(\w+?)>.*?\)/', '<\1>', $key );
 57 | 		$route['nicename'] = $route_nicename;
 58 | 
 59 | 		# group the objects by unique schema titles [ post => ..., term => ..., etc ]
 60 | 		$title = $route['schema']['title'];
 61 | 
 62 | 		# pluralise, super-dodgy.
 63 | 		if ( substr( $title, -1 ) === 's' ) {
 64 | 			$plural = $title;
 65 | 		} else {
 66 | 			$plural = substr( $title, -1 ) === 'y' ? substr( $title, 0, -1 ) . 'ies' : $title . 's';
 67 | 		}
 68 | 		$key = $plural;
 69 | 
 70 | 		# overrides
 71 | 		switch ( $title ) {
 72 | 			case 'attachment':
 73 | 				$key = 'media';
 74 | 				$title = 'Media Item';
 75 | 				$plural = 'media';
 76 | 				break;
 77 | 
 78 | 			case 'rendered-block':
 79 | 				$key = 'rendered-blocks';
 80 | 				$title = 'Rendered Block';
 81 | 				$plural = 'Rendered Blocks';
 82 | 				break;
 83 | 
 84 | 			case 'settings':
 85 | 				$key = 'settings';
 86 | 				$title = 'Site Setting';
 87 | 				$plural = 'Site Settings';
 88 | 			break;
 89 | 
 90 | 			case 'status':
 91 | 				$plural = 'statuses';
 92 | 				$key = 'post-statuses';
 93 | 				break;
 94 | 
 95 | 			case 'type':
 96 | 				$key = 'post-types';
 97 | 				break;
 98 | 
 99 | 			case 'wp_block':
100 | 				$key = 'blocks';
101 | 				$title = 'Editor Block';
102 | 				$plural = 'Editor Blocks';
103 | 				break;
104 | 
105 | 			case 'wp_block-revision':
106 | 				$key = 'block-revisions';
107 | 				$title = 'Block Revision';
108 | 				$plural = 'Block Revisions';
109 | 				break;
110 | 
111 | 			default:
112 | 				// Fallback title cleaning logic, to remove kebab-casing, etcetera.
113 | 				$title = cleanup_name( $title );
114 | 				$plural = cleanup_name( $plural );
115 | 		}
116 | 
117 | 		if ( ! isset( $objects[ $key ] ) ) {
118 | 			$objects[ $key ] = [
119 | 				'name'   => $title,
120 | 				'plural' => $plural,
121 | 				'routes' => [ $route_nicename => update_route( $route ) ],
122 | 				'schema' => $route['schema'],
123 | 			];
124 | 		} else {
125 | 			$objects[ $key ]['routes'][ $route_nicename ] = update_route( $route );
126 | 		}
127 | 	}
128 | 
129 | 	return $objects;
130 | }
131 | 
132 | function add_terms_schema() {
133 | 	$response = Requests::options( SITE_URL . '?rest_route=/wp/v2/terms/category' );
134 | 	$file = fopen( '_data/terms.json', 'w' );
135 | 	$parsed_data = json_decode( $response->body );
136 | 
137 | 	# puts data
138 | 	fwrite( $file, json_encode( $parsed_data, JSON_PRETTY_PRINT | JSON_UNESCAPED_SLASHES ) );
139 | 	fclose( $file );
140 | }
141 | 
142 | function twig() {
143 | 	static $twig;
144 | 	if ( ! empty( $twig ) ) {
145 | 		return $twig;
146 | 	}
147 | 
148 | 	$loader = new Twig\Loader\FilesystemLoader( __DIR__ . '/templates' );
149 | 
150 | 	$twig = new Twig\Environment( $loader, [
151 | 	    'cache' => false,
152 | 	] );
153 | 	return $twig;
154 | }
155 | 
156 | function generate_reference() {
157 | 	$template = twig()->load( 'endpoint.md' );
158 | 
159 | 	$schemas = add_simple_schemas();
160 | 	$rendered = [];
161 | 	foreach ( $schemas as $key => $value ) {
162 | 		$rendered[ $key ] = $template->render( $value );
163 | 		file_put_contents( dirname( __DIR__ ) . '/reference/' . $key . '.md', $rendered[ $key ] );
164 | 	}
165 | }
166 | 
167 | generate_reference();
168 | 


--------------------------------------------------------------------------------
/reference/search-results.md:
--------------------------------------------------------------------------------
  1 | ---
  2 | ---
  3 | 
  4 | # Search Results
  5 | 
  6 | <section class="route">
  7 | 	<div class="primary">
  8 | 		<h2>Schema</h2>
  9 | <p>The schema defines all the fields that exist within a search result record. Any response from these endpoints can be expected to contain the fields below unless the `_filter` query parameter is used or the schema field only appears in a specific context.</p>
 10 | <table class="attributes">
 11 | 			<tr id="schema-id">
 12 | 			<td>
 13 | 				<code>id</code>
 14 | 			</td>
 15 | 			<td>
 16 | 				<p>Unique identifier for the object.</p>
 17 | 				<p class="type">
 18 | 					JSON data type: integer or string				</p>
 19 | 									<p class="read-only">Read only</p>
 20 | 								<p class="context">Context: <code>view</code>, <code>embed</code></p>
 21 | 							</td>
 22 | 		</tr>
 23 | 			<tr id="schema-title">
 24 | 			<td>
 25 | 				<code>title</code>
 26 | 			</td>
 27 | 			<td>
 28 | 				<p>The title for the object.</p>
 29 | 				<p class="type">
 30 | 					JSON data type: string				</p>
 31 | 									<p class="read-only">Read only</p>
 32 | 								<p class="context">Context: <code>view</code>, <code>embed</code></p>
 33 | 							</td>
 34 | 		</tr>
 35 | 			<tr id="schema-url">
 36 | 			<td>
 37 | 				<code>url</code>
 38 | 			</td>
 39 | 			<td>
 40 | 				<p>URL to the object.</p>
 41 | 				<p class="type">
 42 | 					JSON data type: string,
 43 | 											Format: uri
 44 | 									</p>
 45 | 									<p class="read-only">Read only</p>
 46 | 								<p class="context">Context: <code>view</code>, <code>embed</code></p>
 47 | 							</td>
 48 | 		</tr>
 49 | 			<tr id="schema-type">
 50 | 			<td>
 51 | 				<code>type</code>
 52 | 			</td>
 53 | 			<td>
 54 | 				<p>Object type.</p>
 55 | 				<p class="type">
 56 | 					JSON data type: string				</p>
 57 | 									<p class="read-only">Read only</p>
 58 | 								<p class="context">Context: <code>view</code>, <code>embed</code></p>
 59 | 									<p>One of: <code>post</code>, <code>term</code>, <code>post-format</code></p>
 60 | 							</td>
 61 | 		</tr>
 62 | 			<tr id="schema-subtype">
 63 | 			<td>
 64 | 				<code>subtype</code>
 65 | 			</td>
 66 | 			<td>
 67 | 				<p>Object subtype.</p>
 68 | 				<p class="type">
 69 | 					JSON data type: string				</p>
 70 | 									<p class="read-only">Read only</p>
 71 | 								<p class="context">Context: <code>view</code>, <code>embed</code></p>
 72 | 									<p>One of: <code>post</code>, <code>page</code>, <code>category</code>, <code>post_tag</code></p>
 73 | 							</td>
 74 | 		</tr>
 75 | 	</table>
 76 | 
 77 | 	</div>
 78 | </section>
 79 | 
 80 | <div><section class="route">
 81 | 	<div class="primary">
 82 | 		<h2>List Search Results</h2>
 83 | 		<p>Query this endpoint to retrieve a collection of search results. The response you receive can be controlled and filtered using the URL query parameters below.</p>
 84 | 
 85 | 		<h3>Definition</h3>
 86 | 
 87 | 		<code>GET /wp/v2/search</code>
 88 | 
 89 | 		<h3>Example Request</h3>
 90 | 
 91 | 		<code>$ curl https://example.com/wp-json/wp/v2/search</code>
 92 | 	</div>
 93 | 	<div class="secondary">
 94 | 			<h3>Arguments</h3>
 95 | 	<table class="arguments">
 96 | 					<tr>
 97 | 				<td>
 98 | 											<code>context</code><br />
 99 | 									</td>
100 | 				<td>
101 | 											<p>Scope under which the request is made; determines fields present in response.</p>
102 | 																					<p class="default">
103 | 							Default: <code>view</code>
104 | 						</p>
105 | 																<p>One of: <code>view</code>, <code>embed</code></p>
106 | 									</td>
107 | 			</tr>
108 | 					<tr>
109 | 				<td>
110 | 											<code>page</code><br />
111 | 									</td>
112 | 				<td>
113 | 											<p>Current page of the collection.</p>
114 | 																					<p class="default">
115 | 							Default: <code>1</code>
116 | 						</p>
117 | 														</td>
118 | 			</tr>
119 | 					<tr>
120 | 				<td>
121 | 											<code>per_page</code><br />
122 | 									</td>
123 | 				<td>
124 | 											<p>Maximum number of items to be returned in result set.</p>
125 | 																					<p class="default">
126 | 							Default: <code>10</code>
127 | 						</p>
128 | 														</td>
129 | 			</tr>
130 | 					<tr>
131 | 				<td>
132 | 											<code>search</code><br />
133 | 									</td>
134 | 				<td>
135 | 											<p>Limit results to those matching a string.</p>
136 | 																								</td>
137 | 			</tr>
138 | 					<tr>
139 | 				<td>
140 | 											<code>type</code><br />
141 | 									</td>
142 | 				<td>
143 | 											<p>Limit results to items of an object type.</p>
144 | 																					<p class="default">
145 | 							Default: <code>post</code>
146 | 						</p>
147 | 																<p>One of: <code>post</code>, <code>term</code>, <code>post-format</code></p>
148 | 									</td>
149 | 			</tr>
150 | 					<tr>
151 | 				<td>
152 | 											<code>subtype</code><br />
153 | 									</td>
154 | 				<td>
155 | 											<p>Limit results to items of one or more object subtypes.</p>
156 | 																					<p class="default">
157 | 							Default: <code>any</code>
158 | 						</p>
159 | 														</td>
160 | 			</tr>
161 | 					<tr>
162 | 				<td>
163 | 											<code>exclude</code><br />
164 | 									</td>
165 | 				<td>
166 | 											<p>Ensure result set excludes specific IDs.</p>
167 | 																								</td>
168 | 			</tr>
169 | 					<tr>
170 | 				<td>
171 | 											<code>include</code><br />
172 | 									</td>
173 | 				<td>
174 | 											<p>Limit result set to specific IDs.</p>
175 | 																								</td>
176 | 			</tr>
177 | 			</table>
178 | 
179 | 	</div>
180 | </section>
181 | </div>
182 | 


--------------------------------------------------------------------------------
/reference/wp-site-health-tests.md:
--------------------------------------------------------------------------------
  1 | ---
  2 | ---
  3 | 
  4 | # Wp Site Health Tests
  5 | 
  6 | <section class="route">
  7 | 	<div class="primary">
  8 | 		<h2>Schema</h2>
  9 | <p>The schema defines all the fields that exist within a wp site health test record. Any response from these endpoints can be expected to contain the fields below unless the `_filter` query parameter is used or the schema field only appears in a specific context.</p>
 10 | <table class="attributes">
 11 | 			<tr id="schema-test">
 12 | 			<td>
 13 | 				<code>test</code>
 14 | 			</td>
 15 | 			<td>
 16 | 				<p>The name of the test being run.</p>
 17 | 				<p class="type">
 18 | 					JSON data type: string				</p>
 19 | 									<p class="read-only">Read only</p>
 20 | 								<p class="context">Context: <code></code></p>
 21 | 							</td>
 22 | 		</tr>
 23 | 			<tr id="schema-label">
 24 | 			<td>
 25 | 				<code>label</code>
 26 | 			</td>
 27 | 			<td>
 28 | 				<p>A label describing the test.</p>
 29 | 				<p class="type">
 30 | 					JSON data type: string				</p>
 31 | 									<p class="read-only">Read only</p>
 32 | 								<p class="context">Context: <code></code></p>
 33 | 							</td>
 34 | 		</tr>
 35 | 			<tr id="schema-status">
 36 | 			<td>
 37 | 				<code>status</code>
 38 | 			</td>
 39 | 			<td>
 40 | 				<p>The status of the test.</p>
 41 | 				<p class="type">
 42 | 					JSON data type: string				</p>
 43 | 									<p class="read-only">Read only</p>
 44 | 								<p class="context">Context: <code></code></p>
 45 | 									<p>One of: <code>good</code>, <code>recommended</code>, <code>critical</code></p>
 46 | 							</td>
 47 | 		</tr>
 48 | 			<tr id="schema-badge">
 49 | 			<td>
 50 | 				<code>badge</code>
 51 | 			</td>
 52 | 			<td>
 53 | 				<p>The category this test is grouped in.</p>
 54 | 				<p class="type">
 55 | 					JSON data type: object				</p>
 56 | 									<p class="read-only">Read only</p>
 57 | 								<p class="context">Context: <code></code></p>
 58 | 							</td>
 59 | 		</tr>
 60 | 			<tr id="schema-description">
 61 | 			<td>
 62 | 				<code>description</code>
 63 | 			</td>
 64 | 			<td>
 65 | 				<p>A more descriptive explanation of what the test looks for, and why it is important for the user.</p>
 66 | 				<p class="type">
 67 | 					JSON data type: string				</p>
 68 | 									<p class="read-only">Read only</p>
 69 | 								<p class="context">Context: <code></code></p>
 70 | 							</td>
 71 | 		</tr>
 72 | 			<tr id="schema-actions">
 73 | 			<td>
 74 | 				<code>actions</code>
 75 | 			</td>
 76 | 			<td>
 77 | 				<p>HTML containing an action to direct the user to where they can resolve the issue.</p>
 78 | 				<p class="type">
 79 | 					JSON data type: string				</p>
 80 | 									<p class="read-only">Read only</p>
 81 | 								<p class="context">Context: <code></code></p>
 82 | 							</td>
 83 | 		</tr>
 84 | 	</table>
 85 | 
 86 | 	</div>
 87 | </section>
 88 | 
 89 | <div><section class="route">
 90 | 	<div class="primary">
 91 | 		<h2>Retrieve a Wp Site Health Test</h2>
 92 | 
 93 | 		<h3>Definition & Example Request</h3>
 94 | 
 95 | 		<code>GET /wp-site-health/v1/tests/background-updates</code>
 96 | 
 97 | 		<p>Query this endpoint to retrieve a specific wp site health test record.</p>
 98 | 
 99 | 		<code>$ curl https://example.com/wp-json/wp-site-health/v1/tests/background-updates</code>
100 | 	</div>
101 | 	<div class="secondary">
102 | 			<p>There are no arguments for this endpoint.</p>
103 | 
104 | 	</div>
105 | </section>
106 | <section class="route">
107 | 	<div class="primary">
108 | 		<h2>Retrieve a Wp Site Health Test</h2>
109 | 
110 | 		<h3>Definition & Example Request</h3>
111 | 
112 | 		<code>GET /wp-site-health/v1/tests/loopback-requests</code>
113 | 
114 | 		<p>Query this endpoint to retrieve a specific wp site health test record.</p>
115 | 
116 | 		<code>$ curl https://example.com/wp-json/wp-site-health/v1/tests/loopback-requests</code>
117 | 	</div>
118 | 	<div class="secondary">
119 | 			<p>There are no arguments for this endpoint.</p>
120 | 
121 | 	</div>
122 | </section>
123 | <section class="route">
124 | 	<div class="primary">
125 | 		<h2>Retrieve a Wp Site Health Test</h2>
126 | 
127 | 		<h3>Definition & Example Request</h3>
128 | 
129 | 		<code>GET /wp-site-health/v1/tests/https-status</code>
130 | 
131 | 		<p>Query this endpoint to retrieve a specific wp site health test record.</p>
132 | 
133 | 		<code>$ curl https://example.com/wp-json/wp-site-health/v1/tests/https-status</code>
134 | 	</div>
135 | 	<div class="secondary">
136 | 			<p>There are no arguments for this endpoint.</p>
137 | 
138 | 	</div>
139 | </section>
140 | <section class="route">
141 | 	<div class="primary">
142 | 		<h2>Retrieve a Wp Site Health Test</h2>
143 | 
144 | 		<h3>Definition & Example Request</h3>
145 | 
146 | 		<code>GET /wp-site-health/v1/tests/dotorg-communication</code>
147 | 
148 | 		<p>Query this endpoint to retrieve a specific wp site health test record.</p>
149 | 
150 | 		<code>$ curl https://example.com/wp-json/wp-site-health/v1/tests/dotorg-communication</code>
151 | 	</div>
152 | 	<div class="secondary">
153 | 			<p>There are no arguments for this endpoint.</p>
154 | 
155 | 	</div>
156 | </section>
157 | <section class="route">
158 | 	<div class="primary">
159 | 		<h2>Retrieve a Wp Site Health Test</h2>
160 | 
161 | 		<h3>Definition & Example Request</h3>
162 | 
163 | 		<code>GET /wp-site-health/v1/tests/authorization-header</code>
164 | 
165 | 		<p>Query this endpoint to retrieve a specific wp site health test record.</p>
166 | 
167 | 		<code>$ curl https://example.com/wp-json/wp-site-health/v1/tests/authorization-header</code>
168 | 	</div>
169 | 	<div class="secondary">
170 | 			<p>There are no arguments for this endpoint.</p>
171 | 
172 | 	</div>
173 | </section>
174 | </div>
175 | 


--------------------------------------------------------------------------------
/reference/post-statuses.md:
--------------------------------------------------------------------------------
  1 | ---
  2 | ---
  3 | 
  4 | # Statuses
  5 | 
  6 | <section class="route">
  7 | 	<div class="primary">
  8 | 		<h2>Schema</h2>
  9 | <p>The schema defines all the fields that exist within a status record. Any response from these endpoints can be expected to contain the fields below unless the `_filter` query parameter is used or the schema field only appears in a specific context.</p>
 10 | <table class="attributes">
 11 | 			<tr id="schema-name">
 12 | 			<td>
 13 | 				<code>name</code>
 14 | 			</td>
 15 | 			<td>
 16 | 				<p>The title for the status.</p>
 17 | 				<p class="type">
 18 | 					JSON data type: string				</p>
 19 | 									<p class="read-only">Read only</p>
 20 | 								<p class="context">Context: <code>embed</code>, <code>view</code>, <code>edit</code></p>
 21 | 							</td>
 22 | 		</tr>
 23 | 			<tr id="schema-private">
 24 | 			<td>
 25 | 				<code>private</code>
 26 | 			</td>
 27 | 			<td>
 28 | 				<p>Whether posts with this status should be private.</p>
 29 | 				<p class="type">
 30 | 					JSON data type: boolean				</p>
 31 | 									<p class="read-only">Read only</p>
 32 | 								<p class="context">Context: <code>edit</code></p>
 33 | 							</td>
 34 | 		</tr>
 35 | 			<tr id="schema-protected">
 36 | 			<td>
 37 | 				<code>protected</code>
 38 | 			</td>
 39 | 			<td>
 40 | 				<p>Whether posts with this status should be protected.</p>
 41 | 				<p class="type">
 42 | 					JSON data type: boolean				</p>
 43 | 									<p class="read-only">Read only</p>
 44 | 								<p class="context">Context: <code>edit</code></p>
 45 | 							</td>
 46 | 		</tr>
 47 | 			<tr id="schema-public">
 48 | 			<td>
 49 | 				<code>public</code>
 50 | 			</td>
 51 | 			<td>
 52 | 				<p>Whether posts of this status should be shown in the front end of the site.</p>
 53 | 				<p class="type">
 54 | 					JSON data type: boolean				</p>
 55 | 									<p class="read-only">Read only</p>
 56 | 								<p class="context">Context: <code>view</code>, <code>edit</code></p>
 57 | 							</td>
 58 | 		</tr>
 59 | 			<tr id="schema-queryable">
 60 | 			<td>
 61 | 				<code>queryable</code>
 62 | 			</td>
 63 | 			<td>
 64 | 				<p>Whether posts with this status should be publicly-queryable.</p>
 65 | 				<p class="type">
 66 | 					JSON data type: boolean				</p>
 67 | 									<p class="read-only">Read only</p>
 68 | 								<p class="context">Context: <code>view</code>, <code>edit</code></p>
 69 | 							</td>
 70 | 		</tr>
 71 | 			<tr id="schema-show_in_list">
 72 | 			<td>
 73 | 				<code>show_in_list</code>
 74 | 			</td>
 75 | 			<td>
 76 | 				<p>Whether to include posts in the edit listing for their post type.</p>
 77 | 				<p class="type">
 78 | 					JSON data type: boolean				</p>
 79 | 									<p class="read-only">Read only</p>
 80 | 								<p class="context">Context: <code>edit</code></p>
 81 | 							</td>
 82 | 		</tr>
 83 | 			<tr id="schema-slug">
 84 | 			<td>
 85 | 				<code>slug</code>
 86 | 			</td>
 87 | 			<td>
 88 | 				<p>An alphanumeric identifier for the status.</p>
 89 | 				<p class="type">
 90 | 					JSON data type: string				</p>
 91 | 									<p class="read-only">Read only</p>
 92 | 								<p class="context">Context: <code>embed</code>, <code>view</code>, <code>edit</code></p>
 93 | 							</td>
 94 | 		</tr>
 95 | 			<tr id="schema-date_floating">
 96 | 			<td>
 97 | 				<code>date_floating</code>
 98 | 			</td>
 99 | 			<td>
100 | 				<p>Whether posts of this status may have floating published dates.</p>
101 | 				<p class="type">
102 | 					JSON data type: boolean				</p>
103 | 									<p class="read-only">Read only</p>
104 | 								<p class="context">Context: <code>view</code>, <code>edit</code></p>
105 | 							</td>
106 | 		</tr>
107 | 	</table>
108 | 
109 | 	</div>
110 | </section>
111 | 
112 | <div><section class="route">
113 | 	<div class="primary">
114 | 		<h2>Retrieve a Status</h2>
115 | 
116 | 		<h3>Definition & Example Request</h3>
117 | 
118 | 		<code>GET /wp/v2/statuses</code>
119 | 
120 | 		<p>Query this endpoint to retrieve a specific status record.</p>
121 | 
122 | 		<code>$ curl https://example.com/wp-json/wp/v2/statuses</code>
123 | 	</div>
124 | 	<div class="secondary">
125 | 			<h3>Arguments</h3>
126 | 	<table class="arguments">
127 | 					<tr>
128 | 				<td>
129 | 											<code>context</code><br />
130 | 									</td>
131 | 				<td>
132 | 											<p>Scope under which the request is made; determines fields present in response.</p>
133 | 																					<p class="default">
134 | 							Default: <code>view</code>
135 | 						</p>
136 | 																<p>One of: <code>view</code>, <code>embed</code>, <code>edit</code></p>
137 | 									</td>
138 | 			</tr>
139 | 			</table>
140 | 
141 | 	</div>
142 | </section>
143 | <section class="route">
144 | 	<div class="primary">
145 | 		<h2>Retrieve a Status</h2>
146 | 
147 | 		<h3>Definition & Example Request</h3>
148 | 
149 | 		<code>GET /wp/v2/statuses/&lt;status&gt;</code>
150 | 
151 | 		<p>Query this endpoint to retrieve a specific status record.</p>
152 | 
153 | 		<code>$ curl https://example.com/wp-json/wp/v2/statuses/&lt;status&gt;</code>
154 | 	</div>
155 | 	<div class="secondary">
156 | 			<h3>Arguments</h3>
157 | 	<table class="arguments">
158 | 					<tr>
159 | 				<td>
160 | 											<code>status</code><br />
161 | 									</td>
162 | 				<td>
163 | 											<p>An alphanumeric identifier for the status.</p>
164 | 																								</td>
165 | 			</tr>
166 | 					<tr>
167 | 				<td>
168 | 											<code>context</code><br />
169 | 									</td>
170 | 				<td>
171 | 											<p>Scope under which the request is made; determines fields present in response.</p>
172 | 																					<p class="default">
173 | 							Default: <code>view</code>
174 | 						</p>
175 | 																<p>One of: <code>view</code>, <code>embed</code>, <code>edit</code></p>
176 | 									</td>
177 | 			</tr>
178 | 			</table>
179 | 
180 | 	</div>
181 | </section>
182 | </div>
183 | 


--------------------------------------------------------------------------------
/reference.md:
--------------------------------------------------------------------------------
  1 | # Reference
  2 | 
  3 | The WordPress REST API is organized around [REST](http://en.wikipedia.org/wiki/Representational_state_transfer), and is designed to have predictable, resource-oriented URLs and to use HTTP response codes to indicate API errors. The API uses built-in HTTP features, like HTTP authentication and HTTP verbs, which can be understood by off-the-shelf HTTP clients, and supports cross-origin resource sharing to allow you to interact securely with the API from a client-side web application.
  4 | 
  5 | The REST API uses JSON exclusively as the request and response format, including error responses. While the REST API does not completely conform to the [HAL standard](http://stateless.co/hal_specification.html), it does implement HAL's `._links` and `._embedded` properties for linking API resources, and is fully discoverable via hyperlinks in the responses.
  6 | 
  7 | The REST API provides public data accessible to any client anonymously, as well as private data only available after [authentication](https://developer.wordpress.org/rest-api/authentication/). Once authenticated the REST API supports most content management actions, allowing you to build alternative dashboards for a site, enhance your plugins with more responsive management tools, or build complex single-page applications.
  8 | 
  9 | This API reference provides information on the specific endpoints available through the API, their parameters, and their response data format.
 10 | 
 11 | ## REST API Developer Endpoint Reference
 12 | 
 13 | <table>
 14 |   <tr>
 15 |     <th>Resource</th>
 16 |     <th>Base Route</th>
 17 |   </tr>
 18 |   <tr>
 19 |     <td><a href="https://developer.wordpress.org/rest-api/reference/posts/">Posts</td>
 20 |     <td><code>/wp/v2/posts</code></td>
 21 |   </tr>
 22 |   <tr>
 23 |     <td><a href="https://developer.wordpress.org/rest-api/reference/post-revisions/">Post Revisions</a></td>
 24 |     <td><code>/wp/v2/posts/&lt;id&gt;/revisions</code></td>
 25 |   </tr>
 26 |   <tr>
 27 |     <td><a href="https://developer.wordpress.org/rest-api/reference/categories/">Categories</a></td>
 28 |     <td><code>/wp/v2/categories</code></td>
 29 |   </tr>
 30 |   <tr>
 31 |     <td><a href="https://developer.wordpress.org/rest-api/reference/tags/">Tags</a></td>
 32 |     <td><code>/wp/v2/tags</code></td>
 33 |   </tr>
 34 |   <tr>
 35 |     <td><a href="https://developer.wordpress.org/rest-api/reference/pages/">Pages</a></td>
 36 |     <td><code>/wp/v2/pages</code></td>
 37 |   </tr>
 38 |   <tr>
 39 |     <td><a href="https://developer.wordpress.org/rest-api/reference/page-revisions/">Page Revisions</a></td>
 40 |     <td><code>/wp/v2/pages/&lt;id&gt;/revisions</code></td>
 41 |   </tr>
 42 |   <tr>
 43 |     <td><a href="https://developer.wordpress.org/rest-api/reference/comments/">Comments</a></td>
 44 |     <td><code>/wp/v2/comments</code></td>
 45 |   </tr>
 46 |   <tr>
 47 |     <td><a href="https://developer.wordpress.org/rest-api/reference/taxonomies/">Taxonomies</a></td>
 48 |     <td><code>/wp/v2/taxonomies</code></td>
 49 |   </tr>
 50 |   <tr>
 51 |     <td><a href="https://developer.wordpress.org/rest-api/reference/media/">Media</a></td>
 52 |     <td><code>/wp/v2/media</code></td>
 53 |   </tr>
 54 |   <tr>
 55 |     <td><a href="https://developer.wordpress.org/rest-api/reference/users/">Users</a></td>
 56 |     <td><code>/wp/v2/users</code></td>
 57 |   </tr>
 58 |   <tr>
 59 |     <td><a href="https://developer.wordpress.org/rest-api/reference/post-types/">Post Types</a></td>
 60 |     <td><code>/wp/v2/types</code></td>
 61 |   </tr>
 62 |   <tr>
 63 |     <td><a href="https://developer.wordpress.org/rest-api/reference/post-statuses/">Post Statuses</a></td>
 64 |     <td><code>/wp/v2/statuses</code></td>
 65 |   </tr>
 66 |   <tr>
 67 |     <td><a href="https://developer.wordpress.org/rest-api/reference/settings/">Settings</a></td>
 68 |     <td><code>/wp/v2/settings</code></td>
 69 |   </tr>
 70 |   <tr>
 71 |     <td><a href="https://developer.wordpress.org/rest-api/reference/themes/">Themes</a></td>
 72 |     <td><code>/wp/v2/themes</code></td>
 73 |   </tr>
 74 |   <tr>
 75 |     <td><a href="https://developer.wordpress.org/rest-api/reference/search-results/">Search</a></td>
 76 |     <td><code>/wp/v2/search</code></td>
 77 |   </tr>
 78 |   <tr>
 79 |     <td><a href="https://developer.wordpress.org/rest-api/reference/block-types/">Block Types</a></td>
 80 |     <td><code>/wp/v2/block-types</code></td>
 81 |   </tr>
 82 |   <tr>
 83 |     <td><a href="https://developer.wordpress.org/rest-api/reference/blocks/">Blocks</a></td>
 84 |     <td><code>/wp/v2/blocks</code></td>
 85 |   </tr>
 86 |   <tr>
 87 |     <td><a href="https://developer.wordpress.org/rest-api/reference/block-revisions/">Block Revisions</a></td>
 88 |     <td><code>/wp/v2/blocks/&lt;id&gt;/autosaves/</code></td>
 89 |   </tr>
 90 |   <tr>
 91 |     <td><a href="https://developer.wordpress.org/rest-api/reference/rendered-blocks/">Block Renderer</a></td>
 92 |     <td><code>/wp/v2/block-renderer</code></td>
 93 |   </tr>
 94 |   <tr>
 95 |     <td><a href="https://developer.wordpress.org/rest-api/reference/block-directory-items/">Block Directory Items</a></td>
 96 |     <td><code>/wp/v2/block-directory/search</code></td>
 97 |   </tr>
 98 |   <tr>
 99 |     <td><a href="https://developer.wordpress.org/rest-api/reference/plugins/">Plugins</a></td>
100 |     <td><code>/wp/v2/plugins</code></td>
101 |   </tr>
102 | </table>
103 | 
104 | ## A Distributed API
105 | 
106 | Unlike many other REST APIs, the WordPress REST API is distributed and available individually on each site that supports it. This means there is no singular API root or base to contact; instead, we have [a discovery process](https://developer.wordpress.org/rest-api/discovery/) that allows interacting with sites without prior contact. The API also exposes self-documentation at the index endpoint, or via an `OPTIONS` request to any endpoint, allowing human- or machine-discovery of endpoint capabilities.
107 | 


--------------------------------------------------------------------------------
/reference/block-patterns.md:
--------------------------------------------------------------------------------
  1 | ---
  2 | ---
  3 | 
  4 | # Block Patterns
  5 | 
  6 | <section class="route">
  7 | 	<div class="primary">
  8 | 		<h2>Schema</h2>
  9 | <p>The schema defines all the fields that exist within a block pattern record. Any response from these endpoints can be expected to contain the fields below unless the `_filter` query parameter is used or the schema field only appears in a specific context.</p>
 10 | <table class="attributes">
 11 | 			<tr id="schema-name">
 12 | 			<td>
 13 | 				<code>name</code>
 14 | 			</td>
 15 | 			<td>
 16 | 				<p>The pattern name.</p>
 17 | 				<p class="type">
 18 | 					JSON data type: string				</p>
 19 | 									<p class="read-only">Read only</p>
 20 | 								<p class="context">Context: <code>view</code>, <code>edit</code>, <code>embed</code></p>
 21 | 							</td>
 22 | 		</tr>
 23 | 			<tr id="schema-title">
 24 | 			<td>
 25 | 				<code>title</code>
 26 | 			</td>
 27 | 			<td>
 28 | 				<p>The pattern title, in human readable format.</p>
 29 | 				<p class="type">
 30 | 					JSON data type: string				</p>
 31 | 									<p class="read-only">Read only</p>
 32 | 								<p class="context">Context: <code>view</code>, <code>edit</code>, <code>embed</code></p>
 33 | 							</td>
 34 | 		</tr>
 35 | 			<tr id="schema-content">
 36 | 			<td>
 37 | 				<code>content</code>
 38 | 			</td>
 39 | 			<td>
 40 | 				<p>The pattern content.</p>
 41 | 				<p class="type">
 42 | 					JSON data type: string				</p>
 43 | 									<p class="read-only">Read only</p>
 44 | 								<p class="context">Context: <code>view</code>, <code>edit</code>, <code>embed</code></p>
 45 | 							</td>
 46 | 		</tr>
 47 | 			<tr id="schema-description">
 48 | 			<td>
 49 | 				<code>description</code>
 50 | 			</td>
 51 | 			<td>
 52 | 				<p>The pattern detailed description.</p>
 53 | 				<p class="type">
 54 | 					JSON data type: string				</p>
 55 | 									<p class="read-only">Read only</p>
 56 | 								<p class="context">Context: <code>view</code>, <code>edit</code>, <code>embed</code></p>
 57 | 							</td>
 58 | 		</tr>
 59 | 			<tr id="schema-viewport_width">
 60 | 			<td>
 61 | 				<code>viewport_width</code>
 62 | 			</td>
 63 | 			<td>
 64 | 				<p>The pattern viewport width for inserter preview.</p>
 65 | 				<p class="type">
 66 | 					JSON data type: number				</p>
 67 | 									<p class="read-only">Read only</p>
 68 | 								<p class="context">Context: <code>view</code>, <code>edit</code>, <code>embed</code></p>
 69 | 							</td>
 70 | 		</tr>
 71 | 			<tr id="schema-inserter">
 72 | 			<td>
 73 | 				<code>inserter</code>
 74 | 			</td>
 75 | 			<td>
 76 | 				<p>Determines whether the pattern is visible in inserter.</p>
 77 | 				<p class="type">
 78 | 					JSON data type: boolean				</p>
 79 | 									<p class="read-only">Read only</p>
 80 | 								<p class="context">Context: <code>view</code>, <code>edit</code>, <code>embed</code></p>
 81 | 							</td>
 82 | 		</tr>
 83 | 			<tr id="schema-categories">
 84 | 			<td>
 85 | 				<code>categories</code>
 86 | 			</td>
 87 | 			<td>
 88 | 				<p>The pattern category slugs.</p>
 89 | 				<p class="type">
 90 | 					JSON data type: array				</p>
 91 | 									<p class="read-only">Read only</p>
 92 | 								<p class="context">Context: <code>view</code>, <code>edit</code>, <code>embed</code></p>
 93 | 							</td>
 94 | 		</tr>
 95 | 			<tr id="schema-keywords">
 96 | 			<td>
 97 | 				<code>keywords</code>
 98 | 			</td>
 99 | 			<td>
100 | 				<p>The pattern keywords.</p>
101 | 				<p class="type">
102 | 					JSON data type: array				</p>
103 | 									<p class="read-only">Read only</p>
104 | 								<p class="context">Context: <code>view</code>, <code>edit</code>, <code>embed</code></p>
105 | 							</td>
106 | 		</tr>
107 | 			<tr id="schema-block_types">
108 | 			<td>
109 | 				<code>block_types</code>
110 | 			</td>
111 | 			<td>
112 | 				<p>Block types that the pattern is intended to be used with.</p>
113 | 				<p class="type">
114 | 					JSON data type: array				</p>
115 | 									<p class="read-only">Read only</p>
116 | 								<p class="context">Context: <code>view</code>, <code>edit</code>, <code>embed</code></p>
117 | 							</td>
118 | 		</tr>
119 | 			<tr id="schema-post_types">
120 | 			<td>
121 | 				<code>post_types</code>
122 | 			</td>
123 | 			<td>
124 | 				<p>An array of post types that the pattern is restricted to be used with.</p>
125 | 				<p class="type">
126 | 					JSON data type: array				</p>
127 | 									<p class="read-only">Read only</p>
128 | 								<p class="context">Context: <code>view</code>, <code>edit</code>, <code>embed</code></p>
129 | 							</td>
130 | 		</tr>
131 | 			<tr id="schema-template_types">
132 | 			<td>
133 | 				<code>template_types</code>
134 | 			</td>
135 | 			<td>
136 | 				<p>An array of template types where the pattern fits.</p>
137 | 				<p class="type">
138 | 					JSON data type: array				</p>
139 | 									<p class="read-only">Read only</p>
140 | 								<p class="context">Context: <code>view</code>, <code>edit</code>, <code>embed</code></p>
141 | 							</td>
142 | 		</tr>
143 | 			<tr id="schema-source">
144 | 			<td>
145 | 				<code>source</code>
146 | 			</td>
147 | 			<td>
148 | 				<p>Where the pattern comes from e.g. core</p>
149 | 				<p class="type">
150 | 					JSON data type: string				</p>
151 | 									<p class="read-only">Read only</p>
152 | 								<p class="context">Context: <code>view</code>, <code>edit</code>, <code>embed</code></p>
153 | 									<p>One of: <code>core</code>, <code>plugin</code>, <code>theme</code>, <code>pattern-directory/core</code>, <code>pattern-directory/theme</code>, <code>pattern-directory/featured</code></p>
154 | 							</td>
155 | 		</tr>
156 | 	</table>
157 | 
158 | 	</div>
159 | </section>
160 | 
161 | <div><section class="route">
162 | 	<div class="primary">
163 | 		<h2>Retrieve a Block Pattern</h2>
164 | 
165 | 		<h3>Definition & Example Request</h3>
166 | 
167 | 		<code>GET /wp/v2/block-patterns/patterns</code>
168 | 
169 | 		<p>Query this endpoint to retrieve a specific block pattern record.</p>
170 | 
171 | 		<code>$ curl https://example.com/wp-json/wp/v2/block-patterns/patterns</code>
172 | 	</div>
173 | 	<div class="secondary">
174 | 			<p>There are no arguments for this endpoint.</p>
175 | 
176 | 	</div>
177 | </section>
178 | </div>
179 | 


--------------------------------------------------------------------------------
/reference/wp_global_styles-revisions.md:
--------------------------------------------------------------------------------
  1 | ---
  2 | ---
  3 | 
  4 | # Global_Styles Revisions
  5 | 
  6 | <section class="route">
  7 | 	<div class="primary">
  8 | 		<h2>Schema</h2>
  9 | <p>The schema defines all the fields that exist within a global_styles revision record. Any response from these endpoints can be expected to contain the fields below unless the `_filter` query parameter is used or the schema field only appears in a specific context.</p>
 10 | <table class="attributes">
 11 | 			<tr id="schema-author">
 12 | 			<td>
 13 | 				<code>author</code>
 14 | 			</td>
 15 | 			<td>
 16 | 				<p>The ID for the author of the revision.</p>
 17 | 				<p class="type">
 18 | 					JSON data type: integer				</p>
 19 | 								<p class="context">Context: <code>view</code>, <code>edit</code>, <code>embed</code></p>
 20 | 							</td>
 21 | 		</tr>
 22 | 			<tr id="schema-date">
 23 | 			<td>
 24 | 				<code>date</code>
 25 | 			</td>
 26 | 			<td>
 27 | 				<p>The date the revision was published, in the site&#039;s timezone.</p>
 28 | 				<p class="type">
 29 | 					JSON data type: string,
 30 | 											Format: datetime (<a href="https://core.trac.wordpress.org/ticket/41032">details</a>)
 31 | 									</p>
 32 | 								<p class="context">Context: <code>view</code>, <code>edit</code>, <code>embed</code></p>
 33 | 							</td>
 34 | 		</tr>
 35 | 			<tr id="schema-date_gmt">
 36 | 			<td>
 37 | 				<code>date_gmt</code>
 38 | 			</td>
 39 | 			<td>
 40 | 				<p>The date the revision was published, as GMT.</p>
 41 | 				<p class="type">
 42 | 					JSON data type: string,
 43 | 											Format: datetime (<a href="https://core.trac.wordpress.org/ticket/41032">details</a>)
 44 | 									</p>
 45 | 								<p class="context">Context: <code>view</code>, <code>edit</code></p>
 46 | 							</td>
 47 | 		</tr>
 48 | 			<tr id="schema-id">
 49 | 			<td>
 50 | 				<code>id</code>
 51 | 			</td>
 52 | 			<td>
 53 | 				<p>Unique identifier for the revision.</p>
 54 | 				<p class="type">
 55 | 					JSON data type: integer				</p>
 56 | 								<p class="context">Context: <code>view</code>, <code>edit</code>, <code>embed</code></p>
 57 | 							</td>
 58 | 		</tr>
 59 | 			<tr id="schema-modified">
 60 | 			<td>
 61 | 				<code>modified</code>
 62 | 			</td>
 63 | 			<td>
 64 | 				<p>The date the revision was last modified, in the site&#039;s timezone.</p>
 65 | 				<p class="type">
 66 | 					JSON data type: string,
 67 | 											Format: datetime (<a href="https://core.trac.wordpress.org/ticket/41032">details</a>)
 68 | 									</p>
 69 | 								<p class="context">Context: <code>view</code>, <code>edit</code></p>
 70 | 							</td>
 71 | 		</tr>
 72 | 			<tr id="schema-modified_gmt">
 73 | 			<td>
 74 | 				<code>modified_gmt</code>
 75 | 			</td>
 76 | 			<td>
 77 | 				<p>The date the revision was last modified, as GMT.</p>
 78 | 				<p class="type">
 79 | 					JSON data type: string,
 80 | 											Format: datetime (<a href="https://core.trac.wordpress.org/ticket/41032">details</a>)
 81 | 									</p>
 82 | 								<p class="context">Context: <code>view</code>, <code>edit</code></p>
 83 | 							</td>
 84 | 		</tr>
 85 | 			<tr id="schema-parent">
 86 | 			<td>
 87 | 				<code>parent</code>
 88 | 			</td>
 89 | 			<td>
 90 | 				<p>The ID for the parent of the revision.</p>
 91 | 				<p class="type">
 92 | 					JSON data type: integer				</p>
 93 | 								<p class="context">Context: <code>view</code>, <code>edit</code>, <code>embed</code></p>
 94 | 							</td>
 95 | 		</tr>
 96 | 			<tr id="schema-styles">
 97 | 			<td>
 98 | 				<code>styles</code>
 99 | 			</td>
100 | 			<td>
101 | 				<p>Global styles.</p>
102 | 				<p class="type">
103 | 					JSON data type: object				</p>
104 | 								<p class="context">Context: <code>view</code>, <code>edit</code></p>
105 | 							</td>
106 | 		</tr>
107 | 			<tr id="schema-settings">
108 | 			<td>
109 | 				<code>settings</code>
110 | 			</td>
111 | 			<td>
112 | 				<p>Global settings.</p>
113 | 				<p class="type">
114 | 					JSON data type: object				</p>
115 | 								<p class="context">Context: <code>view</code>, <code>edit</code></p>
116 | 							</td>
117 | 		</tr>
118 | 	</table>
119 | 
120 | 	</div>
121 | </section>
122 | 
123 | <div><section class="route">
124 | 	<div class="primary">
125 | 		<h2>List Global_Styles Revisions</h2>
126 | 		<p>Query this endpoint to retrieve a collection of global_styles revisions. The response you receive can be controlled and filtered using the URL query parameters below.</p>
127 | 
128 | 		<h3>Definition</h3>
129 | 
130 | 		<code>GET /wp/v2/global-styles/&lt;parent&gt;/revisions</code>
131 | 
132 | 		<h3>Example Request</h3>
133 | 
134 | 		<code>$ curl https://example.com/wp-json/wp/v2/global-styles/&lt;parent&gt;/revisions</code>
135 | 	</div>
136 | 	<div class="secondary">
137 | 			<h3>Arguments</h3>
138 | 	<table class="arguments">
139 | 					<tr>
140 | 				<td>
141 | 											<code>parent</code><br />
142 | 									</td>
143 | 				<td>
144 | 											<p>The ID for the parent of the revision.</p>
145 | 																								</td>
146 | 			</tr>
147 | 					<tr>
148 | 				<td>
149 | 											<code>context</code><br />
150 | 									</td>
151 | 				<td>
152 | 											<p>Scope under which the request is made; determines fields present in response.</p>
153 | 																					<p class="default">
154 | 							Default: <code>view</code>
155 | 						</p>
156 | 																<p>One of: <code>view</code>, <code>embed</code>, <code>edit</code></p>
157 | 									</td>
158 | 			</tr>
159 | 					<tr>
160 | 				<td>
161 | 											<code>page</code><br />
162 | 									</td>
163 | 				<td>
164 | 											<p>Current page of the collection.</p>
165 | 																					<p class="default">
166 | 							Default: <code>1</code>
167 | 						</p>
168 | 														</td>
169 | 			</tr>
170 | 					<tr>
171 | 				<td>
172 | 											<code>per_page</code><br />
173 | 									</td>
174 | 				<td>
175 | 											<p>Maximum number of items to be returned in result set.</p>
176 | 																								</td>
177 | 			</tr>
178 | 					<tr>
179 | 				<td>
180 | 											<code>offset</code><br />
181 | 									</td>
182 | 				<td>
183 | 											<p>Offset the result set by a specific number of items.</p>
184 | 																								</td>
185 | 			</tr>
186 | 			</table>
187 | 
188 | 	</div>
189 | </section>
190 | </div>
191 | 


--------------------------------------------------------------------------------
/frequently-asked-questions.md:
--------------------------------------------------------------------------------
  1 | # Frequently Asked Questions
  2 | 
  3 | This page provides solutions to some common questions and problems that may arise while using the API. If your question is not explained here it may have been answered in the [WordPress support forums](https://wordpress.org/support/topic-tag/rest-api).
  4 | 
  5 | 
  6 | ## Can I disable the REST API?
  7 | 
  8 | You should not disable the REST API; doing so will break WordPress Admin functionality that depends on the API being active. However, you may use a filter to require that API consumers be authenticated, which effectively prevents anonymous external access. See below for more information.
  9 | 
 10 | 
 11 | ## Require Authentication for All Requests
 12 | 
 13 | You can require authentication for all REST API requests by adding an `is_user_logged_in` check to the [`rest_authentication_errors`](https://developer.wordpress.org/reference/hooks/rest_authentication_errors/) filter.
 14 | 
 15 | Note: The incoming callback parameter can be either `null`, a `WP_Error`, or a boolean. The type of the parameter indicates the state of authentication:
 16 | 
 17 |  * `null`: no authentication check has yet been performed, and the hook callback may apply custom authentication logic.
 18 |  * boolean: indicates a previous authentication method check was performed. Boolean `true` indicates the request was successfully authenticated, and boolean `false` indicates authentication failed.
 19 |  * `WP_Error`: Some kind of error was encountered.
 20 | 
 21 | ```php
 22 | add_filter( 'rest_authentication_errors', function( $result ) {
 23 |     // If a previous authentication check was applied,
 24 |     // pass that result along without modification.
 25 |     if ( true === $result || is_wp_error( $result ) ) {
 26 |         return $result;
 27 |     }
 28 | 
 29 |     // No authentication has been performed yet.
 30 |     // Return an error if user is not logged in.
 31 |     if ( ! is_user_logged_in() ) {
 32 |         return new WP_Error(
 33 |             'rest_not_logged_in',
 34 |             __( 'You are not currently logged in.' ),
 35 |             array( 'status' => 401 )
 36 |         );
 37 |     }
 38 | 
 39 |     // Our custom authentication check should have no effect
 40 |     // on logged-in requests
 41 |     return $result;
 42 | });
 43 | ```
 44 | 
 45 | 
 46 | ## Can I make API requests from PHP within a plugin?
 47 | 
 48 | Yes, you can! Use [rest_do_request](https://developer.wordpress.org/reference/functions/rest_do_request/) to make API requests internally within other WordPress code:
 49 | 
 50 | ```php
 51 | $request = new WP_REST_Request( 'GET', '/wp/v2/posts' );
 52 | // Set one or more request query parameters
 53 | $request->set_param( 'per_page', 20 );
 54 | $response = rest_do_request( $request );
 55 | ```
 56 | 
 57 | ## How do I use the _embed parameter on internal requests?
 58 | 
 59 | Setting the `_embed` param on the request object won't work.
 60 | 
 61 | ```php
 62 | $request = new WP_REST_Request( 'GET', '/wp/v2/posts' );
 63 | $request->set_param( '_embed', 1 );
 64 | $response = rest_do_request( $request );
 65 | ```
 66 | 
 67 | Instead, manually call the [`WP_REST_Server::response_to_data`](https://developer.wordpress.org/reference/classes/wp_rest_server/) function.
 68 | 
 69 | ```php
 70 | $request = new WP_REST_Request( 'GET', '/wp/v2/posts' );
 71 | $response = rest_do_request( $request );
 72 | $data = rest_get_server()->response_to_data( $response, true );
 73 | var_dump( $data['_embedded'] );
 74 | ```
 75 | 
 76 | ## What happened to the `?filter=` query parameter?
 77 | 
 78 | When the REST API was merged into WordPress core the `?filter` query parameter was removed to prevent future compatibility and maintenance issues. The ability to pass arbitrary WP_Query arguments to the API using a `?filter` query parameter was necessary at the genesis of the REST API project, but most API response filtering functionality has been superseded by more robust query parameters like `?categories=`, `?slug=` and `?per_page=`.
 79 | 
 80 | First-party query parameters should be used whenever possible. However, the [rest-filter](https://github.com/wp-api/rest-filter) plugin restores the ability to pass arbitrary `?filter` values in API request if needed.
 81 | 
 82 | 
 83 | ## Query parameters are not working
 84 | 
 85 | If you find that query parameters such as `?page=2` or `?_embed` are not having any effect, your server may not be properly configured to detect them. If you are using Nginx to serve your website, look for a `try_files` line in your site configuration. If it looks like this:
 86 | 
 87 | ```
 88 | try_files $uri $uri/ /index.php$args;
 89 | ```
 90 | 
 91 | change it to this:
 92 | 
 93 | ```
 94 | try_files $uri $uri/ /index.php$is_args$args;
 95 | ```
 96 | 
 97 | Adding `$is_args` (which will print a ? character if query arguments are found) will allow WordPress to properly receive and interpret the query parameters.
 98 | 
 99 | 
100 | ## Why is Authentication not working?
101 | 
102 | If you're finding that you are sending Authentication headers but the request is not being accepted, and you are using a CGI environment, your webserver may be stripping the headers. Please try adding the appropriate configuration below to remedy this.
103 | 
104 | ### Apache
105 | Add the following to a configuration file or .htaccess:
106 | ```
107 | <IfModule mod_setenvif>
108 |   SetEnvIf Authorization "(.*)" HTTP_AUTHORIZATION=$1
109 | </IfModule>
110 | ```
111 | 
112 | ### Nginx
113 | Add the following to your server configurations fastcgi section:
114 | ```
115 | fastcgi_pass_header Authorization;
116 | ```
117 | 
118 | ## Why is the REST API not verifying the incoming Origin header? Does this expose my site to CSRF attacks?
119 | 
120 | Cross-Origin Resource Sharing (CORS) is a mechanism which allows a website to control which Origins (originating external sites) are allowed to access your site's data. CORS prevents against a particular type of attack known as Cross-Site Request Forgery, or CSRF. However, WordPress has an existing CSRF protection mechanism which uses [nonces](https://developer.wordpress.org/plugins/security/nonces/). Tightening CORS restrictions would prevent some authentication methods, so the WordPress REST API uses nonces for CSRF protection instead of CORS.
121 | 
122 | Because the WordPress REST API does not verify the Origin header of incoming requests, public REST API endpoints may therefore be accessed from any site.
123 | 
124 | This is an [intentional design decision](https://core.trac.wordpress.org/changeset/40600), but if you wish to prevent your site from being accessed from unknown origins you may unhook the default [`rest_send_cors_headers` function](https://developer.wordpress.org/reference/functions/rest_send_cors_headers/) from the [`rest_pre_serve_request` filter hook](https://developer.wordpress.org/reference/hooks/rest_pre_serve_request/), then hook in your own function to that same filter to specify stricter CORS headers.
125 | 


--------------------------------------------------------------------------------
/reference/block-directory-items.md:
--------------------------------------------------------------------------------
  1 | ---
  2 | ---
  3 | 
  4 | # Block Directory Items
  5 | 
  6 | <section class="route">
  7 | 	<div class="primary">
  8 | 		<h2>Schema</h2>
  9 | <p>The schema defines all the fields that exist within a block directory item record. Any response from these endpoints can be expected to contain the fields below unless the `_filter` query parameter is used or the schema field only appears in a specific context.</p>
 10 | <table class="attributes">
 11 | 			<tr id="schema-name">
 12 | 			<td>
 13 | 				<code>name</code>
 14 | 			</td>
 15 | 			<td>
 16 | 				<p>The block name, in namespace/block-name format.</p>
 17 | 				<p class="type">
 18 | 					JSON data type: string				</p>
 19 | 								<p class="context">Context: <code>view</code></p>
 20 | 							</td>
 21 | 		</tr>
 22 | 			<tr id="schema-title">
 23 | 			<td>
 24 | 				<code>title</code>
 25 | 			</td>
 26 | 			<td>
 27 | 				<p>The block title, in human readable format.</p>
 28 | 				<p class="type">
 29 | 					JSON data type: string				</p>
 30 | 								<p class="context">Context: <code>view</code></p>
 31 | 							</td>
 32 | 		</tr>
 33 | 			<tr id="schema-description">
 34 | 			<td>
 35 | 				<code>description</code>
 36 | 			</td>
 37 | 			<td>
 38 | 				<p>A short description of the block, in human readable format.</p>
 39 | 				<p class="type">
 40 | 					JSON data type: string				</p>
 41 | 								<p class="context">Context: <code>view</code></p>
 42 | 							</td>
 43 | 		</tr>
 44 | 			<tr id="schema-id">
 45 | 			<td>
 46 | 				<code>id</code>
 47 | 			</td>
 48 | 			<td>
 49 | 				<p>The block slug.</p>
 50 | 				<p class="type">
 51 | 					JSON data type: string				</p>
 52 | 								<p class="context">Context: <code>view</code></p>
 53 | 							</td>
 54 | 		</tr>
 55 | 			<tr id="schema-rating">
 56 | 			<td>
 57 | 				<code>rating</code>
 58 | 			</td>
 59 | 			<td>
 60 | 				<p>The star rating of the block.</p>
 61 | 				<p class="type">
 62 | 					JSON data type: number				</p>
 63 | 								<p class="context">Context: <code>view</code></p>
 64 | 							</td>
 65 | 		</tr>
 66 | 			<tr id="schema-rating_count">
 67 | 			<td>
 68 | 				<code>rating_count</code>
 69 | 			</td>
 70 | 			<td>
 71 | 				<p>The number of ratings.</p>
 72 | 				<p class="type">
 73 | 					JSON data type: integer				</p>
 74 | 								<p class="context">Context: <code>view</code></p>
 75 | 							</td>
 76 | 		</tr>
 77 | 			<tr id="schema-active_installs">
 78 | 			<td>
 79 | 				<code>active_installs</code>
 80 | 			</td>
 81 | 			<td>
 82 | 				<p>The number sites that have activated this block.</p>
 83 | 				<p class="type">
 84 | 					JSON data type: integer				</p>
 85 | 								<p class="context">Context: <code>view</code></p>
 86 | 							</td>
 87 | 		</tr>
 88 | 			<tr id="schema-author_block_rating">
 89 | 			<td>
 90 | 				<code>author_block_rating</code>
 91 | 			</td>
 92 | 			<td>
 93 | 				<p>The average rating of blocks published by the same author.</p>
 94 | 				<p class="type">
 95 | 					JSON data type: number				</p>
 96 | 								<p class="context">Context: <code>view</code></p>
 97 | 							</td>
 98 | 		</tr>
 99 | 			<tr id="schema-author_block_count">
100 | 			<td>
101 | 				<code>author_block_count</code>
102 | 			</td>
103 | 			<td>
104 | 				<p>The number of blocks published by the same author.</p>
105 | 				<p class="type">
106 | 					JSON data type: integer				</p>
107 | 								<p class="context">Context: <code>view</code></p>
108 | 							</td>
109 | 		</tr>
110 | 			<tr id="schema-author">
111 | 			<td>
112 | 				<code>author</code>
113 | 			</td>
114 | 			<td>
115 | 				<p>The WordPress.org username of the block author.</p>
116 | 				<p class="type">
117 | 					JSON data type: string				</p>
118 | 								<p class="context">Context: <code>view</code></p>
119 | 							</td>
120 | 		</tr>
121 | 			<tr id="schema-icon">
122 | 			<td>
123 | 				<code>icon</code>
124 | 			</td>
125 | 			<td>
126 | 				<p>The block icon.</p>
127 | 				<p class="type">
128 | 					JSON data type: string,
129 | 											Format: uri
130 | 									</p>
131 | 								<p class="context">Context: <code>view</code></p>
132 | 							</td>
133 | 		</tr>
134 | 			<tr id="schema-last_updated">
135 | 			<td>
136 | 				<code>last_updated</code>
137 | 			</td>
138 | 			<td>
139 | 				<p>The date when the block was last updated.</p>
140 | 				<p class="type">
141 | 					JSON data type: string,
142 | 											Format: datetime (<a href="https://core.trac.wordpress.org/ticket/41032">details</a>)
143 | 									</p>
144 | 								<p class="context">Context: <code>view</code></p>
145 | 							</td>
146 | 		</tr>
147 | 			<tr id="schema-humanized_updated">
148 | 			<td>
149 | 				<code>humanized_updated</code>
150 | 			</td>
151 | 			<td>
152 | 				<p>The date when the block was last updated, in fuzzy human readable format.</p>
153 | 				<p class="type">
154 | 					JSON data type: string				</p>
155 | 								<p class="context">Context: <code>view</code></p>
156 | 							</td>
157 | 		</tr>
158 | 	</table>
159 | 
160 | 	</div>
161 | </section>
162 | 
163 | <div><section class="route">
164 | 	<div class="primary">
165 | 		<h2>List Block Directory Items</h2>
166 | 		<p>Query this endpoint to retrieve a collection of block directory items. The response you receive can be controlled and filtered using the URL query parameters below.</p>
167 | 
168 | 		<h3>Definition</h3>
169 | 
170 | 		<code>GET /wp/v2/block-directory/search</code>
171 | 
172 | 		<h3>Example Request</h3>
173 | 
174 | 		<code>$ curl https://example.com/wp-json/wp/v2/block-directory/search</code>
175 | 	</div>
176 | 	<div class="secondary">
177 | 			<h3>Arguments</h3>
178 | 	<table class="arguments">
179 | 					<tr>
180 | 				<td>
181 | 											<code>context</code><br />
182 | 									</td>
183 | 				<td>
184 | 											<p>Scope under which the request is made; determines fields present in response.</p>
185 | 																					<p class="default">
186 | 							Default: <code>view</code>
187 | 						</p>
188 | 																<p>One of: <code>view</code></p>
189 | 									</td>
190 | 			</tr>
191 | 					<tr>
192 | 				<td>
193 | 											<code>page</code><br />
194 | 									</td>
195 | 				<td>
196 | 											<p>Current page of the collection.</p>
197 | 																					<p class="default">
198 | 							Default: <code>1</code>
199 | 						</p>
200 | 														</td>
201 | 			</tr>
202 | 					<tr>
203 | 				<td>
204 | 											<code>per_page</code><br />
205 | 									</td>
206 | 				<td>
207 | 											<p>Maximum number of items to be returned in result set.</p>
208 | 																					<p class="default">
209 | 							Default: <code>10</code>
210 | 						</p>
211 | 														</td>
212 | 			</tr>
213 | 					<tr>
214 | 				<td>
215 | 											<code>term</code><br />
216 | 									</td>
217 | 				<td>
218 | 											<p>Limit result set to blocks matching the search term.</p>
219 | 																<p class="required">
220 | 							Required: 1
221 | 						</p>
222 | 																			</td>
223 | 			</tr>
224 | 			</table>
225 | 
226 | 	</div>
227 | </section>
228 | </div>
229 | 


--------------------------------------------------------------------------------
/reference/pattern-directory-items.md:
--------------------------------------------------------------------------------
  1 | ---
  2 | ---
  3 | 
  4 | # Pattern Directory Items
  5 | 
  6 | <section class="route">
  7 | 	<div class="primary">
  8 | 		<h2>Schema</h2>
  9 | <p>The schema defines all the fields that exist within a pattern directory item record. Any response from these endpoints can be expected to contain the fields below unless the `_filter` query parameter is used or the schema field only appears in a specific context.</p>
 10 | <table class="attributes">
 11 | 			<tr id="schema-id">
 12 | 			<td>
 13 | 				<code>id</code>
 14 | 			</td>
 15 | 			<td>
 16 | 				<p>The pattern ID.</p>
 17 | 				<p class="type">
 18 | 					JSON data type: integer				</p>
 19 | 								<p class="context">Context: <code>view</code>, <code>edit</code>, <code>embed</code></p>
 20 | 							</td>
 21 | 		</tr>
 22 | 			<tr id="schema-title">
 23 | 			<td>
 24 | 				<code>title</code>
 25 | 			</td>
 26 | 			<td>
 27 | 				<p>The pattern title, in human readable format.</p>
 28 | 				<p class="type">
 29 | 					JSON data type: string				</p>
 30 | 								<p class="context">Context: <code>view</code>, <code>edit</code>, <code>embed</code></p>
 31 | 							</td>
 32 | 		</tr>
 33 | 			<tr id="schema-content">
 34 | 			<td>
 35 | 				<code>content</code>
 36 | 			</td>
 37 | 			<td>
 38 | 				<p>The pattern content.</p>
 39 | 				<p class="type">
 40 | 					JSON data type: string				</p>
 41 | 								<p class="context">Context: <code>view</code>, <code>edit</code>, <code>embed</code></p>
 42 | 							</td>
 43 | 		</tr>
 44 | 			<tr id="schema-categories">
 45 | 			<td>
 46 | 				<code>categories</code>
 47 | 			</td>
 48 | 			<td>
 49 | 				<p>The pattern&#039;s category slugs.</p>
 50 | 				<p class="type">
 51 | 					JSON data type: array				</p>
 52 | 								<p class="context">Context: <code>view</code>, <code>edit</code>, <code>embed</code></p>
 53 | 							</td>
 54 | 		</tr>
 55 | 			<tr id="schema-keywords">
 56 | 			<td>
 57 | 				<code>keywords</code>
 58 | 			</td>
 59 | 			<td>
 60 | 				<p>The pattern&#039;s keywords.</p>
 61 | 				<p class="type">
 62 | 					JSON data type: array				</p>
 63 | 								<p class="context">Context: <code>view</code>, <code>edit</code>, <code>embed</code></p>
 64 | 							</td>
 65 | 		</tr>
 66 | 			<tr id="schema-description">
 67 | 			<td>
 68 | 				<code>description</code>
 69 | 			</td>
 70 | 			<td>
 71 | 				<p>A description of the pattern.</p>
 72 | 				<p class="type">
 73 | 					JSON data type: string				</p>
 74 | 								<p class="context">Context: <code>view</code>, <code>edit</code>, <code>embed</code></p>
 75 | 							</td>
 76 | 		</tr>
 77 | 			<tr id="schema-viewport_width">
 78 | 			<td>
 79 | 				<code>viewport_width</code>
 80 | 			</td>
 81 | 			<td>
 82 | 				<p>The preferred width of the viewport when previewing a pattern, in pixels.</p>
 83 | 				<p class="type">
 84 | 					JSON data type: integer				</p>
 85 | 								<p class="context">Context: <code>view</code>, <code>edit</code>, <code>embed</code></p>
 86 | 							</td>
 87 | 		</tr>
 88 | 			<tr id="schema-block_types">
 89 | 			<td>
 90 | 				<code>block_types</code>
 91 | 			</td>
 92 | 			<td>
 93 | 				<p>The block types which can use this pattern.</p>
 94 | 				<p class="type">
 95 | 					JSON data type: array				</p>
 96 | 								<p class="context">Context: <code>view</code>, <code>embed</code></p>
 97 | 							</td>
 98 | 		</tr>
 99 | 	</table>
100 | 
101 | 	</div>
102 | </section>
103 | 
104 | <div><section class="route">
105 | 	<div class="primary">
106 | 		<h2>List Pattern Directory Items</h2>
107 | 		<p>Query this endpoint to retrieve a collection of pattern directory items. The response you receive can be controlled and filtered using the URL query parameters below.</p>
108 | 
109 | 		<h3>Definition</h3>
110 | 
111 | 		<code>GET /wp/v2/pattern-directory/patterns</code>
112 | 
113 | 		<h3>Example Request</h3>
114 | 
115 | 		<code>$ curl https://example.com/wp-json/wp/v2/pattern-directory/patterns</code>
116 | 	</div>
117 | 	<div class="secondary">
118 | 			<h3>Arguments</h3>
119 | 	<table class="arguments">
120 | 					<tr>
121 | 				<td>
122 | 											<code>context</code><br />
123 | 									</td>
124 | 				<td>
125 | 											<p>Scope under which the request is made; determines fields present in response.</p>
126 | 																					<p class="default">
127 | 							Default: <code>view</code>
128 | 						</p>
129 | 																<p>One of: <code>view</code>, <code>embed</code>, <code>edit</code></p>
130 | 									</td>
131 | 			</tr>
132 | 					<tr>
133 | 				<td>
134 | 											<code>page</code><br />
135 | 									</td>
136 | 				<td>
137 | 											<p>Current page of the collection.</p>
138 | 																					<p class="default">
139 | 							Default: <code>1</code>
140 | 						</p>
141 | 														</td>
142 | 			</tr>
143 | 					<tr>
144 | 				<td>
145 | 											<code>per_page</code><br />
146 | 									</td>
147 | 				<td>
148 | 											<p>Maximum number of items to be returned in result set.</p>
149 | 																					<p class="default">
150 | 							Default: <code>100</code>
151 | 						</p>
152 | 														</td>
153 | 			</tr>
154 | 					<tr>
155 | 				<td>
156 | 											<code>search</code><br />
157 | 									</td>
158 | 				<td>
159 | 											<p>Limit results to those matching a string.</p>
160 | 																								</td>
161 | 			</tr>
162 | 					<tr>
163 | 				<td>
164 | 											<code>category</code><br />
165 | 									</td>
166 | 				<td>
167 | 											<p>Limit results to those matching a category ID.</p>
168 | 																								</td>
169 | 			</tr>
170 | 					<tr>
171 | 				<td>
172 | 											<code>keyword</code><br />
173 | 									</td>
174 | 				<td>
175 | 											<p>Limit results to those matching a keyword ID.</p>
176 | 																								</td>
177 | 			</tr>
178 | 					<tr>
179 | 				<td>
180 | 											<code>slug</code><br />
181 | 									</td>
182 | 				<td>
183 | 											<p>Limit results to those matching a pattern (slug).</p>
184 | 																								</td>
185 | 			</tr>
186 | 					<tr>
187 | 				<td>
188 | 											<code>offset</code><br />
189 | 									</td>
190 | 				<td>
191 | 											<p>Offset the result set by a specific number of items.</p>
192 | 																								</td>
193 | 			</tr>
194 | 					<tr>
195 | 				<td>
196 | 											<code>order</code><br />
197 | 									</td>
198 | 				<td>
199 | 											<p>Order sort attribute ascending or descending.</p>
200 | 																					<p class="default">
201 | 							Default: <code>desc</code>
202 | 						</p>
203 | 																<p>One of: <code>asc</code>, <code>desc</code></p>
204 | 									</td>
205 | 			</tr>
206 | 					<tr>
207 | 				<td>
208 | 											<code>orderby</code><br />
209 | 									</td>
210 | 				<td>
211 | 											<p>Sort collection by post attribute.</p>
212 | 																					<p class="default">
213 | 							Default: <code>date</code>
214 | 						</p>
215 | 																<p>One of: <code>author</code>, <code>date</code>, <code>id</code>, <code>include</code>, <code>modified</code>, <code>parent</code>, <code>relevance</code>, <code>slug</code>, <code>include_slugs</code>, <code>title</code>, <code>favorite_count</code></p>
216 | 									</td>
217 | 			</tr>
218 | 			</table>
219 | 
220 | 	</div>
221 | </section>
222 | </div>
223 | 


--------------------------------------------------------------------------------
/reference/taxonomies.md:
--------------------------------------------------------------------------------
  1 | ---
  2 | ---
  3 | 
  4 | # Taxonomies
  5 | 
  6 | <section class="route">
  7 | 	<div class="primary">
  8 | 		<h2>Schema</h2>
  9 | <p>The schema defines all the fields that exist within a taxonomy record. Any response from these endpoints can be expected to contain the fields below unless the `_filter` query parameter is used or the schema field only appears in a specific context.</p>
 10 | <table class="attributes">
 11 | 			<tr id="schema-capabilities">
 12 | 			<td>
 13 | 				<code>capabilities</code>
 14 | 			</td>
 15 | 			<td>
 16 | 				<p>All capabilities used by the taxonomy.</p>
 17 | 				<p class="type">
 18 | 					JSON data type: object				</p>
 19 | 									<p class="read-only">Read only</p>
 20 | 								<p class="context">Context: <code>edit</code></p>
 21 | 							</td>
 22 | 		</tr>
 23 | 			<tr id="schema-description">
 24 | 			<td>
 25 | 				<code>description</code>
 26 | 			</td>
 27 | 			<td>
 28 | 				<p>A human-readable description of the taxonomy.</p>
 29 | 				<p class="type">
 30 | 					JSON data type: string				</p>
 31 | 									<p class="read-only">Read only</p>
 32 | 								<p class="context">Context: <code>view</code>, <code>edit</code></p>
 33 | 							</td>
 34 | 		</tr>
 35 | 			<tr id="schema-hierarchical">
 36 | 			<td>
 37 | 				<code>hierarchical</code>
 38 | 			</td>
 39 | 			<td>
 40 | 				<p>Whether or not the taxonomy should have children.</p>
 41 | 				<p class="type">
 42 | 					JSON data type: boolean				</p>
 43 | 									<p class="read-only">Read only</p>
 44 | 								<p class="context">Context: <code>view</code>, <code>edit</code></p>
 45 | 							</td>
 46 | 		</tr>
 47 | 			<tr id="schema-labels">
 48 | 			<td>
 49 | 				<code>labels</code>
 50 | 			</td>
 51 | 			<td>
 52 | 				<p>Human-readable labels for the taxonomy for various contexts.</p>
 53 | 				<p class="type">
 54 | 					JSON data type: object				</p>
 55 | 									<p class="read-only">Read only</p>
 56 | 								<p class="context">Context: <code>edit</code></p>
 57 | 							</td>
 58 | 		</tr>
 59 | 			<tr id="schema-name">
 60 | 			<td>
 61 | 				<code>name</code>
 62 | 			</td>
 63 | 			<td>
 64 | 				<p>The title for the taxonomy.</p>
 65 | 				<p class="type">
 66 | 					JSON data type: string				</p>
 67 | 									<p class="read-only">Read only</p>
 68 | 								<p class="context">Context: <code>view</code>, <code>edit</code>, <code>embed</code></p>
 69 | 							</td>
 70 | 		</tr>
 71 | 			<tr id="schema-slug">
 72 | 			<td>
 73 | 				<code>slug</code>
 74 | 			</td>
 75 | 			<td>
 76 | 				<p>An alphanumeric identifier for the taxonomy.</p>
 77 | 				<p class="type">
 78 | 					JSON data type: string				</p>
 79 | 									<p class="read-only">Read only</p>
 80 | 								<p class="context">Context: <code>view</code>, <code>edit</code>, <code>embed</code></p>
 81 | 							</td>
 82 | 		</tr>
 83 | 			<tr id="schema-show_cloud">
 84 | 			<td>
 85 | 				<code>show_cloud</code>
 86 | 			</td>
 87 | 			<td>
 88 | 				<p>Whether or not the term cloud should be displayed.</p>
 89 | 				<p class="type">
 90 | 					JSON data type: boolean				</p>
 91 | 									<p class="read-only">Read only</p>
 92 | 								<p class="context">Context: <code>edit</code></p>
 93 | 							</td>
 94 | 		</tr>
 95 | 			<tr id="schema-types">
 96 | 			<td>
 97 | 				<code>types</code>
 98 | 			</td>
 99 | 			<td>
100 | 				<p>Types associated with the taxonomy.</p>
101 | 				<p class="type">
102 | 					JSON data type: array				</p>
103 | 									<p class="read-only">Read only</p>
104 | 								<p class="context">Context: <code>view</code>, <code>edit</code></p>
105 | 							</td>
106 | 		</tr>
107 | 			<tr id="schema-rest_base">
108 | 			<td>
109 | 				<code>rest_base</code>
110 | 			</td>
111 | 			<td>
112 | 				<p>REST base route for the taxonomy.</p>
113 | 				<p class="type">
114 | 					JSON data type: string				</p>
115 | 									<p class="read-only">Read only</p>
116 | 								<p class="context">Context: <code>view</code>, <code>edit</code>, <code>embed</code></p>
117 | 							</td>
118 | 		</tr>
119 | 			<tr id="schema-rest_namespace">
120 | 			<td>
121 | 				<code>rest_namespace</code>
122 | 			</td>
123 | 			<td>
124 | 				<p>REST namespace route for the taxonomy.</p>
125 | 				<p class="type">
126 | 					JSON data type: string				</p>
127 | 									<p class="read-only">Read only</p>
128 | 								<p class="context">Context: <code>view</code>, <code>edit</code>, <code>embed</code></p>
129 | 							</td>
130 | 		</tr>
131 | 			<tr id="schema-visibility">
132 | 			<td>
133 | 				<code>visibility</code>
134 | 			</td>
135 | 			<td>
136 | 				<p>The visibility settings for the taxonomy.</p>
137 | 				<p class="type">
138 | 					JSON data type: object				</p>
139 | 									<p class="read-only">Read only</p>
140 | 								<p class="context">Context: <code>edit</code></p>
141 | 							</td>
142 | 		</tr>
143 | 	</table>
144 | 
145 | 	</div>
146 | </section>
147 | 
148 | <div><section class="route">
149 | 	<div class="primary">
150 | 		<h2>Retrieve a Taxonomy</h2>
151 | 
152 | 		<h3>Definition & Example Request</h3>
153 | 
154 | 		<code>GET /wp/v2/taxonomies</code>
155 | 
156 | 		<p>Query this endpoint to retrieve a specific taxonomy record.</p>
157 | 
158 | 		<code>$ curl https://example.com/wp-json/wp/v2/taxonomies</code>
159 | 	</div>
160 | 	<div class="secondary">
161 | 			<h3>Arguments</h3>
162 | 	<table class="arguments">
163 | 					<tr>
164 | 				<td>
165 | 											<code>context</code><br />
166 | 									</td>
167 | 				<td>
168 | 											<p>Scope under which the request is made; determines fields present in response.</p>
169 | 																					<p class="default">
170 | 							Default: <code>view</code>
171 | 						</p>
172 | 																<p>One of: <code>view</code>, <code>embed</code>, <code>edit</code></p>
173 | 									</td>
174 | 			</tr>
175 | 					<tr>
176 | 				<td>
177 | 											<code>type</code><br />
178 | 									</td>
179 | 				<td>
180 | 											<p>Limit results to taxonomies associated with a specific post type.</p>
181 | 																								</td>
182 | 			</tr>
183 | 			</table>
184 | 
185 | 	</div>
186 | </section>
187 | <section class="route">
188 | 	<div class="primary">
189 | 		<h2>Retrieve a Taxonomy</h2>
190 | 
191 | 		<h3>Definition & Example Request</h3>
192 | 
193 | 		<code>GET /wp/v2/taxonomies/&lt;taxonomy&gt;</code>
194 | 
195 | 		<p>Query this endpoint to retrieve a specific taxonomy record.</p>
196 | 
197 | 		<code>$ curl https://example.com/wp-json/wp/v2/taxonomies/&lt;taxonomy&gt;</code>
198 | 	</div>
199 | 	<div class="secondary">
200 | 			<h3>Arguments</h3>
201 | 	<table class="arguments">
202 | 					<tr>
203 | 				<td>
204 | 											<code>taxonomy</code><br />
205 | 									</td>
206 | 				<td>
207 | 											<p>An alphanumeric identifier for the taxonomy.</p>
208 | 																								</td>
209 | 			</tr>
210 | 					<tr>
211 | 				<td>
212 | 											<code>context</code><br />
213 | 									</td>
214 | 				<td>
215 | 											<p>Scope under which the request is made; determines fields present in response.</p>
216 | 																					<p class="default">
217 | 							Default: <code>view</code>
218 | 						</p>
219 | 																<p>One of: <code>view</code>, <code>embed</code>, <code>edit</code></p>
220 | 									</td>
221 | 			</tr>
222 | 			</table>
223 | 
224 | 	</div>
225 | </section>
226 | </div>
227 | 


--------------------------------------------------------------------------------
/reference/sidebars.md:
--------------------------------------------------------------------------------
  1 | ---
  2 | ---
  3 | 
  4 | # Sidebars
  5 | 
  6 | <section class="route">
  7 | 	<div class="primary">
  8 | 		<h2>Schema</h2>
  9 | <p>The schema defines all the fields that exist within a sidebar record. Any response from these endpoints can be expected to contain the fields below unless the `_filter` query parameter is used or the schema field only appears in a specific context.</p>
 10 | <table class="attributes">
 11 | 			<tr id="schema-id">
 12 | 			<td>
 13 | 				<code>id</code>
 14 | 			</td>
 15 | 			<td>
 16 | 				<p>ID of sidebar.</p>
 17 | 				<p class="type">
 18 | 					JSON data type: string				</p>
 19 | 									<p class="read-only">Read only</p>
 20 | 								<p class="context">Context: <code>embed</code>, <code>view</code>, <code>edit</code></p>
 21 | 							</td>
 22 | 		</tr>
 23 | 			<tr id="schema-name">
 24 | 			<td>
 25 | 				<code>name</code>
 26 | 			</td>
 27 | 			<td>
 28 | 				<p>Unique name identifying the sidebar.</p>
 29 | 				<p class="type">
 30 | 					JSON data type: string				</p>
 31 | 									<p class="read-only">Read only</p>
 32 | 								<p class="context">Context: <code>embed</code>, <code>view</code>, <code>edit</code></p>
 33 | 							</td>
 34 | 		</tr>
 35 | 			<tr id="schema-description">
 36 | 			<td>
 37 | 				<code>description</code>
 38 | 			</td>
 39 | 			<td>
 40 | 				<p>Description of sidebar.</p>
 41 | 				<p class="type">
 42 | 					JSON data type: string				</p>
 43 | 									<p class="read-only">Read only</p>
 44 | 								<p class="context">Context: <code>embed</code>, <code>view</code>, <code>edit</code></p>
 45 | 							</td>
 46 | 		</tr>
 47 | 			<tr id="schema-class">
 48 | 			<td>
 49 | 				<code>class</code>
 50 | 			</td>
 51 | 			<td>
 52 | 				<p>Extra CSS class to assign to the sidebar in the Widgets interface.</p>
 53 | 				<p class="type">
 54 | 					JSON data type: string				</p>
 55 | 									<p class="read-only">Read only</p>
 56 | 								<p class="context">Context: <code>embed</code>, <code>view</code>, <code>edit</code></p>
 57 | 							</td>
 58 | 		</tr>
 59 | 			<tr id="schema-before_widget">
 60 | 			<td>
 61 | 				<code>before_widget</code>
 62 | 			</td>
 63 | 			<td>
 64 | 				<p>HTML content to prepend to each widget&#039;s HTML output when assigned to this sidebar. Default is an opening list item element.</p>
 65 | 				<p class="type">
 66 | 					JSON data type: string				</p>
 67 | 									<p class="read-only">Read only</p>
 68 | 								<p class="context">Context: <code>embed</code>, <code>view</code>, <code>edit</code></p>
 69 | 							</td>
 70 | 		</tr>
 71 | 			<tr id="schema-after_widget">
 72 | 			<td>
 73 | 				<code>after_widget</code>
 74 | 			</td>
 75 | 			<td>
 76 | 				<p>HTML content to append to each widget&#039;s HTML output when assigned to this sidebar. Default is a closing list item element.</p>
 77 | 				<p class="type">
 78 | 					JSON data type: string				</p>
 79 | 									<p class="read-only">Read only</p>
 80 | 								<p class="context">Context: <code>embed</code>, <code>view</code>, <code>edit</code></p>
 81 | 							</td>
 82 | 		</tr>
 83 | 			<tr id="schema-before_title">
 84 | 			<td>
 85 | 				<code>before_title</code>
 86 | 			</td>
 87 | 			<td>
 88 | 				<p>HTML content to prepend to the sidebar title when displayed. Default is an opening h2 element.</p>
 89 | 				<p class="type">
 90 | 					JSON data type: string				</p>
 91 | 									<p class="read-only">Read only</p>
 92 | 								<p class="context">Context: <code>embed</code>, <code>view</code>, <code>edit</code></p>
 93 | 							</td>
 94 | 		</tr>
 95 | 			<tr id="schema-after_title">
 96 | 			<td>
 97 | 				<code>after_title</code>
 98 | 			</td>
 99 | 			<td>
100 | 				<p>HTML content to append to the sidebar title when displayed. Default is a closing h2 element.</p>
101 | 				<p class="type">
102 | 					JSON data type: string				</p>
103 | 									<p class="read-only">Read only</p>
104 | 								<p class="context">Context: <code>embed</code>, <code>view</code>, <code>edit</code></p>
105 | 							</td>
106 | 		</tr>
107 | 			<tr id="schema-status">
108 | 			<td>
109 | 				<code>status</code>
110 | 			</td>
111 | 			<td>
112 | 				<p>Status of sidebar.</p>
113 | 				<p class="type">
114 | 					JSON data type: string				</p>
115 | 									<p class="read-only">Read only</p>
116 | 								<p class="context">Context: <code>embed</code>, <code>view</code>, <code>edit</code></p>
117 | 									<p>One of: <code>active</code>, <code>inactive</code></p>
118 | 							</td>
119 | 		</tr>
120 | 			<tr id="schema-widgets">
121 | 			<td>
122 | 				<code>widgets</code>
123 | 			</td>
124 | 			<td>
125 | 				<p>Nested widgets.</p>
126 | 				<p class="type">
127 | 					JSON data type: array				</p>
128 | 								<p class="context">Context: <code>embed</code>, <code>view</code>, <code>edit</code></p>
129 | 							</td>
130 | 		</tr>
131 | 	</table>
132 | 
133 | 	</div>
134 | </section>
135 | 
136 | <div><section class="route">
137 | 	<div class="primary">
138 | 		<h2>Retrieve a Sidebar</h2>
139 | 
140 | 		<h3>Definition & Example Request</h3>
141 | 
142 | 		<code>GET /wp/v2/sidebars</code>
143 | 
144 | 		<p>Query this endpoint to retrieve a specific sidebar record.</p>
145 | 
146 | 		<code>$ curl https://example.com/wp-json/wp/v2/sidebars</code>
147 | 	</div>
148 | 	<div class="secondary">
149 | 			<h3>Arguments</h3>
150 | 	<table class="arguments">
151 | 					<tr>
152 | 				<td>
153 | 											<code>context</code><br />
154 | 									</td>
155 | 				<td>
156 | 											<p>Scope under which the request is made; determines fields present in response.</p>
157 | 																					<p class="default">
158 | 							Default: <code>view</code>
159 | 						</p>
160 | 																<p>One of: <code>view</code>, <code>embed</code>, <code>edit</code></p>
161 | 									</td>
162 | 			</tr>
163 | 			</table>
164 | 
165 | 	</div>
166 | </section>
167 | <section class="route">
168 | 	<div class="primary">
169 | 		<h2>Retrieve a Sidebar</h2>
170 | 
171 | 		<h3>Definition & Example Request</h3>
172 | 
173 | 		<code>GET /wp/v2/sidebars/&lt;id&gt;</code>
174 | 
175 | 		<p>Query this endpoint to retrieve a specific sidebar record.</p>
176 | 
177 | 		<code>$ curl https://example.com/wp-json/wp/v2/sidebars/&lt;id&gt;</code>
178 | 	</div>
179 | 	<div class="secondary">
180 | 			<h3>Arguments</h3>
181 | 	<table class="arguments">
182 | 					<tr>
183 | 				<td>
184 | 											<code>id</code><br />
185 | 									</td>
186 | 				<td>
187 | 											<p>The id of a registered sidebar</p>
188 | 																								</td>
189 | 			</tr>
190 | 					<tr>
191 | 				<td>
192 | 											<code>context</code><br />
193 | 									</td>
194 | 				<td>
195 | 											<p>Scope under which the request is made; determines fields present in response.</p>
196 | 																					<p class="default">
197 | 							Default: <code>view</code>
198 | 						</p>
199 | 																<p>One of: <code>view</code>, <code>embed</code>, <code>edit</code></p>
200 | 									</td>
201 | 			</tr>
202 | 			</table>
203 | 
204 | 	</div>
205 | </section>
206 | <section class="route">
207 | 	<div class="primary">
208 | 		<h2>Update a Sidebar</h2>
209 | 			<h3>Arguments</h3>
210 | 	<table class="arguments">
211 | 					<tr>
212 | 				<td>
213 | 											<code><a href="#schema-widgets">widgets</a></code><br />
214 | 									</td>
215 | 				<td>
216 | 											<p>Nested widgets.</p>
217 | 																								</td>
218 | 			</tr>
219 | 			</table>
220 | 
221 | 	</div>
222 | 	<div class="secondary">
223 | 		<h3>Definition</h3>
224 | 
225 | 		<code>POST /wp/v2/sidebars/&lt;id&gt;</code>
226 | 
227 | 		<h3>Example Request</h3>
228 | 
229 | 		<code></code>
230 | 	</div>
231 | </section>
232 | </div>
233 | 


--------------------------------------------------------------------------------
/using-the-rest-api/global-parameters.md:
--------------------------------------------------------------------------------
  1 | # Global Parameters
  2 | 
  3 | The API includes a number of global parameters (also called "meta-parameters") which control how the API handles the request/response handling. These operate at a layer above the actual resources themselves, and are available on all resources.
  4 | 
  5 | ## `_fields`
  6 | 
  7 | A REST resource like a Post contains a large quantity of data: basic information such as content, title, and author ID, but also [registered metadata and fields](https://developer.wordpress.org/rest-api/extending-the-rest-api/modifying-responses/), media information, and links to other resources. Your application may not need all of this information on every request.
  8 | 
  9 | To instruct WordPress to return only a subset of the fields in a response, you may use the `_fields` query parameter. If for example you are building an archive view and only need the ID, title, permalink, author and excerpt for a collection of posts, you can restrict the response to only those properties with this fields query:
 10 | 
 11 | ```
 12 | /wp/v2/posts?_fields=author,id,excerpt,title,link
 13 | ```
 14 | 
 15 | You may alternatively provide that same list using query parameter array syntax instead of a comma-separated list:
 16 | 
 17 | ```
 18 | /wp/v2/posts?_fields[]=author&_fields[]=id&_fields[]=excerpt&_fields[]=title&_fields[]=link
 19 | ```
 20 | 
 21 | When `_fields` is provided then WordPress will skip unneeded fields when generating your response object, avoiding potentially expensive internal computation or queries for data you don't need. This also means the JSON object returned from the REST API will be smaller, requiring less time to download and less time to parse on your client device.
 22 | 
 23 | Carefully design your queries to pull in only the needed properties from each resource to make your application faster to use and more efficient to run.
 24 | 
 25 | As of WordPress 5.3 the `_fields` parameter supports nested properties. This can be useful if you have registered many meta keys, permitting you to request the value for only one of the registered meta properties:
 26 | 
 27 | ```
 28 | ?_fields=meta.one-of-many-keys
 29 | ```
 30 | 
 31 | Only the meta value with the key `one-of-many-keys` will be returned, and others will be excluded.
 32 | 
 33 | You can also request specific deeply-nested properties within a complex meta object:
 34 | 
 35 | ```
 36 | ?_fields=meta.key_name.nested_prop.deeply_nested_prop,meta.key_name.other_nested_prop
 37 | ```
 38 | 
 39 | 
 40 | ## `_embed`
 41 | 
 42 | Most resources include links to related resources. For example, a post can link to the parent post, or to comments on the post. To reduce the number of HTTP requests required, clients may wish to fetch a resource as well as the linked resources. The `_embed` parameter indicates to the server that the response should include these embedded resources.
 43 | 
 44 | Embed mode is enabled if the `_embed` parameter is passed in the query string (GET parameter). This parameter does not require a value (i.e. `?_embed` is valid), however can be passed "1" as a value if required by a client library.
 45 | 
 46 | As of WordPress 5.4, the resources to embed can be limited by passing a list of link relation names to the `_embed` parameter. For example, `/wp/v2/posts?_embed=author,wp:term` will only embed the post's author and the lists of terms associated with the post.
 47 | 
 48 | Resources in embed mode will contain an additional `_embedded` key next to the `_links` key containing the linked resources. Only links with the `embeddable` parameter set to `true` will be embedded.
 49 | 
 50 | In order to use `_embed` together with `_fields`, add `_embedded` as well as `_links` to the fields, for instance, `/wp-json/wp/v2/posts/_embed=author,wp:term&_fields=title,author,_links,_embedded`.
 51 | 
 52 | For more about linking and embedding, see the [Linking and Embedding](https://developer.wordpress.org/rest-api/linking-and-embedding/) page.
 53 | 
 54 | ## `_method` (or `X-HTTP-Method-Override` header)
 55 | 
 56 | Some servers and clients cannot correctly process some HTTP methods that the API makes use of. For example, all deletion requests on resources use the `DELETE` method, but some clients do not provide the ability to send this method.
 57 | 
 58 | To ensure compatibility with these servers and clients, the API supports a method override. This can be passed either via a `_method` parameter or the `X-HTTP-Method-Override` header, with the value set to the HTTP method to use.
 59 | 
 60 | [alert]
 61 | Clients should only ever send a method override parameter or header with POST requests. Using the method override with GET requests may cause the request to be incorrectly cached.
 62 | [/alert]
 63 | 
 64 | A `POST` to `/wp-json/wp/v2/posts/42?_method=DELETE` would be translated to a `DELETE` to the `wp/v2/posts/42` route.
 65 | 
 66 | Similarly, the following POST request would become a DELETE:
 67 | 
 68 | ```
 69 | POST /wp-json/wp/v2/posts/42 HTTP/1.1
 70 | Host: example.com
 71 | X-HTTP-Method-Override: DELETE
 72 | ```
 73 | 
 74 | ## `_envelope`
 75 | 
 76 | Similarly to `_method`, some servers, clients, and proxies do not support accessing the full response data. The API supports passing an `_envelope` parameter, which sends all response data in the body, including headers and status code.
 77 | 
 78 | Envelope mode is enabled if the `_envelope` parameter is passed in the query string (GET parameter). This parameter does not require a value (i.e. `?_envelope` is valid), but can be passed "1" as a value if required by a client library.
 79 | 
 80 | [info]
 81 | For future compatibility, other values should not be passed.
 82 | [/info]
 83 | 
 84 | Enveloped responses include a "fake" HTTP 200 response code with no additional headers (apart from Content-Type) that should ensure the response correctly passes through intermediaries.
 85 | 
 86 | For example, given the following response to a `GET` to `wp/v2/users/me`:
 87 | 
 88 | ```
 89 | HTTP/1.1 302 Found
 90 | Location: http://example.com/wp-json/wp/v2/users/42
 91 | 
 92 | {
 93 |   "id": 42,
 94 |   ...
 95 | }
 96 | ```
 97 | 
 98 | The equivalent enveloped response (with a `GET` to `wp/v2/users/me?_envelope`) would be:
 99 | 
100 | ```
101 | HTTP/1.1 200 OK
102 | 
103 | {
104 |   "status": 302,
105 |   "headers": {
106 |     "Location": "http://example.com/wp-json/wp/v2/users/42"
107 |   },
108 |   "body": {
109 |     "id": 42
110 |   }
111 | }
112 | ```
113 | 
114 | ## `_jsonp`
115 | 
116 | The API natively supports [JSONP](https://en.wikipedia.org/wiki/JSONP) responses to allow cross-domain requests for legacy browsers and clients. This parameter takes a JavaScript callback function which will be prepended to the data. This URL can then be loaded via a `<script>` tag.
117 | 
118 | The callback function can contain any alphanumeric, `_` (underscore), or `.` (period) character. Callbacks which contain invalid characters will receive a HTTP 400 error response, and the callback will not be called.
119 | 
120 | [info]
121 | Modern browsers can use <a href="https://en.wikipedia.org/wiki/Cross-origin_resource_sharing">Cross-Origin Resource Sharing (CORS)</a> preflight requests for cross-domain requests, but JSONP can be used to ensure support with all browsers.
122 | 
123 | <ul>
124 |   <li><a href="http://caniuse.com/#feat=cors">Browser Support</a></li>
125 |   <li><a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Access_control_CORS">MDN Article on CORS</a></li>
126 | </ul>
127 | [/info]
128 | 
129 | For example:
130 | 
131 | ```html
132 | <script>
133 | function receiveData( data ) {
134 |   // Do something with the data here.
135 |   // For demonstration purposes, we'll simply log it.
136 |   console.log( data );
137 | }
138 | </script>
139 | <script src="https://example.com/wp-json/?_jsonp=receiveData"></script>
140 | ```
141 | 


--------------------------------------------------------------------------------
/reference/themes.md:
--------------------------------------------------------------------------------
  1 | ---
  2 | ---
  3 | 
  4 | # Themes
  5 | 
  6 | <section class="route">
  7 | 	<div class="primary">
  8 | 		<h2>Schema</h2>
  9 | <p>The schema defines all the fields that exist within a theme record. Any response from these endpoints can be expected to contain the fields below unless the `_filter` query parameter is used or the schema field only appears in a specific context.</p>
 10 | <table class="attributes">
 11 | 			<tr id="schema-stylesheet">
 12 | 			<td>
 13 | 				<code>stylesheet</code>
 14 | 			</td>
 15 | 			<td>
 16 | 				<p>The theme&#039;s stylesheet. This uniquely identifies the theme.</p>
 17 | 				<p class="type">
 18 | 					JSON data type: string				</p>
 19 | 									<p class="read-only">Read only</p>
 20 | 								<p class="context">Context: <code></code></p>
 21 | 							</td>
 22 | 		</tr>
 23 | 			<tr id="schema-template">
 24 | 			<td>
 25 | 				<code>template</code>
 26 | 			</td>
 27 | 			<td>
 28 | 				<p>The theme&#039;s template. If this is a child theme, this refers to the parent theme, otherwise this is the same as the theme&#039;s stylesheet.</p>
 29 | 				<p class="type">
 30 | 					JSON data type: string				</p>
 31 | 									<p class="read-only">Read only</p>
 32 | 								<p class="context">Context: <code></code></p>
 33 | 							</td>
 34 | 		</tr>
 35 | 			<tr id="schema-author">
 36 | 			<td>
 37 | 				<code>author</code>
 38 | 			</td>
 39 | 			<td>
 40 | 				<p>The theme author.</p>
 41 | 				<p class="type">
 42 | 					JSON data type: object				</p>
 43 | 									<p class="read-only">Read only</p>
 44 | 								<p class="context">Context: <code></code></p>
 45 | 							</td>
 46 | 		</tr>
 47 | 			<tr id="schema-author_uri">
 48 | 			<td>
 49 | 				<code>author_uri</code>
 50 | 			</td>
 51 | 			<td>
 52 | 				<p>The website of the theme author.</p>
 53 | 				<p class="type">
 54 | 					JSON data type: object				</p>
 55 | 									<p class="read-only">Read only</p>
 56 | 								<p class="context">Context: <code></code></p>
 57 | 							</td>
 58 | 		</tr>
 59 | 			<tr id="schema-description">
 60 | 			<td>
 61 | 				<code>description</code>
 62 | 			</td>
 63 | 			<td>
 64 | 				<p>A description of the theme.</p>
 65 | 				<p class="type">
 66 | 					JSON data type: object				</p>
 67 | 									<p class="read-only">Read only</p>
 68 | 								<p class="context">Context: <code></code></p>
 69 | 							</td>
 70 | 		</tr>
 71 | 			<tr id="schema-is_block_theme">
 72 | 			<td>
 73 | 				<code>is_block_theme</code>
 74 | 			</td>
 75 | 			<td>
 76 | 				<p>Whether the theme is a block-based theme.</p>
 77 | 				<p class="type">
 78 | 					JSON data type: boolean				</p>
 79 | 									<p class="read-only">Read only</p>
 80 | 								<p class="context">Context: <code></code></p>
 81 | 							</td>
 82 | 		</tr>
 83 | 			<tr id="schema-name">
 84 | 			<td>
 85 | 				<code>name</code>
 86 | 			</td>
 87 | 			<td>
 88 | 				<p>The name of the theme.</p>
 89 | 				<p class="type">
 90 | 					JSON data type: object				</p>
 91 | 									<p class="read-only">Read only</p>
 92 | 								<p class="context">Context: <code></code></p>
 93 | 							</td>
 94 | 		</tr>
 95 | 			<tr id="schema-requires_php">
 96 | 			<td>
 97 | 				<code>requires_php</code>
 98 | 			</td>
 99 | 			<td>
100 | 				<p>The minimum PHP version required for the theme to work.</p>
101 | 				<p class="type">
102 | 					JSON data type: string				</p>
103 | 									<p class="read-only">Read only</p>
104 | 								<p class="context">Context: <code></code></p>
105 | 							</td>
106 | 		</tr>
107 | 			<tr id="schema-requires_wp">
108 | 			<td>
109 | 				<code>requires_wp</code>
110 | 			</td>
111 | 			<td>
112 | 				<p>The minimum WordPress version required for the theme to work.</p>
113 | 				<p class="type">
114 | 					JSON data type: string				</p>
115 | 									<p class="read-only">Read only</p>
116 | 								<p class="context">Context: <code></code></p>
117 | 							</td>
118 | 		</tr>
119 | 			<tr id="schema-screenshot">
120 | 			<td>
121 | 				<code>screenshot</code>
122 | 			</td>
123 | 			<td>
124 | 				<p>The theme&#039;s screenshot URL.</p>
125 | 				<p class="type">
126 | 					JSON data type: string,
127 | 											Format: uri
128 | 									</p>
129 | 									<p class="read-only">Read only</p>
130 | 								<p class="context">Context: <code></code></p>
131 | 							</td>
132 | 		</tr>
133 | 			<tr id="schema-tags">
134 | 			<td>
135 | 				<code>tags</code>
136 | 			</td>
137 | 			<td>
138 | 				<p>Tags indicating styles and features of the theme.</p>
139 | 				<p class="type">
140 | 					JSON data type: object				</p>
141 | 									<p class="read-only">Read only</p>
142 | 								<p class="context">Context: <code></code></p>
143 | 							</td>
144 | 		</tr>
145 | 			<tr id="schema-textdomain">
146 | 			<td>
147 | 				<code>textdomain</code>
148 | 			</td>
149 | 			<td>
150 | 				<p>The theme&#039;s text domain.</p>
151 | 				<p class="type">
152 | 					JSON data type: string				</p>
153 | 									<p class="read-only">Read only</p>
154 | 								<p class="context">Context: <code></code></p>
155 | 							</td>
156 | 		</tr>
157 | 			<tr id="schema-theme_supports">
158 | 			<td>
159 | 				<code>theme_supports</code>
160 | 			</td>
161 | 			<td>
162 | 				<p>Features supported by this theme.</p>
163 | 				<p class="type">
164 | 					JSON data type: object				</p>
165 | 									<p class="read-only">Read only</p>
166 | 								<p class="context">Context: <code></code></p>
167 | 							</td>
168 | 		</tr>
169 | 			<tr id="schema-theme_uri">
170 | 			<td>
171 | 				<code>theme_uri</code>
172 | 			</td>
173 | 			<td>
174 | 				<p>The URI of the theme&#039;s webpage.</p>
175 | 				<p class="type">
176 | 					JSON data type: object				</p>
177 | 									<p class="read-only">Read only</p>
178 | 								<p class="context">Context: <code></code></p>
179 | 							</td>
180 | 		</tr>
181 | 			<tr id="schema-version">
182 | 			<td>
183 | 				<code>version</code>
184 | 			</td>
185 | 			<td>
186 | 				<p>The theme&#039;s current version.</p>
187 | 				<p class="type">
188 | 					JSON data type: string				</p>
189 | 									<p class="read-only">Read only</p>
190 | 								<p class="context">Context: <code></code></p>
191 | 							</td>
192 | 		</tr>
193 | 			<tr id="schema-status">
194 | 			<td>
195 | 				<code>status</code>
196 | 			</td>
197 | 			<td>
198 | 				<p>A named status for the theme.</p>
199 | 				<p class="type">
200 | 					JSON data type: string				</p>
201 | 								<p class="context">Context: <code></code></p>
202 | 									<p>One of: <code>inactive</code>, <code>active</code></p>
203 | 							</td>
204 | 		</tr>
205 | 	</table>
206 | 
207 | 	</div>
208 | </section>
209 | 
210 | <div><section class="route">
211 | 	<div class="primary">
212 | 		<h2>Retrieve a Theme</h2>
213 | 
214 | 		<h3>Definition & Example Request</h3>
215 | 
216 | 		<code>GET /wp/v2/themes</code>
217 | 
218 | 		<p>Query this endpoint to retrieve a specific theme record.</p>
219 | 
220 | 		<code>$ curl https://example.com/wp-json/wp/v2/themes</code>
221 | 	</div>
222 | 	<div class="secondary">
223 | 			<h3>Arguments</h3>
224 | 	<table class="arguments">
225 | 					<tr>
226 | 				<td>
227 | 											<code>status</code><br />
228 | 									</td>
229 | 				<td>
230 | 											<p>Limit result set to themes assigned one or more statuses.</p>
231 | 																								</td>
232 | 			</tr>
233 | 			</table>
234 | 
235 | 	</div>
236 | </section>
237 | <section class="route">
238 | 	<div class="primary">
239 | 		<h2>Retrieve a Theme</h2>
240 | 
241 | 		<h3>Definition & Example Request</h3>
242 | 
243 | 		<code>GET /wp/v2/themes/&lt;stylesheet&gt;?)</code>
244 | 
245 | 		<p>Query this endpoint to retrieve a specific theme record.</p>
246 | 
247 | 		<code>$ curl https://example.com/wp-json/wp/v2/themes/&lt;stylesheet&gt;?)</code>
248 | 	</div>
249 | 	<div class="secondary">
250 | 			<h3>Arguments</h3>
251 | 	<table class="arguments">
252 | 					<tr>
253 | 				<td>
254 | 											<code>stylesheet</code><br />
255 | 									</td>
256 | 				<td>
257 | 											<p>The theme&#039;s stylesheet. This uniquely identifies the theme.</p>
258 | 																								</td>
259 | 			</tr>
260 | 			</table>
261 | 
262 | 	</div>
263 | </section>
264 | </div>
265 | 


--------------------------------------------------------------------------------
/using-the-rest-api/discovery.md:
--------------------------------------------------------------------------------
  1 | # Discovery
  2 | 
  3 | When your client talks to an unknown site, you'll need to discover what the site is capable of and how the site is configured. There are a couple of steps for this, depending on what you need to discover.
  4 | 
  5 | 
  6 | ## Discovering the API
  7 | 
  8 | The first step of connecting to a site is finding out whether the site has the API enabled. Typically, you'll be working with URLs from user input, so the site you're accessing could be anything. The discovery step lets you verify the API is available, as well as indicating how to access it.
  9 | 
 10 | 
 11 | ### Link Header
 12 | 
 13 | The preferred way to handle discovery is to send a HEAD request to the supplied address. The REST API automatically adds a Link header to all front-end pages that looks like the following:
 14 | 
 15 | 	Link: <http://example.com/wp-json/>; rel="https://api.w.org/"
 16 | 
 17 | This URL points to the root route (`/`) of the API, which is then used for further discovery steps.
 18 | 
 19 | For sites without "pretty permalinks" enabled, `/wp-json/` isn't automatically handled by WordPress. This means that normal/default WordPress permalinks will be used instead. These headers look more like this:
 20 | 
 21 | 	Link: <http://example.com/?rest_route=/>; rel="https://api.w.org/"
 22 | 
 23 | Clients should keep this variation in mind and ensure that both routes can be handled seamlessly.
 24 | 
 25 | This auto-discovery can be applied to any URL served by a WordPress installation, so no pre-processing on user input needs to be added. Since this is a HEAD request, the request should be safe to send blindly to servers without worrying about causing side-effects.
 26 | 
 27 | 
 28 | ### Element
 29 | 
 30 | For clients with a HTML parser, or running in the browser, the equivalent of the Link header is included in the `<head>` of front-end pages through a `<link>` element:
 31 | 
 32 | 	<link rel='https://api.w.org/' href='http://example.com/wp-json/' />
 33 | 
 34 | In-browser Javascript can access this via the DOM:
 35 | 
 36 | ```js
 37 | // jQuery method
 38 | var $link = jQuery( 'link[rel="https://api.w.org/"]' );
 39 | var api_root = $link.attr( 'href' );
 40 | 
 41 | // Native method
 42 | var links = document.getElementsByTagName( 'link' );
 43 | var link = Array.prototype.filter.call( links, function ( item ) {
 44 | 	return ( item.rel === 'https://api.w.org/' );
 45 | } );
 46 | var api_root = link[0].href;
 47 | ```
 48 | 
 49 | For in-browser clients, or clients without access to HTTP headers, this may be a more usable way of discovering the API. This is similar to Atom/RSS feed discovery, so existing code for that purpose may also be automatically adapted instead.
 50 | 
 51 | 
 52 | ### RSD (Really Simple Discovery)
 53 | 
 54 | For clients with support for XML-RPC discovery, the [RSD method](http://cyber.law.harvard.edu/blogs/gems/tech/rsd.html) may be more applicable. This is an XML-based discovery format typically used for XML-RPC. RSD has two steps. The first step is to find the RSD endpoint, supplied as a `<link>` element:
 55 | 
 56 | 	<link rel="EditURI" type="application/rsd+xml" title="RSD" href="http://example.com/xmlrpc.php?rsd" />
 57 | 
 58 | The second step is to fetch the RSD document and parse the available endpoints. This involves using an XML parser on a document like the following:
 59 | 
 60 | ```xml
 61 | <?xml version="1.0" encoding="utf-8"?>
 62 | <rsd version="1.0" xmlns="http://archipelago.phrasewise.com/rsd">
 63 |   <service>
 64 |     <engineName>WordPress</engineName>
 65 |     <engineLink>http://wordpress.org/</engineLink>
 66 |     <homePageLink>http://example.com/</homePageLink>
 67 |     <apis>
 68 |       <api name="WordPress" blogID="1" preferred="true" apiLink="http://example.com/xmlrpc.php" />
 69 |       <!-- ... -->
 70 |       <api name="WP-API" blogID="1" preferred="false" apiLink="http://example.com/wp-json/" />
 71 |     </apis>
 72 |   </service>
 73 | </rsd>
 74 | ```
 75 | 
 76 | The REST API always has a `name` attribute with the value equal to `WP-API`.
 77 | 
 78 | RSD is the least-preferred method of autodiscovery for a couple of reasons. The first step of RSD-based discovery involves parsing the HTML to first find the RSD document itself, which is equivalent to the `<link>` Element autodiscovery. It then involves another step to parse the RSD document, which requires a full XML parser.
 79 | 
 80 | Where possible, we suggest avoiding RSD-based discovery due to the complexity, but existing XML-RPC clients may prefer to use this method if they already have an RSD parser enabled. For XML-RPC clients which wish to use the REST API as a progressive enhancement to the codebase, this avoids needing to support different forms of discovery.
 81 | 
 82 | 
 83 | ## Authentication Discovery
 84 | 
 85 | Discovery is also available for authentication methods available via the API. The API root's response is an object describing the API, which includes an `authentication` key:
 86 | 
 87 | ```
 88 | {
 89 | 	"name": "Example WordPress Site",
 90 | 	"description": "YOLO",
 91 | 	"routes": { ... },
 92 | 	"authentication": {
 93 | 		"oauth1": {
 94 | 			"request": "http://example.com/oauth/request",
 95 | 			"authorize": "http://example.com/oauth/authorize",
 96 | 			"access": "http://example.com/oauth/access",
 97 | 			"version": "0.1"
 98 | 		}
 99 | 	}
100 | }
101 | ```
102 | 
103 | The `authentication` value is a map (associative array) of authentication method ID to authentication options. The options available here are specific to the authentication method itself. See the [authentication documentation](/rest-api/authentication/) for the options for specific authentication methods.
104 | 
105 | 
106 | ## Extension Discovery
107 | 
108 | Once you've discovered the API, the next step is check what the API supports. The index of the API exposes the `namespaces` item, which contains the extensions to the API that are supported.
109 | 
110 | For WordPress sites using versions 4.4 through 4.6, only the base API infrastructure is available, not the full API with endpoints. This also includes the oEmbed endpoints:
111 | 
112 | ```
113 | {
114 | 	"name": "Example WordPress Site",
115 | 	"namespaces": [
116 | 		"oembed/1.0/"
117 | 	]
118 | }
119 | ```
120 | 
121 | Sites with the full API available (i.e. with WordPress 4.7+ or the REST API plugin installed) will have the `wp/v2` item in `namespaces` as well:
122 | 
123 | ```
124 | {
125 | 	"name": "Example WordPress Site",
126 | 	"namespaces": [
127 | 		"wp/v2",
128 | 		"oembed/1.0/"
129 | 	]
130 | }
131 | ```
132 | 
133 | Before attempting to use any of the core endpoints, you should be sure to check that the API is supported by checking for `wp/v2` support. WordPress 4.4 enabled the API infrastructure for all sites, but did **not** include the core endpoints under `wp/v2`. Core endpoints were added in WordPress 4.7.
134 | 
135 | This same mechanism can be used for detecting support for any plugins that support the REST API. For example, take a plugin which registers the following route:
136 | 
137 | ```php
138 | <?php
139 | register_rest_route( 'testplugin/v1', '/testroute', array( /* ... */ ) );
140 | ```
141 | 
142 | This would add the `testplugin/v1` namespace to the index:
143 | 
144 | ```
145 | {
146 | 	"name": "Example WordPress Site",
147 | 	"namespaces": [
148 | 		"wp/v2",
149 | 		"oembed/1.0/",
150 | 		"testplugin/v1"
151 | 	]
152 | }
153 | ```
154 | 
155 | ## Resource Discovery
156 | 
157 | 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 `application/json` that points to a REST API url. The link is added both as a [`Link` header](#link-header) and a [`<link>` element](#element).
158 | 
159 | For instance, in the `<head>` section of this page, the following `<link>` appears.
160 | 
161 | ```html
162 | <link rel="alternate" type="application/json" href="https://developer.wordpress.org/wp-json/wp/v2/rest-api-handbook/23085">
163 | ```
164 | 
165 | 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.
166 | 


--------------------------------------------------------------------------------
/reference/post-types.md:
--------------------------------------------------------------------------------
  1 | ---
  2 | ---
  3 | 
  4 | # Types
  5 | 
  6 | <section class="route">
  7 | 	<div class="primary">
  8 | 		<h2>Schema</h2>
  9 | <p>The schema defines all the fields that exist within a type record. Any response from these endpoints can be expected to contain the fields below unless the `_filter` query parameter is used or the schema field only appears in a specific context.</p>
 10 | <table class="attributes">
 11 | 			<tr id="schema-capabilities">
 12 | 			<td>
 13 | 				<code>capabilities</code>
 14 | 			</td>
 15 | 			<td>
 16 | 				<p>All capabilities used by the post type.</p>
 17 | 				<p class="type">
 18 | 					JSON data type: object				</p>
 19 | 									<p class="read-only">Read only</p>
 20 | 								<p class="context">Context: <code>edit</code></p>
 21 | 							</td>
 22 | 		</tr>
 23 | 			<tr id="schema-description">
 24 | 			<td>
 25 | 				<code>description</code>
 26 | 			</td>
 27 | 			<td>
 28 | 				<p>A human-readable description of the post type.</p>
 29 | 				<p class="type">
 30 | 					JSON data type: string				</p>
 31 | 									<p class="read-only">Read only</p>
 32 | 								<p class="context">Context: <code>view</code>, <code>edit</code></p>
 33 | 							</td>
 34 | 		</tr>
 35 | 			<tr id="schema-hierarchical">
 36 | 			<td>
 37 | 				<code>hierarchical</code>
 38 | 			</td>
 39 | 			<td>
 40 | 				<p>Whether or not the post type should have children.</p>
 41 | 				<p class="type">
 42 | 					JSON data type: boolean				</p>
 43 | 									<p class="read-only">Read only</p>
 44 | 								<p class="context">Context: <code>view</code>, <code>edit</code></p>
 45 | 							</td>
 46 | 		</tr>
 47 | 			<tr id="schema-viewable">
 48 | 			<td>
 49 | 				<code>viewable</code>
 50 | 			</td>
 51 | 			<td>
 52 | 				<p>Whether or not the post type can be viewed.</p>
 53 | 				<p class="type">
 54 | 					JSON data type: boolean				</p>
 55 | 									<p class="read-only">Read only</p>
 56 | 								<p class="context">Context: <code>edit</code></p>
 57 | 							</td>
 58 | 		</tr>
 59 | 			<tr id="schema-labels">
 60 | 			<td>
 61 | 				<code>labels</code>
 62 | 			</td>
 63 | 			<td>
 64 | 				<p>Human-readable labels for the post type for various contexts.</p>
 65 | 				<p class="type">
 66 | 					JSON data type: object				</p>
 67 | 									<p class="read-only">Read only</p>
 68 | 								<p class="context">Context: <code>edit</code></p>
 69 | 							</td>
 70 | 		</tr>
 71 | 			<tr id="schema-name">
 72 | 			<td>
 73 | 				<code>name</code>
 74 | 			</td>
 75 | 			<td>
 76 | 				<p>The title for the post type.</p>
 77 | 				<p class="type">
 78 | 					JSON data type: string				</p>
 79 | 									<p class="read-only">Read only</p>
 80 | 								<p class="context">Context: <code>view</code>, <code>edit</code>, <code>embed</code></p>
 81 | 							</td>
 82 | 		</tr>
 83 | 			<tr id="schema-slug">
 84 | 			<td>
 85 | 				<code>slug</code>
 86 | 			</td>
 87 | 			<td>
 88 | 				<p>An alphanumeric identifier for the post type.</p>
 89 | 				<p class="type">
 90 | 					JSON data type: string				</p>
 91 | 									<p class="read-only">Read only</p>
 92 | 								<p class="context">Context: <code>view</code>, <code>edit</code>, <code>embed</code></p>
 93 | 							</td>
 94 | 		</tr>
 95 | 			<tr id="schema-supports">
 96 | 			<td>
 97 | 				<code>supports</code>
 98 | 			</td>
 99 | 			<td>
100 | 				<p>All features, supported by the post type.</p>
101 | 				<p class="type">
102 | 					JSON data type: object				</p>
103 | 									<p class="read-only">Read only</p>
104 | 								<p class="context">Context: <code>edit</code></p>
105 | 							</td>
106 | 		</tr>
107 | 			<tr id="schema-has_archive">
108 | 			<td>
109 | 				<code>has_archive</code>
110 | 			</td>
111 | 			<td>
112 | 				<p>If the value is a string, the value will be used as the archive slug. If the value is false the post type has no archive.</p>
113 | 				<p class="type">
114 | 					JSON data type: string or boolean				</p>
115 | 									<p class="read-only">Read only</p>
116 | 								<p class="context">Context: <code>view</code>, <code>edit</code></p>
117 | 							</td>
118 | 		</tr>
119 | 			<tr id="schema-taxonomies">
120 | 			<td>
121 | 				<code>taxonomies</code>
122 | 			</td>
123 | 			<td>
124 | 				<p>Taxonomies associated with post type.</p>
125 | 				<p class="type">
126 | 					JSON data type: array				</p>
127 | 									<p class="read-only">Read only</p>
128 | 								<p class="context">Context: <code>view</code>, <code>edit</code></p>
129 | 							</td>
130 | 		</tr>
131 | 			<tr id="schema-rest_base">
132 | 			<td>
133 | 				<code>rest_base</code>
134 | 			</td>
135 | 			<td>
136 | 				<p>REST base route for the post type.</p>
137 | 				<p class="type">
138 | 					JSON data type: string				</p>
139 | 									<p class="read-only">Read only</p>
140 | 								<p class="context">Context: <code>view</code>, <code>edit</code>, <code>embed</code></p>
141 | 							</td>
142 | 		</tr>
143 | 			<tr id="schema-rest_namespace">
144 | 			<td>
145 | 				<code>rest_namespace</code>
146 | 			</td>
147 | 			<td>
148 | 				<p>REST route&#039;s namespace for the post type.</p>
149 | 				<p class="type">
150 | 					JSON data type: string				</p>
151 | 									<p class="read-only">Read only</p>
152 | 								<p class="context">Context: <code>view</code>, <code>edit</code>, <code>embed</code></p>
153 | 							</td>
154 | 		</tr>
155 | 			<tr id="schema-visibility">
156 | 			<td>
157 | 				<code>visibility</code>
158 | 			</td>
159 | 			<td>
160 | 				<p>The visibility settings for the post type.</p>
161 | 				<p class="type">
162 | 					JSON data type: object				</p>
163 | 									<p class="read-only">Read only</p>
164 | 								<p class="context">Context: <code>edit</code></p>
165 | 							</td>
166 | 		</tr>
167 | 			<tr id="schema-icon">
168 | 			<td>
169 | 				<code>icon</code>
170 | 			</td>
171 | 			<td>
172 | 				<p>The icon for the post type.</p>
173 | 				<p class="type">
174 | 					JSON data type: string or null				</p>
175 | 									<p class="read-only">Read only</p>
176 | 								<p class="context">Context: <code>view</code>, <code>edit</code>, <code>embed</code></p>
177 | 							</td>
178 | 		</tr>
179 | 	</table>
180 | 
181 | 	</div>
182 | </section>
183 | 
184 | <div><section class="route">
185 | 	<div class="primary">
186 | 		<h2>Retrieve a Type</h2>
187 | 
188 | 		<h3>Definition & Example Request</h3>
189 | 
190 | 		<code>GET /wp/v2/types</code>
191 | 
192 | 		<p>Query this endpoint to retrieve a specific type record.</p>
193 | 
194 | 		<code>$ curl https://example.com/wp-json/wp/v2/types</code>
195 | 	</div>
196 | 	<div class="secondary">
197 | 			<h3>Arguments</h3>
198 | 	<table class="arguments">
199 | 					<tr>
200 | 				<td>
201 | 											<code>context</code><br />
202 | 									</td>
203 | 				<td>
204 | 											<p>Scope under which the request is made; determines fields present in response.</p>
205 | 																					<p class="default">
206 | 							Default: <code>view</code>
207 | 						</p>
208 | 																<p>One of: <code>view</code>, <code>embed</code>, <code>edit</code></p>
209 | 									</td>
210 | 			</tr>
211 | 			</table>
212 | 
213 | 	</div>
214 | </section>
215 | <section class="route">
216 | 	<div class="primary">
217 | 		<h2>Retrieve a Type</h2>
218 | 
219 | 		<h3>Definition & Example Request</h3>
220 | 
221 | 		<code>GET /wp/v2/types/&lt;type&gt;</code>
222 | 
223 | 		<p>Query this endpoint to retrieve a specific type record.</p>
224 | 
225 | 		<code>$ curl https://example.com/wp-json/wp/v2/types/&lt;type&gt;</code>
226 | 	</div>
227 | 	<div class="secondary">
228 | 			<h3>Arguments</h3>
229 | 	<table class="arguments">
230 | 					<tr>
231 | 				<td>
232 | 											<code>type</code><br />
233 | 									</td>
234 | 				<td>
235 | 											<p>An alphanumeric identifier for the post type.</p>
236 | 																								</td>
237 | 			</tr>
238 | 					<tr>
239 | 				<td>
240 | 											<code>context</code><br />
241 | 									</td>
242 | 				<td>
243 | 											<p>Scope under which the request is made; determines fields present in response.</p>
244 | 																					<p class="default">
245 | 							Default: <code>view</code>
246 | 						</p>
247 | 																<p>One of: <code>view</code>, <code>embed</code>, <code>edit</code></p>
248 | 									</td>
249 | 			</tr>
250 | 			</table>
251 | 
252 | 	</div>
253 | </section>
254 | </div>
255 | 


--------------------------------------------------------------------------------
/using-the-rest-api/backbone-javascript-client.md:
--------------------------------------------------------------------------------
  1 | # Backbone JavaScript Client
  2 | 
  3 | The REST API includes a JavaScript/Backbone client library.
  4 | 
  5 | The library provides an interface for the WP REST API by providing Backbone Models and Collections for all endpoints exposed through the API Schema.
  6 | 
  7 | 
  8 | ## Using
  9 | 
 10 | Activate the WP-API plugin. Enqueue the script directly:
 11 | 
 12 | ```php
 13 | wp_enqueue_script( 'wp-api' );
 14 | ```
 15 | 
 16 | or as a dependency for your script:
 17 | 
 18 | ```php
 19 | wp_enqueue_script( 'my_script', 'path/to/my/script', array( 'wp-api' ) );
 20 | ```
 21 | 
 22 | The library parses the root endpoint (the 'Schema') and creates matching Backbone models and collections. You will now have two root objects available to you: `wp.api.models` and `wp.api.collections`.
 23 | 
 24 | The models and collections include:
 25 | 
 26 | Models:
 27 | * Category
 28 | * Comment
 29 | * Media
 30 | * Page
 31 | * PageMeta
 32 | * PageRevision
 33 | * Post
 34 | * PostMeta
 35 | * PostRevision
 36 | * Schema
 37 | * Status
 38 | * Tag
 39 | * Taxonomy
 40 | * Type
 41 | * User
 42 | 
 43 | Collections:
 44 | * Categories
 45 | * Comments
 46 | * Media
 47 | * PageMeta
 48 | * PageRevisions
 49 | * Pages
 50 | * Posts
 51 | * Statuses
 52 | * Tags
 53 | * Taxonomies
 54 | * Types
 55 | * Users
 56 | 
 57 | You can use these endpoints as-is to read, update, create and delete items using standard Backbone methods (fetch, sync, save & destroy for models, sync for collections). You can also extend these objects to make them your own, and build your views on top of them.
 58 | 
 59 | 
 60 | ### Default values
 61 | 
 62 | Each model and collection includes a reference to its default values, for example:
 63 | 
 64 | `wp.api.models.Post.prototype.args`
 65 | 
 66 | * author: null
 67 | * comment_status: null
 68 | * content: null
 69 | * date: null
 70 | * date_gmt: null
 71 | * excerpt: null
 72 | * featured_media: null
 73 | * format: null
 74 | * modified: null
 75 | * modified_gmt: null
 76 | * password: null
 77 | * ping_status: null
 78 | * slug: null
 79 | * status: null
 80 | * sticky: null
 81 | * title: null
 82 | 
 83 | 
 84 | ### Available methods
 85 | 
 86 | Each model and collection contains a list of methods the corresponding endpoint supports. For example, models created from `wp.api.models.Post` have a methods array of:
 87 | 
 88 | ```js
 89 | ["GET", "POST", "PUT", "PATCH", "DELETE"]
 90 | ```
 91 | 
 92 | 
 93 | ### Accepted options
 94 | 
 95 | Each model and collection contains a list of options the corresponding endpoint accepts (note that options are passed as the second parameter when creating models or collections), for example:
 96 | 
 97 | `wp.api.collections.Posts.prototype.options`
 98 | 
 99 | * author
100 | * context
101 | * filter
102 | * order
103 | * orderby
104 | * page
105 | * per_page
106 | * search
107 | * status
108 | 
109 | 
110 | ### Localizing the API Schema
111 | 
112 | The client will accept and use a localized schema as part of the `wpApiSettings` object. The Schema is currently not passed by default; instead the client makes an ajax request to the API to load the Schema, then caches it in the browser's session storage (if available). Activating the client-js plugin with `SCRIPT_DEBUG` enabled uses a localized Schema. Check the [client-js example](https://github.com/WP-API/client-js/blob/master/client-js.php) or this branch which [attempts to only localize the schema once per client](https://github.com/WP-API/client-js/compare/features/only-localize-schma-once?expand=1).
113 | 
114 | 
115 | ### Waiting for the client to load
116 | 
117 | Client startup is asynchronous. If the api schema is localized, the client can start immediately; if not the client makes an ajax request to load the schema. The client exposes a load promise for provide a reliable wait to wait for client to be ready:
118 | 
119 | ```js
120 | wp.api.loadPromise.done( function() {
121 | //... use the client here
122 | } )
123 | ```
124 | 
125 | 
126 | ### Model examples:
127 | 
128 | To create a post and edit its categories, make sure you are logged in, then:
129 | 
130 | ```js
131 | // Create a new post
132 | var post = new wp.api.models.Post( { title: 'This is a test post' } );
133 | post.save();
134 | 
135 | // Load an existing post
136 | var post = new wp.api.models.Post( { id: 1 } );
137 | post.fetch();
138 | 
139 | // Get a collection of the post's categories (returns a promise)
140 | // Uses _embedded data if available, in which case promise resolves immediately.
141 | 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"
146 | } );
147 | 
148 | // Get a posts author User model.
149 | post.getAuthorUser().done( function( user ){
150 |   // ... do something with user
151 |   console.log( user.get( "name" ) );
152 | } );
153 | 
154 | // Get a posts featured image Media model.
155 | post.getFeaturedMedia().done( function( image ){
156 |   // ... do something with image
157 |   console.log( image );
158 | } );
159 | 
160 | // Set the post categories.
161 | post.setCategories( [ "apples", "oranges" ] );
162 | 
163 | // Get all the categories
164 | var allCategories = new wp.api.collections.Categories()
165 | allCategories.fetch();
166 | 
167 | var appleCategory = allCategories.findWhere( { slug: "apples" } );
168 | 
169 | // Add the category to the postCategories collection we previously fetched.
170 | appleCategory.set( "parent_post", post.get( "id" ) );
171 | 
172 | // Use the POST method so Backbone will not PUT it even though it has an id.
173 | postCategories.create( appleCategory.toJSON(), { type: "POST" } );
174 | 
175 | // Remove the Uncategorized category
176 | postCategories.at( 0 ).destroy();
177 | 
178 | // Check the results - re-fetch
179 | postCategories = post.getCategories();
180 | 
181 | postCategories.at( 0 ).get( "name" );
182 | // response -> "apples"
183 | ```
184 | 
185 | ### Collection examples:
186 | To get the last 10 posts:
187 | 
188 | ```js
189 | var postsCollection = new wp.api.collections.Posts();
190 | postsCollection.fetch();
191 | ```
192 | 
193 | To get the last 25 posts:
194 | 
195 | ```js
196 | postsCollection.fetch( { data: { per_page: 25 } } );
197 | ```
198 | 
199 | Use filter to change the order & orderby options:
200 | 
201 | ```js
202 | postsCollection.fetch( { data: { 'filter': { 'orderby': 'title', 'order': 'ASC' } } } );
203 | ```
204 | 
205 | All collections support pagination automatically, and you can get the next page of results using `more`:
206 | 
207 | ```js
208 | postsCollection.more();
209 | ```
210 | 
211 | To get page 5 of a collection:
212 | 
213 | ```js
214 | posts.fetch( { data: { page: 5 } } );
215 | ```
216 | 
217 | Check if the collection has any more posts:
218 | 
219 | ```js
220 | posts.hasMore();
221 | ```
222 | 
223 | 
224 | ### Working With Revisions
225 | 
226 | You can access post or page revisions using the PostRevisions or PageRevisions collections or through the Post or Page collection.
227 | 
228 | For example, to get a collection of all revisions of post ID 1:
229 | 
230 | ```js
231 | var revisions = new wp.api.collections.PostRevisions({}, { parent: 1 });
232 | ```
233 | 
234 | Revision collections can also be accessed via their parent's collection. This example makes 2 HTTP requests instead of one, but now the original post and its revisions are available:
235 | 
236 | ```js
237 | var post = new wp.api.models.Post( { id: 1 } );
238 | post.fetch();
239 | post.getRevisions().done( function( revisions ){
240 |   console.log( revisions );
241 | });
242 | ```
243 | 
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](https://developer.wordpress.org/rest-api/extending-the-rest-api/adding-rest-api-support-for-custom-content-types/). To access custom endpoints created, use the item's JSON endpoint name as CamelCase; for example if the item is found at the JSON path of /wp-json/wp/v2/my-custom-post, it can be accessed via the api at wp.api.collections.MyCustomPost.  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.
245 | 
246 | ```js
247 | // Extend wp.api.models.Post and wp.api.collections.Posts to load a custom post type
248 | const CustomPost = wp.api.models.Post.extend( {
249 |   urlRoot: wpApiSettings.root + 'wp/v2/custom_post_slug',
250 |   defaults: {
251 |     type: 'custom_post_slug',
252 |   },
253 | } );
254 | const CustomPosts = wp.api.collections.Posts.extend( {
255 |   url: wpApiSettings.root + 'wp/v2/custom_post_slug',
256 |   model: BLProduct,
257 | } );
258 | const someCustomPosts = new CustomPosts();
259 | someCustomPosts.fetch().then( ( posts ) => {
260 |   // do something with the custom posts
261 | } );
262 | ```
263 | 


--------------------------------------------------------------------------------
/reference/widgets.md:
--------------------------------------------------------------------------------
  1 | ---
  2 | ---
  3 | 
  4 | # Widgets
  5 | 
  6 | <section class="route">
  7 | 	<div class="primary">
  8 | 		<h2>Schema</h2>
  9 | <p>The schema defines all the fields that exist within a widget record. Any response from these endpoints can be expected to contain the fields below unless the `_filter` query parameter is used or the schema field only appears in a specific context.</p>
 10 | <table class="attributes">
 11 | 			<tr id="schema-id">
 12 | 			<td>
 13 | 				<code>id</code>
 14 | 			</td>
 15 | 			<td>
 16 | 				<p>Unique identifier for the widget.</p>
 17 | 				<p class="type">
 18 | 					JSON data type: string				</p>
 19 | 								<p class="context">Context: <code>view</code>, <code>edit</code>, <code>embed</code></p>
 20 | 							</td>
 21 | 		</tr>
 22 | 			<tr id="schema-id_base">
 23 | 			<td>
 24 | 				<code>id_base</code>
 25 | 			</td>
 26 | 			<td>
 27 | 				<p>The type of the widget. Corresponds to ID in widget-types endpoint.</p>
 28 | 				<p class="type">
 29 | 					JSON data type: string				</p>
 30 | 								<p class="context">Context: <code>view</code>, <code>edit</code>, <code>embed</code></p>
 31 | 							</td>
 32 | 		</tr>
 33 | 			<tr id="schema-sidebar">
 34 | 			<td>
 35 | 				<code>sidebar</code>
 36 | 			</td>
 37 | 			<td>
 38 | 				<p>The sidebar the widget belongs to.</p>
 39 | 				<p class="type">
 40 | 					JSON data type: string				</p>
 41 | 								<p class="context">Context: <code>view</code>, <code>edit</code>, <code>embed</code></p>
 42 | 							</td>
 43 | 		</tr>
 44 | 			<tr id="schema-rendered">
 45 | 			<td>
 46 | 				<code>rendered</code>
 47 | 			</td>
 48 | 			<td>
 49 | 				<p>HTML representation of the widget.</p>
 50 | 				<p class="type">
 51 | 					JSON data type: string				</p>
 52 | 									<p class="read-only">Read only</p>
 53 | 								<p class="context">Context: <code>view</code>, <code>edit</code>, <code>embed</code></p>
 54 | 							</td>
 55 | 		</tr>
 56 | 			<tr id="schema-rendered_form">
 57 | 			<td>
 58 | 				<code>rendered_form</code>
 59 | 			</td>
 60 | 			<td>
 61 | 				<p>HTML representation of the widget admin form.</p>
 62 | 				<p class="type">
 63 | 					JSON data type: string				</p>
 64 | 									<p class="read-only">Read only</p>
 65 | 								<p class="context">Context: <code>edit</code></p>
 66 | 							</td>
 67 | 		</tr>
 68 | 			<tr id="schema-instance">
 69 | 			<td>
 70 | 				<code>instance</code>
 71 | 			</td>
 72 | 			<td>
 73 | 				<p>Instance settings of the widget, if supported.</p>
 74 | 				<p class="type">
 75 | 					JSON data type: object				</p>
 76 | 								<p class="context">Context: <code>edit</code></p>
 77 | 							</td>
 78 | 		</tr>
 79 | 			<tr id="schema-form_data">
 80 | 			<td>
 81 | 				<code>form_data</code>
 82 | 			</td>
 83 | 			<td>
 84 | 				<p>URL-encoded form data from the widget admin form. Used to update a widget that does not support instance. Write only.</p>
 85 | 				<p class="type">
 86 | 					JSON data type: string				</p>
 87 | 								<p class="context">Context: <code></code></p>
 88 | 							</td>
 89 | 		</tr>
 90 | 	</table>
 91 | 
 92 | 	</div>
 93 | </section>
 94 | 
 95 | <div><section class="route">
 96 | 	<div class="primary">
 97 | 		<h2>Retrieve a Widget</h2>
 98 | 
 99 | 		<h3>Definition & Example Request</h3>
100 | 
101 | 		<code>GET /wp/v2/widgets</code>
102 | 
103 | 		<p>Query this endpoint to retrieve a specific widget record.</p>
104 | 
105 | 		<code>$ curl https://example.com/wp-json/wp/v2/widgets</code>
106 | 	</div>
107 | 	<div class="secondary">
108 | 			<h3>Arguments</h3>
109 | 	<table class="arguments">
110 | 					<tr>
111 | 				<td>
112 | 											<code>context</code><br />
113 | 									</td>
114 | 				<td>
115 | 											<p>Scope under which the request is made; determines fields present in response.</p>
116 | 																					<p class="default">
117 | 							Default: <code>view</code>
118 | 						</p>
119 | 																<p>One of: <code>view</code>, <code>embed</code>, <code>edit</code></p>
120 | 									</td>
121 | 			</tr>
122 | 					<tr>
123 | 				<td>
124 | 											<code>sidebar</code><br />
125 | 									</td>
126 | 				<td>
127 | 											<p>The sidebar to return widgets for.</p>
128 | 																								</td>
129 | 			</tr>
130 | 			</table>
131 | 
132 | 	</div>
133 | </section>
134 | <section class="route">
135 | 	<div class="primary">
136 | 		<h2>Create a Widget</h2>
137 | 			<h3>Arguments</h3>
138 | 	<table class="arguments">
139 | 					<tr>
140 | 				<td>
141 | 											<code><a href="#schema-id">id</a></code><br />
142 | 									</td>
143 | 				<td>
144 | 											<p>Unique identifier for the widget.</p>
145 | 																								</td>
146 | 			</tr>
147 | 					<tr>
148 | 				<td>
149 | 											<code><a href="#schema-id_base">id_base</a></code><br />
150 | 									</td>
151 | 				<td>
152 | 											<p>The type of the widget. Corresponds to ID in widget-types endpoint.</p>
153 | 																								</td>
154 | 			</tr>
155 | 					<tr>
156 | 				<td>
157 | 											<code><a href="#schema-sidebar">sidebar</a></code><br />
158 | 									</td>
159 | 				<td>
160 | 											<p>The sidebar the widget belongs to.</p>
161 | 																<p class="required">
162 | 							Required: 1
163 | 						</p>
164 | 																<p class="default">
165 | 							Default: <code>wp_inactive_widgets</code>
166 | 						</p>
167 | 														</td>
168 | 			</tr>
169 | 					<tr>
170 | 				<td>
171 | 											<code><a href="#schema-instance">instance</a></code><br />
172 | 									</td>
173 | 				<td>
174 | 											<p>Instance settings of the widget, if supported.</p>
175 | 																								</td>
176 | 			</tr>
177 | 					<tr>
178 | 				<td>
179 | 											<code><a href="#schema-form_data">form_data</a></code><br />
180 | 									</td>
181 | 				<td>
182 | 											<p>URL-encoded form data from the widget admin form. Used to update a widget that does not support instance. Write only.</p>
183 | 																								</td>
184 | 			</tr>
185 | 			</table>
186 | 
187 | 	</div>
188 | 	<div class="secondary">
189 | 		<h3>Definition</h3>
190 | 
191 | 		<code>POST /wp/v2/widgets</code>
192 | 	</div>
193 | </section>
194 | <section class="route">
195 | 	<div class="primary">
196 | 		<h2>Retrieve a Widget</h2>
197 | 
198 | 		<h3>Definition & Example Request</h3>
199 | 
200 | 		<code>GET /wp/v2/widgets/&lt;id&gt;</code>
201 | 
202 | 		<p>Query this endpoint to retrieve a specific widget record.</p>
203 | 
204 | 		<code>$ curl https://example.com/wp-json/wp/v2/widgets/&lt;id&gt;</code>
205 | 	</div>
206 | 	<div class="secondary">
207 | 			<h3>Arguments</h3>
208 | 	<table class="arguments">
209 | 					<tr>
210 | 				<td>
211 | 											<code>context</code><br />
212 | 									</td>
213 | 				<td>
214 | 											<p>Scope under which the request is made; determines fields present in response.</p>
215 | 																					<p class="default">
216 | 							Default: <code>view</code>
217 | 						</p>
218 | 																<p>One of: <code>view</code>, <code>embed</code>, <code>edit</code></p>
219 | 									</td>
220 | 			</tr>
221 | 			</table>
222 | 
223 | 	</div>
224 | </section>
225 | <section class="route">
226 | 	<div class="primary">
227 | 		<h2>Update a Widget</h2>
228 | 			<h3>Arguments</h3>
229 | 	<table class="arguments">
230 | 					<tr>
231 | 				<td>
232 | 											<code><a href="#schema-id">id</a></code><br />
233 | 									</td>
234 | 				<td>
235 | 											<p>Unique identifier for the widget.</p>
236 | 																								</td>
237 | 			</tr>
238 | 					<tr>
239 | 				<td>
240 | 											<code><a href="#schema-id_base">id_base</a></code><br />
241 | 									</td>
242 | 				<td>
243 | 											<p>The type of the widget. Corresponds to ID in widget-types endpoint.</p>
244 | 																								</td>
245 | 			</tr>
246 | 					<tr>
247 | 				<td>
248 | 											<code><a href="#schema-sidebar">sidebar</a></code><br />
249 | 									</td>
250 | 				<td>
251 | 											<p>The sidebar the widget belongs to.</p>
252 | 																								</td>
253 | 			</tr>
254 | 					<tr>
255 | 				<td>
256 | 											<code><a href="#schema-instance">instance</a></code><br />
257 | 									</td>
258 | 				<td>
259 | 											<p>Instance settings of the widget, if supported.</p>
260 | 																								</td>
261 | 			</tr>
262 | 					<tr>
263 | 				<td>
264 | 											<code><a href="#schema-form_data">form_data</a></code><br />
265 | 									</td>
266 | 				<td>
267 | 											<p>URL-encoded form data from the widget admin form. Used to update a widget that does not support instance. Write only.</p>
268 | 																								</td>
269 | 			</tr>
270 | 			</table>
271 | 
272 | 	</div>
273 | 	<div class="secondary">
274 | 		<h3>Definition</h3>
275 | 
276 | 		<code>POST /wp/v2/widgets/&lt;id&gt;</code>
277 | 
278 | 		<h3>Example Request</h3>
279 | 
280 | 		<code></code>
281 | 	</div>
282 | </section>
283 | <section class="route">
284 | 	<div class="primary">
285 | 		<h2>Delete a Widget</h2>
286 | 			<h3>Arguments</h3>
287 | 	<table class="arguments">
288 | 					<tr>
289 | 				<td>
290 | 											<code>force</code><br />
291 | 									</td>
292 | 				<td>
293 | 											<p>Whether to force removal of the widget, or move it to the inactive sidebar.</p>
294 | 																								</td>
295 | 			</tr>
296 | 			</table>
297 | 
298 | 	</div>
299 | 	<div class="secondary">
300 | 		<h3>Definition</h3>
301 | 
302 | 		<code>DELETE /wp/v2/widgets/&lt;id&gt;</code>
303 | 
304 | 		<h3>Example Request</h3>
305 | 
306 | 		<code>$ curl -X DELETE https://example.com/wp-json/wp/v2/widgets/&lt;id&gt;</code>
307 | 	</div>
308 | </section>
309 | </div>
310 | 


--------------------------------------------------------------------------------
/extending-the-rest-api/adding-rest-api-support-for-custom-content-types.md:
--------------------------------------------------------------------------------
  1 | # Adding REST API Support For Custom Content Types
  2 | 
  3 | The REST API can create routes for custom post types and custom taxonomies inside of the `wp/v2` namespace, using the same controllers as the default post type or taxonomy term controllers. Alternatively, you can use your own controllers and namespace. This document will cover using the default controllers for your custom content type's API routes. This is the easiest way and ensures the highest chance of compatibility with third parties.
  4 | 
  5 | 
  6 | ## Registering A Custom Post Type With REST API Support
  7 | 
  8 | When registering a custom post type, if you want it to be available via the REST API you should set `'show_in_rest' => true` in the arguments passed to `register_post_type`. Setting this argument to true will add a route in the `wp/v2` namespace.
  9 | 
 10 | ```php
 11 | /**
 12 |  * Register a book post type, with REST API support
 13 |  *
 14 |  * Based on example at: https://developer.wordpress.org/reference/functions/register_post_type
 15 |  */
 16 | add_action( 'init', 'my_book_cpt' );
 17 | function my_book_cpt() {
 18 |     $args = array(
 19 |       'public'       => true,
 20 |       'show_in_rest' => true,
 21 |       'label'        => 'Books'
 22 |     );
 23 |     register_post_type( 'book', $args );
 24 | }
 25 | ```
 26 | 
 27 | You can optionally set the `rest_base` argument to change the base url, which will otherwise default to the post type's name. In the example below, "books" is used as the value of `rest_base`. This will make the URL for the route `wp-json/wp/v2/books` instead of `wp-json/wp/v2/book/`, which would have been the default.
 28 | 
 29 | In addition, you can pass an argument for `rest_controller_class`. This class must be a subclass of `WP_REST_Controller`. By default, `WP_REST_Posts_Controller` is used as the controller. If you are using a custom controller, then you likely will not be within the `wp/v2` namespace.
 30 | 
 31 | Here is an example of registering a post type, with full labels, support for the REST API, a customized rest_base, and explicit registry of the default controller:
 32 | 
 33 | ```php
 34 | /**
 35 |  * Register a book post type, with REST API support
 36 |  *
 37 |  * Based on example at: https://developer.wordpress.org/reference/functions/register_post_type
 38 |  */
 39 | add_action( 'init', 'my_book_cpt' );
 40 | function my_book_cpt() {
 41 |   $labels = array(
 42 |     'name'               => _x( 'Books', 'post type general name', 'your-plugin-textdomain' ),
 43 |     'singular_name'      => _x( 'Book', 'post type singular name', 'your-plugin-textdomain' ),
 44 |     'menu_name'          => _x( 'Books', 'admin menu', 'your-plugin-textdomain' ),
 45 |     'name_admin_bar'     => _x( 'Book', 'add new on admin bar', 'your-plugin-textdomain' ),
 46 |     'add_new'            => _x( 'Add New', 'book', 'your-plugin-textdomain' ),
 47 |     'add_new_item'       => __( 'Add New Book', 'your-plugin-textdomain' ),
 48 |     'new_item'           => __( 'New Book', 'your-plugin-textdomain' ),
 49 |     'edit_item'          => __( 'Edit Book', 'your-plugin-textdomain' ),
 50 |     'view_item'          => __( 'View Book', 'your-plugin-textdomain' ),
 51 |     'all_items'          => __( 'All Books', 'your-plugin-textdomain' ),
 52 |     'search_items'       => __( 'Search Books', 'your-plugin-textdomain' ),
 53 |     'parent_item_colon'  => __( 'Parent Books:', 'your-plugin-textdomain' ),
 54 |     'not_found'          => __( 'No books found.', 'your-plugin-textdomain' ),
 55 |     'not_found_in_trash' => __( 'No books found in Trash.', 'your-plugin-textdomain' )
 56 |   );
 57 | 
 58 |   $args = array(
 59 |     'labels'             => $labels,
 60 |     'description'        => __( 'Description.', 'your-plugin-textdomain' ),
 61 |     'public'             => true,
 62 |     'publicly_queryable' => true,
 63 |     'show_ui'            => true,
 64 |     'show_in_menu'       => true,
 65 |     'query_var'          => true,
 66 |     'rewrite'            => array( 'slug' => 'book' ),
 67 |     'capability_type'    => 'post',
 68 |     'has_archive'        => true,
 69 |     'hierarchical'       => false,
 70 |     'menu_position'      => null,
 71 |     'show_in_rest'       => true,
 72 |     'rest_base'          => 'books',
 73 |     'rest_controller_class' => 'WP_REST_Posts_Controller',
 74 |     'supports'           => array( 'title', 'editor', 'author', 'thumbnail', 'excerpt', 'comments' )
 75 |   );
 76 | 
 77 |   register_post_type( 'book', $args );
 78 | }
 79 | ```
 80 | 
 81 | 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.
 82 | 
 83 | ```php
 84 | function my_plugin_rest_route_for_post( $route, $post ) {
 85 |     if ( $post->post_type === 'book' ) {
 86 |         $route = '/wp/v2/books/' . $post->ID;
 87 |     }
 88 |  
 89 |     return $route;
 90 | }
 91 | add_filter( 'rest_route_for_post', 'my_plugin_rest_route_for_post', 10, 2 );
 92 | ``` 
 93 | 
 94 | ## Registering A Custom Taxonomy With REST API Support
 95 | 
 96 | Registering a custom taxonomy with REST API support is very similar to registering a custom post type: pass `'show_in_rest' => true` in the arguments passed to `register_taxonomy`. You may optionally pass `rest_base` to change the base url for the taxonomy's routes.
 97 | 
 98 | The default controller for taxonomies is `WP_REST_Terms_Controller`. You may modify this with the `rest_controller_class` if you choose to use a custom controller.
 99 | 
100 | Here is an example of how to register a custom taxonomy with REST API support:
101 | 
102 | ```php
103 | /**
104 |  * Register a genre post type, with REST API support
105 |  *
106 |  * Based on example at: https://developer.wordpress.org/reference/functions/register_taxonomy/
107 |  */
108 | add_action( 'init', 'my_book_taxonomy', 30 );
109 | function my_book_taxonomy() {
110 | 
111 |   $labels = array(
112 |     'name'              => _x( 'Genres', 'taxonomy general name' ),
113 |     'singular_name'     => _x( 'Genre', 'taxonomy singular name' ),
114 |     'search_items'      => __( 'Search Genres' ),
115 |     'all_items'         => __( 'All Genres' ),
116 |     'parent_item'       => __( 'Parent Genre' ),
117 |     'parent_item_colon' => __( 'Parent Genre:' ),
118 |     'edit_item'         => __( 'Edit Genre' ),
119 |     'update_item'       => __( 'Update Genre' ),
120 |     'add_new_item'      => __( 'Add New Genre' ),
121 |     'new_item_name'     => __( 'New Genre Name' ),
122 |     'menu_name'         => __( 'Genre' ),
123 |   );
124 | 
125 |   $args = array(
126 |     'hierarchical'          => true,
127 |     'labels'                => $labels,
128 |     'show_ui'               => true,
129 |     'show_admin_column'     => true,
130 |     'query_var'             => true,
131 |     'rewrite'               => array( 'slug' => 'genre' ),
132 |     'show_in_rest'          => true,
133 |     'rest_base'             => 'genre',
134 |     'rest_controller_class' => 'WP_REST_Terms_Controller',
135 |   );
136 | 
137 |   register_taxonomy( 'genre', array( 'book' ), $args );
138 | 
139 | }
140 | ```
141 | 
142 | 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.
143 | 
144 | ```php
145 | function my_plugin_rest_route_for_term( $route, $term ) {
146 |     if ( $term->taxonomy === 'genre' ) {
147 |         $route = '/wp/v2/genre/' . $term->term_id;
148 |     }
149 |  
150 |     return $route;
151 | }
152 | add_filter( 'rest_route_for_term', 'my_plugin_rest_route_for_term', 10, 2 );
153 | ``` 
154 | 
155 | ## Adding REST API Support To Existing Content Types
156 | 
157 | 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.
158 | 
159 | ```php
160 | /**
161 |  * Add REST API support to an already registered post type.
162 |  */
163 | add_filter( 'register_post_type_args', 'my_post_type_args', 10, 2 );
164 | 
165 | function my_post_type_args( $args, $post_type ) {
166 | 
167 | 	if ( 'book' === $post_type ) {
168 | 		$args['show_in_rest'] = true;
169 | 
170 | 		// Optionally customize the rest_base or rest_controller_class
171 | 		$args['rest_base']             = 'books';
172 | 		$args['rest_controller_class'] = 'WP_REST_Posts_Controller';
173 | 	}
174 | 
175 | 	return $args;
176 | }
177 | ```
178 | 
179 | 
180 | For custom taxonomies it is almost the same. You can use the `register_taxonomy_args` filter that exists since WordPress version 4.4.0. 
181 | 
182 | ```php
183 | /**
184 |  * Add REST API support to an already registered taxonomy.
185 |  */
186 | add_filter( 'register_taxonomy_args', 'my_taxonomy_args', 10, 2 );
187 | 
188 | function my_taxonomy_args( $args, $taxonomy_name ) {
189 | 
190 | 	if ( 'genre' === $taxonomy_name ) {
191 | 		$args['show_in_rest'] = true;
192 | 
193 | 		// Optionally customize the rest_base or rest_controller_class
194 | 		$args['rest_base']             = 'genres';
195 | 		$args['rest_controller_class'] = 'WP_REST_Terms_Controller';
196 | 	}
197 | 
198 | 	return $args;
199 | }
200 | ```
201 | 
202 | ## Custom Link Relationships
203 | 
204 | Taxonomies & custom post types have a built-in association within WordPress, but what if you want to establish a link between two custom post types? This is not supported formally within WordPress itself, but we can create our own connections between arbitrary content types using the `_link` relation.
205 | 


--------------------------------------------------------------------------------
/reference/application-passwords.md:
--------------------------------------------------------------------------------
  1 | ---
  2 | ---
  3 | 
  4 | # Application Passwords
  5 | 
  6 | <section class="route">
  7 | 	<div class="primary">
  8 | 		<h2>Schema</h2>
  9 | <p>The schema defines all the fields that exist within a application password record. Any response from these endpoints can be expected to contain the fields below unless the `_filter` query parameter is used or the schema field only appears in a specific context.</p>
 10 | <table class="attributes">
 11 | 			<tr id="schema-uuid">
 12 | 			<td>
 13 | 				<code>uuid</code>
 14 | 			</td>
 15 | 			<td>
 16 | 				<p>The unique identifier for the application password.</p>
 17 | 				<p class="type">
 18 | 					JSON data type: string,
 19 | 											Format: uuid
 20 | 									</p>
 21 | 									<p class="read-only">Read only</p>
 22 | 								<p class="context">Context: <code>view</code>, <code>edit</code>, <code>embed</code></p>
 23 | 							</td>
 24 | 		</tr>
 25 | 			<tr id="schema-app_id">
 26 | 			<td>
 27 | 				<code>app_id</code>
 28 | 			</td>
 29 | 			<td>
 30 | 				<p>A UUID provided by the application to uniquely identify it. It is recommended to use an UUID v5 with the URL or DNS namespace.</p>
 31 | 				<p class="type">
 32 | 					JSON data type: string,
 33 | 											Format: uuid
 34 | 									</p>
 35 | 								<p class="context">Context: <code>view</code>, <code>edit</code>, <code>embed</code></p>
 36 | 							</td>
 37 | 		</tr>
 38 | 			<tr id="schema-name">
 39 | 			<td>
 40 | 				<code>name</code>
 41 | 			</td>
 42 | 			<td>
 43 | 				<p>The name of the application password.</p>
 44 | 				<p class="type">
 45 | 					JSON data type: string				</p>
 46 | 								<p class="context">Context: <code>view</code>, <code>edit</code>, <code>embed</code></p>
 47 | 							</td>
 48 | 		</tr>
 49 | 			<tr id="schema-password">
 50 | 			<td>
 51 | 				<code>password</code>
 52 | 			</td>
 53 | 			<td>
 54 | 				<p>The generated password. Only available after adding an application.</p>
 55 | 				<p class="type">
 56 | 					JSON data type: string				</p>
 57 | 									<p class="read-only">Read only</p>
 58 | 								<p class="context">Context: <code>edit</code></p>
 59 | 							</td>
 60 | 		</tr>
 61 | 			<tr id="schema-created">
 62 | 			<td>
 63 | 				<code>created</code>
 64 | 			</td>
 65 | 			<td>
 66 | 				<p>The GMT date the application password was created.</p>
 67 | 				<p class="type">
 68 | 					JSON data type: string,
 69 | 											Format: datetime (<a href="https://core.trac.wordpress.org/ticket/41032">details</a>)
 70 | 									</p>
 71 | 									<p class="read-only">Read only</p>
 72 | 								<p class="context">Context: <code>view</code>, <code>edit</code></p>
 73 | 							</td>
 74 | 		</tr>
 75 | 			<tr id="schema-last_used">
 76 | 			<td>
 77 | 				<code>last_used</code>
 78 | 			</td>
 79 | 			<td>
 80 | 				<p>The GMT date the application password was last used.</p>
 81 | 				<p class="type">
 82 | 					JSON data type: string or null,
 83 | 											Format: datetime (<a href="https://core.trac.wordpress.org/ticket/41032">details</a>)
 84 | 									</p>
 85 | 									<p class="read-only">Read only</p>
 86 | 								<p class="context">Context: <code>view</code>, <code>edit</code></p>
 87 | 							</td>
 88 | 		</tr>
 89 | 			<tr id="schema-last_ip">
 90 | 			<td>
 91 | 				<code>last_ip</code>
 92 | 			</td>
 93 | 			<td>
 94 | 				<p>The IP address the application password was last used by.</p>
 95 | 				<p class="type">
 96 | 					JSON data type: string or null,
 97 | 											Format: ip
 98 | 									</p>
 99 | 									<p class="read-only">Read only</p>
100 | 								<p class="context">Context: <code>view</code>, <code>edit</code></p>
101 | 							</td>
102 | 		</tr>
103 | 	</table>
104 | 
105 | 	</div>
106 | </section>
107 | 
108 | <div><section class="route">
109 | 	<div class="primary">
110 | 		<h2>Retrieve a Application Password</h2>
111 | 
112 | 		<h3>Definition & Example Request</h3>
113 | 
114 | 		<code>GET /wp/v2/users/&lt;user_id&gt;)/application-passwords</code>
115 | 
116 | 		<p>Query this endpoint to retrieve a specific application password record.</p>
117 | 
118 | 		<code>$ curl https://example.com/wp-json/wp/v2/users/&lt;user_id&gt;)/application-passwords</code>
119 | 	</div>
120 | 	<div class="secondary">
121 | 			<h3>Arguments</h3>
122 | 	<table class="arguments">
123 | 					<tr>
124 | 				<td>
125 | 											<code>context</code><br />
126 | 									</td>
127 | 				<td>
128 | 											<p>Scope under which the request is made; determines fields present in response.</p>
129 | 																					<p class="default">
130 | 							Default: <code>view</code>
131 | 						</p>
132 | 																<p>One of: <code>view</code>, <code>embed</code>, <code>edit</code></p>
133 | 									</td>
134 | 			</tr>
135 | 			</table>
136 | 
137 | 	</div>
138 | </section>
139 | <section class="route">
140 | 	<div class="primary">
141 | 		<h2>Create a Application Password</h2>
142 | 			<h3>Arguments</h3>
143 | 	<table class="arguments">
144 | 					<tr>
145 | 				<td>
146 | 											<code><a href="#schema-app_id">app_id</a></code><br />
147 | 									</td>
148 | 				<td>
149 | 											<p>A UUID provided by the application to uniquely identify it. It is recommended to use an UUID v5 with the URL or DNS namespace.</p>
150 | 																								</td>
151 | 			</tr>
152 | 					<tr>
153 | 				<td>
154 | 											<code><a href="#schema-name">name</a></code><br />
155 | 									</td>
156 | 				<td>
157 | 											<p>The name of the application password.</p>
158 | 																<p class="required">
159 | 							Required: 1
160 | 						</p>
161 | 																			</td>
162 | 			</tr>
163 | 			</table>
164 | 
165 | 	</div>
166 | 	<div class="secondary">
167 | 		<h3>Definition</h3>
168 | 
169 | 		<code>POST /wp/v2/users/&lt;user_id&gt;)/application-passwords</code>
170 | 	</div>
171 | </section>
172 | <section class="route">
173 | 	<div class="primary">
174 | 		<h2>Delete a Application Password</h2>
175 | 			<p>There are no arguments for this endpoint.</p>
176 | 
177 | 	</div>
178 | 	<div class="secondary">
179 | 		<h3>Definition</h3>
180 | 
181 | 		<code>DELETE /wp/v2/users/&lt;user_id&gt;)/application-passwords</code>
182 | 
183 | 		<h3>Example Request</h3>
184 | 
185 | 		<code>$ curl -X DELETE https://example.com/wp-json/wp/v2/users/&lt;user_id&gt;)/application-passwords</code>
186 | 	</div>
187 | </section>
188 | <section class="route">
189 | 	<div class="primary">
190 | 		<h2>Retrieve a Application Password</h2>
191 | 
192 | 		<h3>Definition & Example Request</h3>
193 | 
194 | 		<code>GET /wp/v2/users/&lt;user_id&gt;)/application-passwords/introspect</code>
195 | 
196 | 		<p>Query this endpoint to retrieve a specific application password record.</p>
197 | 
198 | 		<code>$ curl https://example.com/wp-json/wp/v2/users/&lt;user_id&gt;)/application-passwords/introspect</code>
199 | 	</div>
200 | 	<div class="secondary">
201 | 			<h3>Arguments</h3>
202 | 	<table class="arguments">
203 | 					<tr>
204 | 				<td>
205 | 											<code>context</code><br />
206 | 									</td>
207 | 				<td>
208 | 											<p>Scope under which the request is made; determines fields present in response.</p>
209 | 																					<p class="default">
210 | 							Default: <code>view</code>
211 | 						</p>
212 | 																<p>One of: <code>view</code>, <code>embed</code>, <code>edit</code></p>
213 | 									</td>
214 | 			</tr>
215 | 			</table>
216 | 
217 | 	</div>
218 | </section>
219 | <section class="route">
220 | 	<div class="primary">
221 | 		<h2>Retrieve a Application Password</h2>
222 | 
223 | 		<h3>Definition & Example Request</h3>
224 | 
225 | 		<code>GET /wp/v2/users/&lt;user_id&gt;)/application-passwords/&lt;uuid&gt;</code>
226 | 
227 | 		<p>Query this endpoint to retrieve a specific application password record.</p>
228 | 
229 | 		<code>$ curl https://example.com/wp-json/wp/v2/users/&lt;user_id&gt;)/application-passwords/&lt;uuid&gt;</code>
230 | 	</div>
231 | 	<div class="secondary">
232 | 			<h3>Arguments</h3>
233 | 	<table class="arguments">
234 | 					<tr>
235 | 				<td>
236 | 											<code>context</code><br />
237 | 									</td>
238 | 				<td>
239 | 											<p>Scope under which the request is made; determines fields present in response.</p>
240 | 																					<p class="default">
241 | 							Default: <code>view</code>
242 | 						</p>
243 | 																<p>One of: <code>view</code>, <code>embed</code>, <code>edit</code></p>
244 | 									</td>
245 | 			</tr>
246 | 			</table>
247 | 
248 | 	</div>
249 | </section>
250 | <section class="route">
251 | 	<div class="primary">
252 | 		<h2>Update a Application Password</h2>
253 | 			<h3>Arguments</h3>
254 | 	<table class="arguments">
255 | 					<tr>
256 | 				<td>
257 | 											<code><a href="#schema-app_id">app_id</a></code><br />
258 | 									</td>
259 | 				<td>
260 | 											<p>A UUID provided by the application to uniquely identify it. It is recommended to use an UUID v5 with the URL or DNS namespace.</p>
261 | 																								</td>
262 | 			</tr>
263 | 					<tr>
264 | 				<td>
265 | 											<code><a href="#schema-name">name</a></code><br />
266 | 									</td>
267 | 				<td>
268 | 											<p>The name of the application password.</p>
269 | 																								</td>
270 | 			</tr>
271 | 			</table>
272 | 
273 | 	</div>
274 | 	<div class="secondary">
275 | 		<h3>Definition</h3>
276 | 
277 | 		<code>POST /wp/v2/users/&lt;user_id&gt;)/application-passwords/&lt;uuid&gt;</code>
278 | 
279 | 		<h3>Example Request</h3>
280 | 
281 | 		<code></code>
282 | 	</div>
283 | </section>
284 | <section class="route">
285 | 	<div class="primary">
286 | 		<h2>Delete a Application Password</h2>
287 | 			<p>There are no arguments for this endpoint.</p>
288 | 
289 | 	</div>
290 | 	<div class="secondary">
291 | 		<h3>Definition</h3>
292 | 
293 | 		<code>DELETE /wp/v2/users/&lt;user_id&gt;)/application-passwords/&lt;uuid&gt;</code>
294 | 
295 | 		<h3>Example Request</h3>
296 | 
297 | 		<code>$ curl -X DELETE https://example.com/wp-json/wp/v2/users/&lt;user_id&gt;)/application-passwords/&lt;uuid&gt;</code>
298 | 	</div>
299 | </section>
300 | </div>
301 | 


--------------------------------------------------------------------------------
/reference/plugins.md:
--------------------------------------------------------------------------------
  1 | ---
  2 | ---
  3 | 
  4 | # Plugins
  5 | 
  6 | <section class="route">
  7 | 	<div class="primary">
  8 | 		<h2>Schema</h2>
  9 | <p>The schema defines all the fields that exist within a plugin record. Any response from these endpoints can be expected to contain the fields below unless the `_filter` query parameter is used or the schema field only appears in a specific context.</p>
 10 | <table class="attributes">
 11 | 			<tr id="schema-plugin">
 12 | 			<td>
 13 | 				<code>plugin</code>
 14 | 			</td>
 15 | 			<td>
 16 | 				<p>The plugin file.</p>
 17 | 				<p class="type">
 18 | 					JSON data type: string				</p>
 19 | 									<p class="read-only">Read only</p>
 20 | 								<p class="context">Context: <code>view</code>, <code>edit</code>, <code>embed</code></p>
 21 | 							</td>
 22 | 		</tr>
 23 | 			<tr id="schema-status">
 24 | 			<td>
 25 | 				<code>status</code>
 26 | 			</td>
 27 | 			<td>
 28 | 				<p>The plugin activation status.</p>
 29 | 				<p class="type">
 30 | 					JSON data type: string				</p>
 31 | 								<p class="context">Context: <code>view</code>, <code>edit</code>, <code>embed</code></p>
 32 | 									<p>One of: <code>inactive</code>, <code>active</code></p>
 33 | 							</td>
 34 | 		</tr>
 35 | 			<tr id="schema-name">
 36 | 			<td>
 37 | 				<code>name</code>
 38 | 			</td>
 39 | 			<td>
 40 | 				<p>The plugin name.</p>
 41 | 				<p class="type">
 42 | 					JSON data type: string				</p>
 43 | 									<p class="read-only">Read only</p>
 44 | 								<p class="context">Context: <code>view</code>, <code>edit</code>, <code>embed</code></p>
 45 | 							</td>
 46 | 		</tr>
 47 | 			<tr id="schema-plugin_uri">
 48 | 			<td>
 49 | 				<code>plugin_uri</code>
 50 | 			</td>
 51 | 			<td>
 52 | 				<p>The plugin&#039;s website address.</p>
 53 | 				<p class="type">
 54 | 					JSON data type: string,
 55 | 											Format: uri
 56 | 									</p>
 57 | 									<p class="read-only">Read only</p>
 58 | 								<p class="context">Context: <code>view</code>, <code>edit</code></p>
 59 | 							</td>
 60 | 		</tr>
 61 | 			<tr id="schema-author">
 62 | 			<td>
 63 | 				<code>author</code>
 64 | 			</td>
 65 | 			<td>
 66 | 				<p>The plugin author.</p>
 67 | 				<p class="type">
 68 | 					JSON data type: object				</p>
 69 | 									<p class="read-only">Read only</p>
 70 | 								<p class="context">Context: <code>view</code>, <code>edit</code></p>
 71 | 							</td>
 72 | 		</tr>
 73 | 			<tr id="schema-author_uri">
 74 | 			<td>
 75 | 				<code>author_uri</code>
 76 | 			</td>
 77 | 			<td>
 78 | 				<p>Plugin author&#039;s website address.</p>
 79 | 				<p class="type">
 80 | 					JSON data type: string,
 81 | 											Format: uri
 82 | 									</p>
 83 | 									<p class="read-only">Read only</p>
 84 | 								<p class="context">Context: <code>view</code>, <code>edit</code></p>
 85 | 							</td>
 86 | 		</tr>
 87 | 			<tr id="schema-description">
 88 | 			<td>
 89 | 				<code>description</code>
 90 | 			</td>
 91 | 			<td>
 92 | 				<p>The plugin description.</p>
 93 | 				<p class="type">
 94 | 					JSON data type: object				</p>
 95 | 									<p class="read-only">Read only</p>
 96 | 								<p class="context">Context: <code>view</code>, <code>edit</code></p>
 97 | 							</td>
 98 | 		</tr>
 99 | 			<tr id="schema-version">
100 | 			<td>
101 | 				<code>version</code>
102 | 			</td>
103 | 			<td>
104 | 				<p>The plugin version number.</p>
105 | 				<p class="type">
106 | 					JSON data type: string				</p>
107 | 									<p class="read-only">Read only</p>
108 | 								<p class="context">Context: <code>view</code>, <code>edit</code></p>
109 | 							</td>
110 | 		</tr>
111 | 			<tr id="schema-network_only">
112 | 			<td>
113 | 				<code>network_only</code>
114 | 			</td>
115 | 			<td>
116 | 				<p>Whether the plugin can only be activated network-wide.</p>
117 | 				<p class="type">
118 | 					JSON data type: boolean				</p>
119 | 									<p class="read-only">Read only</p>
120 | 								<p class="context">Context: <code>view</code>, <code>edit</code>, <code>embed</code></p>
121 | 							</td>
122 | 		</tr>
123 | 			<tr id="schema-requires_wp">
124 | 			<td>
125 | 				<code>requires_wp</code>
126 | 			</td>
127 | 			<td>
128 | 				<p>Minimum required version of WordPress.</p>
129 | 				<p class="type">
130 | 					JSON data type: string				</p>
131 | 									<p class="read-only">Read only</p>
132 | 								<p class="context">Context: <code>view</code>, <code>edit</code>, <code>embed</code></p>
133 | 							</td>
134 | 		</tr>
135 | 			<tr id="schema-requires_php">
136 | 			<td>
137 | 				<code>requires_php</code>
138 | 			</td>
139 | 			<td>
140 | 				<p>Minimum required version of PHP.</p>
141 | 				<p class="type">
142 | 					JSON data type: string				</p>
143 | 									<p class="read-only">Read only</p>
144 | 								<p class="context">Context: <code>view</code>, <code>edit</code>, <code>embed</code></p>
145 | 							</td>
146 | 		</tr>
147 | 			<tr id="schema-textdomain">
148 | 			<td>
149 | 				<code>textdomain</code>
150 | 			</td>
151 | 			<td>
152 | 				<p>The plugin&#039;s text domain.</p>
153 | 				<p class="type">
154 | 					JSON data type: string				</p>
155 | 									<p class="read-only">Read only</p>
156 | 								<p class="context">Context: <code>view</code>, <code>edit</code></p>
157 | 							</td>
158 | 		</tr>
159 | 	</table>
160 | 
161 | 	</div>
162 | </section>
163 | 
164 | <div><section class="route">
165 | 	<div class="primary">
166 | 		<h2>Retrieve a Plugin</h2>
167 | 
168 | 		<h3>Definition & Example Request</h3>
169 | 
170 | 		<code>GET /wp/v2/plugins</code>
171 | 
172 | 		<p>Query this endpoint to retrieve a specific plugin record.</p>
173 | 
174 | 		<code>$ curl https://example.com/wp-json/wp/v2/plugins</code>
175 | 	</div>
176 | 	<div class="secondary">
177 | 			<h3>Arguments</h3>
178 | 	<table class="arguments">
179 | 					<tr>
180 | 				<td>
181 | 											<code>context</code><br />
182 | 									</td>
183 | 				<td>
184 | 											<p>Scope under which the request is made; determines fields present in response.</p>
185 | 																					<p class="default">
186 | 							Default: <code>view</code>
187 | 						</p>
188 | 																<p>One of: <code>view</code>, <code>embed</code>, <code>edit</code></p>
189 | 									</td>
190 | 			</tr>
191 | 					<tr>
192 | 				<td>
193 | 											<code>search</code><br />
194 | 									</td>
195 | 				<td>
196 | 											<p>Limit results to those matching a string.</p>
197 | 																								</td>
198 | 			</tr>
199 | 					<tr>
200 | 				<td>
201 | 											<code>status</code><br />
202 | 									</td>
203 | 				<td>
204 | 											<p>Limits results to plugins with the given status.</p>
205 | 																								</td>
206 | 			</tr>
207 | 			</table>
208 | 
209 | 	</div>
210 | </section>
211 | <section class="route">
212 | 	<div class="primary">
213 | 		<h2>Create a Plugin</h2>
214 | 			<h3>Arguments</h3>
215 | 	<table class="arguments">
216 | 					<tr>
217 | 				<td>
218 | 											<code><a href="#schema-slug">slug</a></code><br />
219 | 									</td>
220 | 				<td>
221 | 											<p>WordPress.org plugin directory slug.</p>
222 | 																<p class="required">
223 | 							Required: 1
224 | 						</p>
225 | 																			</td>
226 | 			</tr>
227 | 					<tr>
228 | 				<td>
229 | 											<code><a href="#schema-status">status</a></code><br />
230 | 									</td>
231 | 				<td>
232 | 											<p>The plugin activation status.</p>
233 | 																					<p class="default">
234 | 							Default: <code>inactive</code>
235 | 						</p>
236 | 																<p>One of: <code>inactive</code>, <code>active</code></p>
237 | 									</td>
238 | 			</tr>
239 | 			</table>
240 | 
241 | 	</div>
242 | 	<div class="secondary">
243 | 		<h3>Definition</h3>
244 | 
245 | 		<code>POST /wp/v2/plugins</code>
246 | 	</div>
247 | </section>
248 | <section class="route">
249 | 	<div class="primary">
250 | 		<h2>Retrieve a Plugin</h2>
251 | 
252 | 		<h3>Definition & Example Request</h3>
253 | 
254 | 		<code>GET /wp/v2/plugins/&lt;plugin&gt;?)</code>
255 | 
256 | 		<p>Query this endpoint to retrieve a specific plugin record.</p>
257 | 
258 | 		<code>$ curl https://example.com/wp-json/wp/v2/plugins/&lt;plugin&gt;?)</code>
259 | 	</div>
260 | 	<div class="secondary">
261 | 			<h3>Arguments</h3>
262 | 	<table class="arguments">
263 | 					<tr>
264 | 				<td>
265 | 											<code>context</code><br />
266 | 									</td>
267 | 				<td>
268 | 											<p>Scope under which the request is made; determines fields present in response.</p>
269 | 																					<p class="default">
270 | 							Default: <code>view</code>
271 | 						</p>
272 | 																<p>One of: <code>view</code>, <code>embed</code>, <code>edit</code></p>
273 | 									</td>
274 | 			</tr>
275 | 					<tr>
276 | 				<td>
277 | 											<code>plugin</code><br />
278 | 									</td>
279 | 				<td>
280 | 																								</td>
281 | 			</tr>
282 | 			</table>
283 | 
284 | 	</div>
285 | </section>
286 | <section class="route">
287 | 	<div class="primary">
288 | 		<h2>Update a Plugin</h2>
289 | 			<h3>Arguments</h3>
290 | 	<table class="arguments">
291 | 					<tr>
292 | 				<td>
293 | 											<code><a href="#schema-context">context</a></code><br />
294 | 									</td>
295 | 				<td>
296 | 											<p>Scope under which the request is made; determines fields present in response.</p>
297 | 																					<p class="default">
298 | 							Default: <code>view</code>
299 | 						</p>
300 | 																<p>One of: <code>view</code>, <code>embed</code>, <code>edit</code></p>
301 | 									</td>
302 | 			</tr>
303 | 					<tr>
304 | 				<td>
305 | 											<code><a href="#schema-plugin">plugin</a></code><br />
306 | 									</td>
307 | 				<td>
308 | 																								</td>
309 | 			</tr>
310 | 					<tr>
311 | 				<td>
312 | 											<code><a href="#schema-status">status</a></code><br />
313 | 									</td>
314 | 				<td>
315 | 											<p>The plugin activation status.</p>
316 | 																										<p>One of: <code>inactive</code>, <code>active</code></p>
317 | 									</td>
318 | 			</tr>
319 | 			</table>
320 | 
321 | 	</div>
322 | 	<div class="secondary">
323 | 		<h3>Definition</h3>
324 | 
325 | 		<code>POST /wp/v2/plugins/&lt;plugin&gt;?)</code>
326 | 
327 | 		<h3>Example Request</h3>
328 | 
329 | 		<code></code>
330 | 	</div>
331 | </section>
332 | <section class="route">
333 | 	<div class="primary">
334 | 		<h2>Delete a Plugin</h2>
335 | 			<h3>Arguments</h3>
336 | 	<table class="arguments">
337 | 					<tr>
338 | 				<td>
339 | 											<code>context</code><br />
340 | 									</td>
341 | 				<td>
342 | 											<p>Scope under which the request is made; determines fields present in response.</p>
343 | 																					<p class="default">
344 | 							Default: <code>view</code>
345 | 						</p>
346 | 																<p>One of: <code>view</code>, <code>embed</code>, <code>edit</code></p>
347 | 									</td>
348 | 			</tr>
349 | 					<tr>
350 | 				<td>
351 | 											<code>plugin</code><br />
352 | 									</td>
353 | 				<td>
354 | 																								</td>
355 | 			</tr>
356 | 			</table>
357 | 
358 | 	</div>
359 | 	<div class="secondary">
360 | 		<h3>Definition</h3>
361 | 
362 | 		<code>DELETE /wp/v2/plugins/&lt;plugin&gt;?)</code>
363 | 
364 | 		<h3>Example Request</h3>
365 | 
366 | 		<code>$ curl -X DELETE https://example.com/wp-json/wp/v2/plugins/&lt;plugin&gt;?)</code>
367 | 	</div>
368 | </section>
369 | </div>
370 | 


--------------------------------------------------------------------------------
/reference/nav_menu_item-revisions.md:
--------------------------------------------------------------------------------
  1 | ---
  2 | ---
  3 | 
  4 | # Nav_Menu_Item Revisions
  5 | 
  6 | <section class="route">
  7 | 	<div class="primary">
  8 | 		<h2>Schema</h2>
  9 | <p>The schema defines all the fields that exist within a nav_menu_item revision record. Any response from these endpoints can be expected to contain the fields below unless the `_filter` query parameter is used or the schema field only appears in a specific context.</p>
 10 | <table class="attributes">
 11 | 			<tr id="schema-author">
 12 | 			<td>
 13 | 				<code>author</code>
 14 | 			</td>
 15 | 			<td>
 16 | 				<p>The ID for the author of the revision.</p>
 17 | 				<p class="type">
 18 | 					JSON data type: integer				</p>
 19 | 								<p class="context">Context: <code>view</code>, <code>edit</code>, <code>embed</code></p>
 20 | 							</td>
 21 | 		</tr>
 22 | 			<tr id="schema-date">
 23 | 			<td>
 24 | 				<code>date</code>
 25 | 			</td>
 26 | 			<td>
 27 | 				<p>The date the revision was published, in the site&#039;s timezone.</p>
 28 | 				<p class="type">
 29 | 					JSON data type: string,
 30 | 											Format: datetime (<a href="https://core.trac.wordpress.org/ticket/41032">details</a>)
 31 | 									</p>
 32 | 								<p class="context">Context: <code>view</code>, <code>edit</code>, <code>embed</code></p>
 33 | 							</td>
 34 | 		</tr>
 35 | 			<tr id="schema-date_gmt">
 36 | 			<td>
 37 | 				<code>date_gmt</code>
 38 | 			</td>
 39 | 			<td>
 40 | 				<p>The date the revision was published, as GMT.</p>
 41 | 				<p class="type">
 42 | 					JSON data type: string,
 43 | 											Format: datetime (<a href="https://core.trac.wordpress.org/ticket/41032">details</a>)
 44 | 									</p>
 45 | 								<p class="context">Context: <code>view</code>, <code>edit</code></p>
 46 | 							</td>
 47 | 		</tr>
 48 | 			<tr id="schema-guid">
 49 | 			<td>
 50 | 				<code>guid</code>
 51 | 			</td>
 52 | 			<td>
 53 | 				<p>GUID for the revision, as it exists in the database.</p>
 54 | 				<p class="type">
 55 | 					JSON data type: string				</p>
 56 | 								<p class="context">Context: <code>view</code>, <code>edit</code></p>
 57 | 							</td>
 58 | 		</tr>
 59 | 			<tr id="schema-id">
 60 | 			<td>
 61 | 				<code>id</code>
 62 | 			</td>
 63 | 			<td>
 64 | 				<p>Unique identifier for the revision.</p>
 65 | 				<p class="type">
 66 | 					JSON data type: integer				</p>
 67 | 								<p class="context">Context: <code>view</code>, <code>edit</code>, <code>embed</code></p>
 68 | 							</td>
 69 | 		</tr>
 70 | 			<tr id="schema-modified">
 71 | 			<td>
 72 | 				<code>modified</code>
 73 | 			</td>
 74 | 			<td>
 75 | 				<p>The date the revision was last modified, in the site&#039;s timezone.</p>
 76 | 				<p class="type">
 77 | 					JSON data type: string,
 78 | 											Format: datetime (<a href="https://core.trac.wordpress.org/ticket/41032">details</a>)
 79 | 									</p>
 80 | 								<p class="context">Context: <code>view</code>, <code>edit</code></p>
 81 | 							</td>
 82 | 		</tr>
 83 | 			<tr id="schema-modified_gmt">
 84 | 			<td>
 85 | 				<code>modified_gmt</code>
 86 | 			</td>
 87 | 			<td>
 88 | 				<p>The date the revision was last modified, as GMT.</p>
 89 | 				<p class="type">
 90 | 					JSON data type: string,
 91 | 											Format: datetime (<a href="https://core.trac.wordpress.org/ticket/41032">details</a>)
 92 | 									</p>
 93 | 								<p class="context">Context: <code>view</code>, <code>edit</code></p>
 94 | 							</td>
 95 | 		</tr>
 96 | 			<tr id="schema-parent">
 97 | 			<td>
 98 | 				<code>parent</code>
 99 | 			</td>
100 | 			<td>
101 | 				<p>The ID for the parent of the revision.</p>
102 | 				<p class="type">
103 | 					JSON data type: integer				</p>
104 | 								<p class="context">Context: <code>view</code>, <code>edit</code>, <code>embed</code></p>
105 | 							</td>
106 | 		</tr>
107 | 			<tr id="schema-slug">
108 | 			<td>
109 | 				<code>slug</code>
110 | 			</td>
111 | 			<td>
112 | 				<p>An alphanumeric identifier for the revision unique to its type.</p>
113 | 				<p class="type">
114 | 					JSON data type: string				</p>
115 | 								<p class="context">Context: <code>view</code>, <code>edit</code>, <code>embed</code></p>
116 | 							</td>
117 | 		</tr>
118 | 			<tr id="schema-title">
119 | 			<td>
120 | 				<code>title</code>
121 | 			</td>
122 | 			<td>
123 | 				<p>The title for the object.</p>
124 | 				<p class="type">
125 | 					JSON data type: string or object				</p>
126 | 								<p class="context">Context: <code>view</code>, <code>edit</code>, <code>embed</code></p>
127 | 							</td>
128 | 		</tr>
129 | 			<tr id="schema-preview_link">
130 | 			<td>
131 | 				<code>preview_link</code>
132 | 			</td>
133 | 			<td>
134 | 				<p>Preview link for the post.</p>
135 | 				<p class="type">
136 | 					JSON data type: string,
137 | 											Format: uri
138 | 									</p>
139 | 									<p class="read-only">Read only</p>
140 | 								<p class="context">Context: <code>edit</code></p>
141 | 							</td>
142 | 		</tr>
143 | 	</table>
144 | 
145 | 	</div>
146 | </section>
147 | 
148 | <div><section class="route">
149 | 	<div class="primary">
150 | 		<h2>Retrieve a Nav_Menu_Item Revision</h2>
151 | 
152 | 		<h3>Definition & Example Request</h3>
153 | 
154 | 		<code>GET /wp/v2/menu-items/&lt;id&gt;/autosaves</code>
155 | 
156 | 		<p>Query this endpoint to retrieve a specific nav_menu_item revision record.</p>
157 | 
158 | 		<code>$ curl https://example.com/wp-json/wp/v2/menu-items/&lt;id&gt;/autosaves</code>
159 | 	</div>
160 | 	<div class="secondary">
161 | 			<h3>Arguments</h3>
162 | 	<table class="arguments">
163 | 					<tr>
164 | 				<td>
165 | 											<code>parent</code><br />
166 | 									</td>
167 | 				<td>
168 | 											<p>The ID for the parent of the autosave.</p>
169 | 																								</td>
170 | 			</tr>
171 | 					<tr>
172 | 				<td>
173 | 											<code>context</code><br />
174 | 									</td>
175 | 				<td>
176 | 											<p>Scope under which the request is made; determines fields present in response.</p>
177 | 																					<p class="default">
178 | 							Default: <code>view</code>
179 | 						</p>
180 | 																<p>One of: <code>view</code>, <code>embed</code>, <code>edit</code></p>
181 | 									</td>
182 | 			</tr>
183 | 			</table>
184 | 
185 | 	</div>
186 | </section>
187 | <section class="route">
188 | 	<div class="primary">
189 | 		<h2>Create a Nav_Menu_Item Revision</h2>
190 | 			<h3>Arguments</h3>
191 | 	<table class="arguments">
192 | 					<tr>
193 | 				<td>
194 | 											<code><a href="#schema-parent">parent</a></code><br />
195 | 									</td>
196 | 				<td>
197 | 											<p>The ID for the parent of the object.</p>
198 | 																								</td>
199 | 			</tr>
200 | 					<tr>
201 | 				<td>
202 | 											<code><a href="#schema-title">title</a></code><br />
203 | 									</td>
204 | 				<td>
205 | 											<p>The title for the object.</p>
206 | 																								</td>
207 | 			</tr>
208 | 					<tr>
209 | 				<td>
210 | 											<code><a href="#schema-type">type</a></code><br />
211 | 									</td>
212 | 				<td>
213 | 											<p>The family of objects originally represented, such as &quot;post_type&quot; or &quot;taxonomy&quot;.</p>
214 | 																										<p>One of: <code>taxonomy</code>, <code>post_type</code>, <code>post_type_archive</code>, <code>custom</code></p>
215 | 									</td>
216 | 			</tr>
217 | 					<tr>
218 | 				<td>
219 | 											<code><a href="#schema-status">status</a></code><br />
220 | 									</td>
221 | 				<td>
222 | 											<p>A named status for the object.</p>
223 | 																										<p>One of: <code>publish</code>, <code>future</code>, <code>draft</code>, <code>pending</code>, <code>private</code></p>
224 | 									</td>
225 | 			</tr>
226 | 					<tr>
227 | 				<td>
228 | 											<code><a href="#schema-attr_title">attr_title</a></code><br />
229 | 									</td>
230 | 				<td>
231 | 											<p>Text for the title attribute of the link element for this menu item.</p>
232 | 																								</td>
233 | 			</tr>
234 | 					<tr>
235 | 				<td>
236 | 											<code><a href="#schema-classes">classes</a></code><br />
237 | 									</td>
238 | 				<td>
239 | 											<p>Class names for the link element of this menu item.</p>
240 | 																								</td>
241 | 			</tr>
242 | 					<tr>
243 | 				<td>
244 | 											<code><a href="#schema-description">description</a></code><br />
245 | 									</td>
246 | 				<td>
247 | 											<p>The description of this menu item.</p>
248 | 																								</td>
249 | 			</tr>
250 | 					<tr>
251 | 				<td>
252 | 											<code><a href="#schema-menu_order">menu_order</a></code><br />
253 | 									</td>
254 | 				<td>
255 | 											<p>The DB ID of the nav_menu_item that is this item&#039;s menu parent, if any, otherwise 0.</p>
256 | 																								</td>
257 | 			</tr>
258 | 					<tr>
259 | 				<td>
260 | 											<code><a href="#schema-object">object</a></code><br />
261 | 									</td>
262 | 				<td>
263 | 											<p>The type of object originally represented, such as &quot;category&quot;, &quot;post&quot;, or &quot;attachment&quot;.</p>
264 | 																								</td>
265 | 			</tr>
266 | 					<tr>
267 | 				<td>
268 | 											<code><a href="#schema-object_id">object_id</a></code><br />
269 | 									</td>
270 | 				<td>
271 | 											<p>The database ID of the original object this menu item represents, for example the ID for posts or the term_id for categories.</p>
272 | 																								</td>
273 | 			</tr>
274 | 					<tr>
275 | 				<td>
276 | 											<code><a href="#schema-target">target</a></code><br />
277 | 									</td>
278 | 				<td>
279 | 											<p>The target attribute of the link element for this menu item.</p>
280 | 																										<p>One of: <code>_blank</code>, <code></code></p>
281 | 									</td>
282 | 			</tr>
283 | 					<tr>
284 | 				<td>
285 | 											<code><a href="#schema-url">url</a></code><br />
286 | 									</td>
287 | 				<td>
288 | 											<p>The URL to which this menu item points.</p>
289 | 																								</td>
290 | 			</tr>
291 | 					<tr>
292 | 				<td>
293 | 											<code><a href="#schema-xfn">xfn</a></code><br />
294 | 									</td>
295 | 				<td>
296 | 											<p>The XFN relationship expressed in the link of this menu item.</p>
297 | 																								</td>
298 | 			</tr>
299 | 					<tr>
300 | 				<td>
301 | 											<code><a href="#schema-menus">menus</a></code><br />
302 | 									</td>
303 | 				<td>
304 | 											<p>The terms assigned to the object in the nav_menu taxonomy.</p>
305 | 																								</td>
306 | 			</tr>
307 | 					<tr>
308 | 				<td>
309 | 											<code><a href="#schema-meta">meta</a></code><br />
310 | 									</td>
311 | 				<td>
312 | 											<p>Meta fields.</p>
313 | 																								</td>
314 | 			</tr>
315 | 			</table>
316 | 
317 | 	</div>
318 | 	<div class="secondary">
319 | 		<h3>Definition</h3>
320 | 
321 | 		<code>POST /wp/v2/menu-items/&lt;id&gt;/autosaves</code>
322 | 	</div>
323 | </section>
324 | <section class="route">
325 | 	<div class="primary">
326 | 		<h2>Retrieve a Nav_Menu_Item Revision</h2>
327 | 
328 | 		<h3>Definition & Example Request</h3>
329 | 
330 | 		<code>GET /wp/v2/menu-items/&lt;parent&gt;/autosaves/&lt;id&gt;</code>
331 | 
332 | 		<p>Query this endpoint to retrieve a specific nav_menu_item revision record.</p>
333 | 
334 | 		<code>$ curl https://example.com/wp-json/wp/v2/menu-items/&lt;parent&gt;/autosaves/&lt;id&gt;</code>
335 | 	</div>
336 | 	<div class="secondary">
337 | 			<h3>Arguments</h3>
338 | 	<table class="arguments">
339 | 					<tr>
340 | 				<td>
341 | 											<code>parent</code><br />
342 | 									</td>
343 | 				<td>
344 | 											<p>The ID for the parent of the autosave.</p>
345 | 																								</td>
346 | 			</tr>
347 | 					<tr>
348 | 				<td>
349 | 											<code>id</code><br />
350 | 									</td>
351 | 				<td>
352 | 											<p>The ID for the autosave.</p>
353 | 																								</td>
354 | 			</tr>
355 | 					<tr>
356 | 				<td>
357 | 											<code>context</code><br />
358 | 									</td>
359 | 				<td>
360 | 											<p>Scope under which the request is made; determines fields present in response.</p>
361 | 																					<p class="default">
362 | 							Default: <code>view</code>
363 | 						</p>
364 | 																<p>One of: <code>view</code>, <code>embed</code>, <code>edit</code></p>
365 | 									</td>
366 | 			</tr>
367 | 			</table>
368 | 
369 | 	</div>
370 | </section>
371 | </div>
372 | 


--------------------------------------------------------------------------------