Completed
Push — add/https-heartbeat ( 21cfb7...3b8753 )
by
unknown
15:45
created

json-endpoints.php (10 issues)

Upgrade to new PHP Analysis Engine

These results are based on our legacy PHP analysis, consider migrating to our new PHP analysis engine instead. Learn more

1
<?php
2
3
/*
4
 * Endpoint class definitions. Only instantiations should be in this file
5
 *   file ordering matters
6
 */
7
8
$json_endpoints_dir = dirname( __FILE__ ) . '/json-endpoints/';
9
10
//abstract endpoints
11
require_once( $json_endpoints_dir . 'class.wpcom-json-api-post-endpoint.php' );
12
require_once( $json_endpoints_dir . 'class.wpcom-json-api-post-v1-1-endpoint.php' ); // v1.1
13
require_once( $json_endpoints_dir . 'class.wpcom-json-api-comment-endpoint.php' );
14
require_once( $json_endpoints_dir . 'class.wpcom-json-api-taxonomy-endpoint.php' );
15
16
17
// **********
18
// v1
19
// **********
20
21
require_once( $json_endpoints_dir . 'class.wpcom-json-api-delete-media-endpoint.php' );
22
require_once( $json_endpoints_dir . 'class.wpcom-json-api-get-comment-endpoint.php' );
23
require_once( $json_endpoints_dir . 'class.wpcom-json-api-get-media-endpoint.php' );
24
require_once( $json_endpoints_dir . 'class.wpcom-json-api-get-post-endpoint.php' );
25
require_once( $json_endpoints_dir . 'class.wpcom-json-api-render-endpoint.php' );
26
require_once( $json_endpoints_dir . 'class.wpcom-json-api-render-shortcode-endpoint.php' );
27
require_once( $json_endpoints_dir . 'class.wpcom-json-api-list-shortcodes-endpoint.php' );
28
require_once( $json_endpoints_dir . 'class.wpcom-json-api-render-embed-reversal-endpoint.php' );
29
require_once( $json_endpoints_dir . 'class.wpcom-json-api-render-embed-endpoint.php' );
30
require_once( $json_endpoints_dir . 'class.wpcom-json-api-list-embeds-endpoint.php' );
31
require_once( $json_endpoints_dir . 'class.wpcom-json-api-get-site-endpoint.php' );
32
require_once( $json_endpoints_dir . 'class.wpcom-json-api-get-taxonomies-endpoint.php' );
33
require_once( $json_endpoints_dir . 'class.wpcom-json-api-get-taxonomy-endpoint.php' );
34
require_once( $json_endpoints_dir . 'class.wpcom-json-api-list-comments-endpoint.php' );
35
require_once( $json_endpoints_dir . 'class.wpcom-json-api-list-media-endpoint.php' );
36
require_once( $json_endpoints_dir . 'class.wpcom-json-api-list-posts-endpoint.php' );
37
require_once( $json_endpoints_dir . 'class.wpcom-json-api-list-roles-endpoint.php' );
38
require_once( $json_endpoints_dir . 'class.wpcom-json-api-list-users-endpoint.php' );
39
require_once( $json_endpoints_dir . 'class.wpcom-json-api-site-user-endpoint.php' );
40
require_once( $json_endpoints_dir . 'class.wpcom-json-api-update-comment-endpoint.php' );
41
require_once( $json_endpoints_dir . 'class.wpcom-json-api-update-media-endpoint.php' );
42
require_once( $json_endpoints_dir . 'class.wpcom-json-api-update-post-endpoint.php' );
43
require_once( $json_endpoints_dir . 'class.wpcom-json-api-update-user-endpoint.php' );
44
require_once( $json_endpoints_dir . 'class.wpcom-json-api-update-taxonomy-endpoint.php' );
45
require_once( $json_endpoints_dir . 'class.wpcom-json-api-update-user-endpoint.php' );
46
require_once( $json_endpoints_dir . 'class.wpcom-json-api-upload-media-endpoint.php' );
47
require_once( $json_endpoints_dir . 'class.wpcom-json-api-site-settings-endpoint.php' );
48
require_once( $json_endpoints_dir . 'class.wpcom-json-api-publicize-endpoint.php' );
49
require_once( $json_endpoints_dir . 'class.wpcom-json-api-sharing-buttons-endpoint.php' );
50
51
// **********
52
// v1.1
53
// **********
54
55
// Media
56
require_once( $json_endpoints_dir . 'class.wpcom-json-api-delete-media-v1-1-endpoint.php' );
57
require_once( $json_endpoints_dir . 'class.wpcom-json-api-get-media-v1-1-endpoint.php' );
58
require_once( $json_endpoints_dir . 'class.wpcom-json-api-list-media-v1-1-endpoint.php' );
59
require_once( $json_endpoints_dir . 'class.wpcom-json-api-update-media-v1-1-endpoint.php' );
60
require_once( $json_endpoints_dir . 'class.wpcom-json-api-upload-media-v1-1-endpoint.php' );
61
62
// Posts
63
require_once( $json_endpoints_dir . 'class.wpcom-json-api-get-post-v1-1-endpoint.php' );
64
require_once( $json_endpoints_dir . 'class.wpcom-json-api-list-posts-v1-1-endpoint.php' );
65
require_once( $json_endpoints_dir . 'class.wpcom-json-api-update-post-v1-1-endpoint.php' );
66
require_once( $json_endpoints_dir . 'class.wpcom-json-api-get-autosave-v1-1-endpoint.php' );
67
require_once( $json_endpoints_dir . 'class.wpcom-json-api-autosave-post-v1-1-endpoint.php' );
68
require_once( $json_endpoints_dir . 'class.wpcom-json-api-get-post-counts-v1-1-endpoint.php' );
69
70
// Custom Menus
71
require_once( $json_endpoints_dir . 'class.wpcom-json-api-menus-v1-1-endpoint.php' );
72
73
// Users
74
require_once( $json_endpoints_dir . 'class.wpcom-json-api-list-invites-endpoint.php' );
75
require_once( $json_endpoints_dir . 'class.wpcom-json-api-update-invites-endpoint.php' );
76
77
// Custom CSS
78
require_once( $json_endpoints_dir . 'class.wpcom-json-api-get-customcss.php' );
79
require_once( $json_endpoints_dir . 'class.wpcom-json-api-update-customcss.php' );
80
81
// **********
82
// v1.2
83
// **********
84
require_once( $json_endpoints_dir . 'class.wpcom-json-api-update-post-v1-2-endpoint.php' );
85
86
// Jetpack Only Endpoints
87
$json_jetpack_endpoints_dir = dirname( __FILE__ ) . '/json-endpoints/jetpack/';
88
89
// This files instantiates the endpoints
90
require_once( $json_jetpack_endpoints_dir . 'json-api-jetpack-endpoints.php' );
91
92
/*
93
 * Endpoint instantiations
94
 */
95
96
new WPCOM_JSON_API_GET_Site_Endpoint( array(
97
	'description' => 'Get information about a site.',
98
	'group'	      => 'sites',
99
	'stat'        => 'sites:X',
100
	'allowed_if_flagged' => true,
101
	'method'      => 'GET',
102
	'path'        => '/sites/%s',
103
	'path_labels' => array(
104
		'$site' => '(int|string) Site ID or domain',
105
	),
106
107
	'query_parameters' => array(
108
		'context' => false,
109
	),
110
111
	'response_format' => WPCOM_JSON_API_GET_Site_Endpoint::$site_format,
112
113
	'example_request' => 'https://public-api.wordpress.com/rest/v1/sites/en.blog.wordpress.com/',
114
) );
115
116
new WPCOM_JSON_API_GET_Post_Counts_V1_1_Endpoint( array(
117
	'description'   => 'Get number of posts in the post type groups by post status',
118
	'group'         => '__do_not_document',
119
	'stat'          => 'sites:X:post-counts:X',
120
	'force'         => 'wpcom',
121
	'method'        => 'GET',
122
	'min_version'   => '1.1',
123
	'max_version'   => '1.2',
124
	'path'          => '/sites/%s/post-counts/%s',
125
	'path_labels'   => array(
126
		'$site'       => '(int|string) Site ID or domain',
127
		'$post_type'  => '(string) Post Type',
128
	),
129
130
	'query_parameters' => array(
131
		'context' => false,
132
		'author' => '(int) author ID',
133
	),
134
135
	'example_request' => 'https://public-api.wordpress.com/rest/v1.2/sites/en.blog.wordpress.com/post-counts/page',
136
137
	'response_format' => array(
138
		'counts' => array(
139
			'all' => '(array) Number of posts by any author in the post type grouped by post status',
140
			'mine' => '(array) Number of posts by the current user in the post type grouped by post status'
141
		)
142
	)
143
) );
144
145
146
new WPCOM_JSON_API_List_Post_Formats_Endpoint( array(
147
	'description' => 'Get a list of post formats supported by a site.',
148
	'group'       => '__do_not_document',
149
	'stat'        => 'sites:X:post-formats',
150
151
	'method'      => 'GET',
152
	'path'        => '/sites/%s/post-formats',
153
	'path_labels' => array(
154
		'$site' => '(int|string) Site ID or domain',
155
	),
156
157
	'query_parameters' => array(
158
		'context' => false,
159
	),
160
161
	'response_format' => array(
162
		'formats' => '(array) A list of supported post formats. id => label.',
163
	)
164
) );
165
166
new WPCOM_JSON_API_List_Page_Templates_Endpoint( array(
167
	'description' => 'Get a list of page templates supported by a site.',
168
	'group'       => 'sites',
169
	'stat'        => 'sites:X:post-templates',
170
171
	'method'      => 'GET',
172
	'path'        => '/sites/%s/page-templates',
173
	'path_labels' => array(
174
		'$site' => '(int|string) Site ID or domain',
175
	),
176
	'query_parameters' => array(
177
		'context' => false,
178
	),
179
	'response_format' => array(
180
		'templates' => '(array) A list of supported page templates. Contains label and file.',
181
	)
182
) );
183
184
new WPCOM_JSON_API_List_Post_Types_Endpoint( array (
185
	'description' => 'Get a list of post types available for a site.',
186
	'group'       => '__do_not_document',
187
	'stat'        => 'sites:X:post-types',
188
189
	'method'      => 'GET',
190
	'path'        => '/sites/%s/post-types',
191
	'path_labels' => array(
192
		'$site' => '(int|string) Site ID or domain',
193
	),
194
195
	'query_parameters' => array(
196
		'api_queryable' => '(bool) If true, only queryable post types are returned',
197
	),
198
199
	'response_format' => array(
200
		'found'      => '(int) The number of post types found',
201
		'post_types' => '(array) A list of available post types',
202
	)
203
) );
204
205
/*
206
 * Shortcode endpoints
207
 */
208
209
new WPCOM_JSON_API_List_Shortcodes_Endpoint( array(
210
	'description' => "Get a list of shortcodes available on a site. Note: The current user must have publishing access.",
211
	'group'       => 'sites',
212
	'stat'        => 'shortcodes',
213
	'method'      => 'GET',
214
	'path'        => '/sites/%s/shortcodes',
215
	'path_labels' => array(
216
		'$site'    => '(int|string) Site ID or domain',
217
	),
218
	'response_format' => array(
219
		'shortcodes' => '(array) A list of supported shortcodes by their handle.',
220
	),
221
	'example_request' => 'https://public-api.wordpress.com/rest/v1/sites/82974409/shortcodes',
222
	'example_request_data' => array(
223
		'headers' => array(
224
			'authorization' => 'Bearer YOUR_API_TOKEN'
225
		),
226
	)
227
) );
228
229
new WPCOM_JSON_API_Render_Shortcode_Endpoint( array(
230
	'description' => "Get a rendered shortcode for a site. Note: The current user must have publishing access.",
231
	'group'       => 'sites',
232
	'stat'        => 'shortcodes:render',
233
	'method'      => 'GET',
234
	'path'        => '/sites/%s/shortcodes/render',
235
	'path_labels' => array(
236
		'$site'    => '(int|string) Site ID or domain',
237
	),
238
	'query_parameters' => array(
239
		'shortcode'     => '(string) The query-string encoded shortcode string to render. Required. Only accepts one at a time.',
240
	),
241
	'response_format' => array(
242
		'shortcode' => '(string) The shortcode that was passed in for rendering.',
243
		'result'    => '(html) The rendered HTML result of the shortcode.',
244
		'scripts'   => '(array) An array of JavaScript files needed to render the shortcode. Returned in the format of <code>{ "script-slug" : { "src": "http://example.com/file.js", "extra" : "" } }</code> where extra contains any neccessary extra JS for initializing the source file and src contains the script to load. Omitted if no scripts are neccessary.',
245
		'styles'    => '(array) An array of CSS files needed to render the shortcode. Returned in the format of <code>{ "style-slug" : { "src": "http://example.com/file.css", "media" : "all" } }</code>. Omitted if no styles are neccessary.',
246
	),
247
	'example_request' => 'https://public-api.wordpress.com/rest/v1/sites/82974409/shortcodes/render?shortcode=%5Bgallery%20ids%3D%22729%2C732%2C731%2C720%22%5D',
248
	'example_request_data' => array(
249
		'headers' => array(
250
			'authorization' => 'Bearer YOUR_API_TOKEN'
251
		),
252
	)
253
) );
254
255
/*
256
 * embed endpoints
257
 */
258
new WPCOM_JSON_API_List_Embeds_Endpoint( array(
259
	'description' => "Get a list of embeds available on a site. Note: The current user must have publishing access.",
260
	'group'       => 'sites',
261
	'stat'        => 'embeds',
262
	'method'      => 'GET',
263
	'path'        => '/sites/%s/embeds',
264
	'path_labels' => array(
265
		'$site'    => '(int|string) Site ID or domain',
266
	),
267
	'response_format' => array(
268
		'embeds' => '(array) A list of supported embeds by their regex pattern.',
269
	),
270
	'example_request' => 'https://public-api.wordpress.com/rest/v1/sites/82974409/embeds',
271
	'example_request_data' => array(
272
		'headers' => array(
273
			'authorization' => 'Bearer YOUR_API_TOKEN'
274
		),
275
	)
276
) );
277
278
new WPCOM_JSON_API_Render_Embed_Endpoint( array(
279
	'description' => "Get a rendered embed for a site. Note: The current user must have publishing access.",
280
	'group'       => 'sites',
281
	'stat'        => 'embeds:render',
282
	'method'      => 'GET',
283
	'path'        => '/sites/%s/embeds/render',
284
	'path_labels' => array(
285
		'$site'    => '(int|string) Site ID or domain',
286
	),
287
	'query_parameters' => array(
288
		'embed_url'     => '(string) The query-string encoded embed URL to render. Required. Only accepts one at a time.',
289
	),
290
	'response_format' => array(
291
		'embed_url' => '(string) The embed_url that was passed in for rendering.',
292
		'result'    => '(html) The rendered HTML result of the embed.',
293
	),
294
	'example_request' => 'https://public-api.wordpress.com/rest/v1/sites/apiexamples.wordpress.com/embeds/render?embed_url=https%3A%2F%2Fwww.youtube.com%2Fwatch%3Fv%3DSQEQr7c0-dw',
295
	'example_request_data' => array(
296
		'headers' => array(
297
			'authorization' => 'Bearer YOUR_API_TOKEN'
298
		),
299
	)
300
) );
301
302
new WPCOM_JSON_API_Render_Embed_Reversal_Endpoint( array(
303
	'description' => "Determines if the given embed code can be reversed into a single line embed or a shortcode, and if so returns the embed or shortcode. Note: The current user must have publishing access.",
304
	//'group'       => 'sites',
305
	'group'       => '__do_not_document',
306
	'stat'        => 'embeds:reversal',
307
	'method'      => 'POST',
308
	'path'        => '/sites/%s/embeds/reversal',
309
	'path_labels' => array(
310
		'$site'    => '(int|string) Site ID or domain',
311
	),
312
	'request_format' => array(
313
		'maybe_embed' => '(string) The embed code to reverse. Required. Only accepts one at a time.',
314
	),
315
	'response_format' => array(
316
		'maybe_embed' => '(string) The original embed code that was passed in for rendering.',
317
		'reversal_type' => '(string) The type of reversal. Either an embed or a shortcode.',
318
		'render_result' => '(html) The rendered HTML result of the embed or shortcode.',
319
		'result' => '(string) The reversed content. Either a single line embed or a shortcode.',
320
		'scripts'   => '(array) An array of JavaScript files needed to render the embed or shortcode. Returned in the format of <code>{ "script-slug" : { "src": "http://example.com/file.js", "extra" : "" } }</code> where extra contains any neccessary extra JS for initializing the source file and src contains the script to load. Omitted if no scripts are neccessary.',
321
		'styles'    => '(array) An array of CSS files needed to render the embed or shortcode. Returned in the format of <code>{ "style-slug" : { "src": "http://example.com/file.css", "media" : "all" } }</code>. Omitted if no styles are neccessary.',
322
	),
323
	'example_request'      => 'https://public-api.wordpress.com/rest/v1/sites/82974409/shortcode-reversals/render/',
324
	'example_request_data' => array(
325
		'headers' => array(
326
			'authorization' => 'Bearer YOUR_API_TOKEN'
327
		),
328
329
		'body' => array(
330
			'maybe_embed' => '<iframe width="480" height="302" src="http://www.ustream.tv/embed/recorded/26370522/highlight/299667?v=3&amp;wmode=direct" scrolling="no" frameborder="0"></iframe>',
331
		)
332
	),
333
) );
334
335
336
/*
337
 * Post endpoints
338
 */
339
new WPCOM_JSON_API_List_Posts_Endpoint( array(
340
	'description' => 'Get a list of matching posts.',
341
	'new_version' => '1.1',
342
	'max_version' => '1',
343
	'group'       => 'posts',
344
	'stat'        => 'posts',
345
346
	'method'      => 'GET',
347
	'path'        => '/sites/%s/posts/',
348
	'path_labels' => array(
349
		'$site' => '(int|string) Site ID or domain',
350
	),
351
352
	'query_parameters' => array(
353
		'number'   => '(int=20) The number of posts to return. Limit: 100.',
354
		'offset'   => '(int=0) 0-indexed offset.',
355
		'page'     => '(int) Return the Nth 1-indexed page of posts. Takes precedence over the <code>offset</code> parameter.',
356
		'order'    => array(
357
			'DESC' => 'Return posts in descending order. For dates, that means newest to oldest.',
358
			'ASC'  => 'Return posts in ascending order. For dates, that means oldest to newest.',
359
		),
360
		'order_by' => array(
361
			'date'          => 'Order by the created time of each post.',
362
			'modified'      => 'Order by the modified time of each post.',
363
			'title'         => "Order lexicographically by the posts' titles.",
364
			'comment_count' => 'Order by the number of comments for each post.',
365
			'ID'            => 'Order by post ID.',
366
		),
367
		'after'    => '(ISO 8601 datetime) Return posts dated on or after the specified datetime.',
368
		'before'   => '(ISO 8601 datetime) Return posts dated on or before the specified datetime.',
369
		'tag'      => '(string) Specify the tag name or slug.',
370
		'category' => '(string) Specify the category name or slug.',
371
		'type'     => "(string) Specify the post type. Defaults to 'post', use 'any' to query for both posts and pages. Post types besides post and page need to be whitelisted using the <code>rest_api_allowed_post_types</code> filter.",
372
		'parent_id' => '(int) Returns only posts which are children of the specified post. Applies only to hierarchical post types.',
373
		'exclude'  => '(array:int|int) Excludes the specified post ID(s) from the response',
374
		'exclude_tree' => '(int) Excludes the specified post and all of its descendants from the response. Applies only to hierarchical post types.',
375
		'status'   => array(
376
			'publish' => 'Return only published posts.',
377
			'private' => 'Return only private posts.',
378
			'draft'   => 'Return only draft posts.',
379
			'pending' => 'Return only posts pending editorial approval.',
380
			'future'  => 'Return only posts scheduled for future publishing.',
381
			'trash'   => 'Return only posts in the trash.',
382
			'any'     => 'Return all posts regardless of status.',
383
		),
384
		'sticky'    => array(
385
			'false'   => 'Post is not marked as sticky.',
386
			'true'    => 'Stick the post to the front page.',
387
		),
388
		'author'   => "(int) Author's user ID",
389
		'search'   => '(string) Search query',
390
		'meta_key'   => '(string) Metadata key that the post should contain',
391
		'meta_value'   => '(string) Metadata value that the post should contain. Will only be applied if a `meta_key` is also given',
392
	),
393
394
	'example_request' => 'https://public-api.wordpress.com/rest/v1/sites/en.blog.wordpress.com/posts/?number=5'
395
) );
396
397
new WPCOM_JSON_API_List_Posts_v1_1_Endpoint( array(
398
	'description' => 'Get a list of matching posts.',
399
	'min_version' => '1.1',
400
	'max_version' => '1.1',
401
402
	'group'       => 'posts',
403
	'stat'        => 'posts',
404
405
	'method'      => 'GET',
406
	'path'        => '/sites/%s/posts/',
407
	'path_labels' => array(
408
		'$site' => '(int|string) Site ID or domain',
409
	),
410
411
	'query_parameters' => array(
412
		'number'   => '(int=20) The number of posts to return. Limit: 100.',
413
		'offset'   => '(int=0) 0-indexed offset.',
414
		'page'     => '(int) Return the Nth 1-indexed page of posts. Takes precedence over the <code>offset</code> parameter.',
415
		'page_handle' => '(string) A page handle, returned from a previous API call as a <code>meta.next_page</code> property. This is the most efficient way to fetch the next page of results.',
416
		'order'    => array(
417
			'DESC' => 'Return posts in descending order. For dates, that means newest to oldest.',
418
			'ASC'  => 'Return posts in ascending order. For dates, that means oldest to newest.',
419
		),
420
		'order_by' => array(
421
			'date'          => 'Order by the created time of each post.',
422
			'modified'      => 'Order by the modified time of each post.',
423
			'title'         => "Order lexicographically by the posts' titles.",
424
			'comment_count' => 'Order by the number of comments for each post.',
425
			'ID'            => 'Order by post ID.',
426
		),
427
		'after'    => '(ISO 8601 datetime) Return posts dated after the specified datetime.',
428
		'before'   => '(ISO 8601 datetime) Return posts dated before the specified datetime.',
429
		'modified_after'    => '(ISO 8601 datetime) Return posts modified after the specified datetime.',
430
		'modified_before'   => '(ISO 8601 datetime) Return posts modified before the specified datetime.',
431
		'tag'      => '(string) Specify the tag name or slug.',
432
		'category' => '(string) Specify the category name or slug.',
433
		'type'     => "(string) Specify the post type. Defaults to 'post', use 'any' to query for both posts and pages. Post types besides post and page need to be whitelisted using the <code>rest_api_allowed_post_types</code> filter.",
434
		'parent_id' => '(int) Returns only posts which are children of the specified post. Applies only to hierarchical post types.',
435
		'exclude'  => '(array:int|int) Excludes the specified post ID(s) from the response',
436
		'exclude_tree' => '(int) Excludes the specified post and all of its descendants from the response. Applies only to hierarchical post types.',
437
		'status'   => '(string) Comma-separated list of statuses for which to query, including any of: "publish", "private", "draft", "pending", "future", and "trash", or simply "any". Defaults to "publish"',
438
		'sticky'    => array(
439
			'include'   => 'Sticky posts are not excluded from the list.',
440
			'exclude'   => 'Sticky posts are excluded from the list.',
441
			'require'   => 'Only include sticky posts',
442
		),
443
		'author'   => "(int) Author's user ID",
444
		'search'   => '(string) Search query',
445
		'meta_key'   => '(string) Metadata key that the post should contain',
446
		'meta_value'   => '(string) Metadata value that the post should contain. Will only be applied if a `meta_key` is also given',
447
	),
448
449
	'example_request' => 'https://public-api.wordpress.com/rest/v1.1/sites/en.blog.wordpress.com/posts/?number=2'
450
) );
451
452
new WPCOM_JSON_API_Get_Post_Endpoint( array(
453
	'description' => 'Get a single post (by ID).',
454
	'group'       => 'posts',
455
	'stat'        => 'posts:1',
456
	'new_version' => '1.1',
457
	'max_version' => '1',
458
	'method'      => 'GET',
459
	'path'        => '/sites/%s/posts/%d',
460
	'path_labels' => array(
461
		'$site'    => '(int|string) Site ID or domain',
462
		'$post_ID' => '(int) The post ID',
463
	),
464
465
	'example_request'  => 'https://public-api.wordpress.com/rest/v1/sites/en.blog.wordpress.com/posts/7'
466
) );
467
468
new WPCOM_JSON_API_Get_Post_v1_1_Endpoint( array(
469
	'description' => 'Get a single post (by ID).',
470
	'min_version' => '1.1',
471
	'max_version' => '1.1',
472
	'group'       => 'posts',
473
	'stat'        => 'posts:1',
474
	'method'      => 'GET',
475
	'path'        => '/sites/%s/posts/%d',
476
	'path_labels' => array(
477
		'$site'    => '(int|string) Site ID or domain',
478
		'$post_ID' => '(int) The post ID',
479
	),
480
	'example_request'  => 'https://public-api.wordpress.com/rest/v1.1/sites/en.blog.wordpress.com/posts/7'
481
) );
482
483
new WPCOM_JSON_API_Get_Post_Endpoint( array(
484
	'description' => 'Get a single post (by name)',
485
	'group'       => '__do_not_document',
486
	'stat'        => 'posts:name',
487
	'method'      => 'GET',
488
	'path'        => '/sites/%s/posts/name:%s',
489
	'path_labels' => array(
490
		'$site'      => '(int|string) Site ID or domain',
491
		'$post_name' => '(string) The post name (a.k.a. slug)',
492
	),
493
494
	'example_request' => 'https://public-api.wordpress.com/rest/v1/sites/en.blog.wordpress.com/posts/name:blogging-and-stuff?pretty=1',
495
) );
496
497
new WPCOM_JSON_API_Get_Post_Endpoint( array(
498
	'description' => 'Get a single post (by slug).',
499
	'group'       => 'posts',
500
	'stat'        => 'posts:slug',
501
	'new_version' => '1.1',
502
	'max_version' => '1',
503
	'method'      => 'GET',
504
	'path'        => '/sites/%s/posts/slug:%s',
505
	'path_labels' => array(
506
		'$site'      => '(int|string) Site ID or domain',
507
		'$post_slug' => '(string) The post slug (a.k.a. sanitized name)',
508
	),
509
510
	'example_request' => 'https://public-api.wordpress.com/rest/v1/sites/en.blog.wordpress.com/posts/slug:blogging-and-stuff',
511
) );
512
513
new WPCOM_JSON_API_Get_Post_v1_1_Endpoint( array(
514
	'description' => 'Get a single post (by slug).',
515
	'min_version' => '1.1',
516
	'max_version' => '1.1',
517
	'group'       => 'posts',
518
	'stat'        => 'posts:slug',
519
	'method'      => 'GET',
520
	'path'        => '/sites/%s/posts/slug:%s',
521
	'path_labels' => array(
522
		'$site'      => '(int|string) Site ID or domain',
523
		'$post_slug' => '(string) The post slug (a.k.a. sanitized name)',
524
	),
525
	'example_request' => 'https://public-api.wordpress.com/rest/v1.1/sites/en.blog.wordpress.com/posts/slug:blogging-and-stuff',
526
) );
527
528
new WPCOM_JSON_API_Update_Post_Endpoint( array(
529
	'description' => 'Create a post.',
530
	'group'       => 'posts',
531
	'stat'        => 'posts:new',
532
	'new_version' => '1.1',
533
	'max_version' => '1',
534
	'method'      => 'POST',
535
	'path'        => '/sites/%s/posts/new',
536
	'path_labels' => array(
537
		'$site' => '(int|string) Site ID or domain',
538
	),
539
540
	'request_format' => array(
541
		// explicitly document all input
542
		'date'      => "(ISO 8601 datetime) The post's creation time.",
543
		'title'     => '(HTML) The post title.',
544
		'content'   => '(HTML) The post content.',
545
		'excerpt'   => '(HTML) An optional post excerpt.',
546
		'slug'      => '(string) The name (slug) for the post, used in URLs.',
547
		'author'    => '(string) The username or ID for the user to assign the post to.',
548
		'publicize' => '(array|bool) True or false if the post be publicized to external services. An array of services if we only want to publicize to a select few. Defaults to true.',
549
		'publicize_message' => '(string) Custom message to be publicized to external services.',
550
		'status'    => array(
551
			'publish' => 'Publish the post.',
552
			'private' => 'Privately publish the post.',
553
			'draft'   => 'Save the post as a draft.',
554
			'pending' => 'Mark the post as pending editorial approval.',
555
			'auto-draft' => 'Save a placeholder for a newly created post, with no content.',
556
		),
557
		'sticky'    => array(
558
			'false'   => 'Post is not marked as sticky.',
559
			'true'    => 'Stick the post to the front page.',
560
		),
561
		'password'  => '(string) The plaintext password protecting the post, or, more likely, the empty string if the post is not password protected.',
562
		'parent'    => "(int) The post ID of the new post's parent.",
563
		'type'      => "(string) The post type. Defaults to 'post'. Post types besides post and page need to be whitelisted using the <code>rest_api_allowed_post_types</code> filter.",
564
		'categories' => "(array|string) Comma-separated list or array of categories (name or id)",
565
		'tags'       => "(array|string) Comma-separated list or array of tags (name or id)",
566
		'format'     => array_merge( array( 'default' => 'Use default post format' ), get_post_format_strings() ),
567
		'featured_image' => "(string) The post ID of an existing attachment to set as the featured image. Pass an empty string to delete the existing image.",
568
		'media'      => "(media) An array of files to attach to the post. To upload media, the entire request should be multipart/form-data encoded. Multiple media items will be displayed in a gallery. Accepts  jpg, jpeg, png, gif, pdf, doc, ppt, odt, pptx, docx, pps, ppsx, xls, xlsx, key. Audio and Video may also be available. See <code>allowed_file_types</code> in the options response of the site endpoint. <br /><br /><strong>Example</strong>:<br />" .
1 ignored issue
show
String concat is not required here; use a single string instead
Loading history...
569
		 				"<code>curl \<br />--form 'title=Image' \<br />--form 'media[]=@/path/to/file.jpg' \<br />-H 'Authorization: BEARER your-token' \<br />'https://public-api.wordpress.com/rest/v1/sites/123/posts/new'</code>",
570
		'media_urls' => "(array) An array of URLs for images to attach to a post. Sideloads the media in for a post.",
571
		'metadata'      => "(array) Array of metadata objects containing the following properties: `key` (metadata key), `id` (meta ID), `previous_value` (if set, the action will only occur for the provided previous value), `value` (the new value to set the meta to), `operation` (the operation to perform: `update` or `add`; defaults to `update`). All unprotected meta keys are available by default for read requests. Both unprotected and protected meta keys are avaiable for authenticated requests with proper capabilities. Protected meta keys can be made available with the <code>rest_api_allowed_public_metadata</code> filter.",
572
		'comments_open' => "(bool) Should the post be open to comments? Defaults to the blog's preference.",
573
		'pings_open'    => "(bool) Should the post be open to comments? Defaults to the blog's preference.",
574
		'likes_enabled' => "(bool) Should the post be open to likes? Defaults to the blog's preference.",
575
		'sharing_enabled' => "(bool) Should sharing buttons show on this post? Defaults to true.",
576
		'menu_order'    => "(int) (Pages Only) the order pages should appear in. Use 0 to maintain alphabetical order.",
577
	),
578
579
	'example_request'      => 'https://public-api.wordpress.com/rest/v1/sites/82974409/posts/new/',
580
581
	'example_request_data' => array(
582
		'headers' => array(
583
			'authorization' => 'Bearer YOUR_API_TOKEN'
584
		),
585
586
		'body' => array(
587
			'title'      => 'Hello World',
588
			'content'    => 'Hello. I am a test post. I was created by the API',
589
			'tags'       => 'tests',
590
			'categories' => 'API'
591
		)
592
	)
593
) );
594
595
new WPCOM_JSON_API_Update_Post_v1_1_Endpoint( array(
596
	'description' => 'Create a post.',
597
	'group'       => 'posts',
598
	'stat'        => 'posts:new',
599
	'min_version' => '1.1',
600
	'max_version' => '1.1',
601
	'method'      => 'POST',
602
	'path'        => '/sites/%s/posts/new',
603
	'path_labels' => array(
604
		'$site' => '(int|string) Site ID or domain',
605
	),
606
607
	'request_format' => array(
608
		// explicitly document all input
609
		'date'      => "(ISO 8601 datetime) The post's creation time.",
610
		'title'     => '(HTML) The post title.',
611
		'content'   => '(HTML) The post content.',
612
		'excerpt'   => '(HTML) An optional post excerpt.',
613
		'slug'      => '(string) The name (slug) for the post, used in URLs.',
614
		'author'    => '(string) The username or ID for the user to assign the post to.',
615
		'publicize' => '(array|bool) True or false if the post be publicized to external services. An array of services if we only want to publicize to a select few. Defaults to true.',
616
		'publicize_message' => '(string) Custom message to be publicized to external services.',
617
		'status'    => array(
618
			'publish' => 'Publish the post.',
619
			'private' => 'Privately publish the post.',
620
			'draft'   => 'Save the post as a draft.',
621
			'pending' => 'Mark the post as pending editorial approval.',
622
			'future'  => 'Schedule the post (alias for publish; you must also set a future date).',
623
			'auto-draft' => 'Save a placeholder for a newly created post, with no content.',
624
		),
625
		'sticky'    => array(
626
			'false'   => 'Post is not marked as sticky.',
627
			'true'    => 'Stick the post to the front page.',
628
		),
629
		'password'  => '(string) The plaintext password protecting the post, or, more likely, the empty string if the post is not password protected.',
630
		'parent'    => "(int) The post ID of the new post's parent.",
631
		'type'      => "(string) The post type. Defaults to 'post'. Post types besides post and page need to be whitelisted using the <code>rest_api_allowed_post_types</code> filter.",
632
		'categories' => "(array|string) Comma-separated list or array of categories (name or id)",
633
		'tags'       => "(array|string) Comma-separated list or array of tags (name or id)",
634
		'format'     => array_merge( array( 'default' => 'Use default post format' ), get_post_format_strings() ),
635
		'featured_image' => "(string) The post ID of an existing attachment to set as the featured image. Pass an empty string to delete the existing image.",
636
		'media'      => "(media) An array of files to attach to the post. To upload media, the entire request should be multipart/form-data encoded. Multiple media items will be displayed in a gallery. Accepts  jpg, jpeg, png, gif, pdf, doc, ppt, odt, pptx, docx, pps, ppsx, xls, xlsx, key. Audio and Video may also be available. See <code>allowed_file_types</code> in the options response of the site endpoint. Errors produced by media uploads, if any, will be in `media_errors` in the response. <br /><br /><strong>Example</strong>:<br />" .
1 ignored issue
show
String concat is not required here; use a single string instead
Loading history...
637
		 				"<code>curl \<br />--form 'title=Image Post' \<br />--form 'media[0]=@/path/to/file.jpg' \<br />--form 'media_attrs[0][caption]=My Great Photo' \<br />-H 'Authorization: BEARER your-token' \<br />'https://public-api.wordpress.com/rest/v1/sites/123/posts/new'</code>",
638
		'media_urls' => "(array) An array of URLs for images to attach to a post. Sideloads the media in for a post. Errors produced by media sideloading, if any, will be in `media_errors` in the response.",
639
		'media_attrs' => "(array) An array of attributes (`title`, `description` and `caption`) are supported to assign to the media uploaded via the `media` or `media_urls` properties. You must use a numeric index for the keys of `media_attrs` which follow the same sequence as `media` and `media_urls`. <br /><br /><strong>Example</strong>:<br />" .
1 ignored issue
show
String concat is not required here; use a single string instead
Loading history...
640
		                 "<code>curl \<br />--form 'title=Gallery Post' \<br />--form 'media[]=@/path/to/file1.jpg' \<br />--form 'media_urls[]=http://exapmple.com/file2.jpg' \<br /> \<br />--form 'media_attrs[0][caption]=This will be the caption for file1.jpg' \<br />--form 'media_attrs[1][title]=This will be the title for file2.jpg' \<br />-H 'Authorization: BEARER your-token' \<br />'https://public-api.wordpress.com/rest/v1/sites/123/posts/new'</code>",
641
		'metadata'      => "(array) Array of metadata objects containing the following properties: `key` (metadata key), `id` (meta ID), `previous_value` (if set, the action will only occur for the provided previous value), `value` (the new value to set the meta to), `operation` (the operation to perform: `update` or `add`; defaults to `update`). All unprotected meta keys are available by default for read requests. Both unprotected and protected meta keys are avaiable for authenticated requests with proper capabilities. Protected meta keys can be made available with the <code>rest_api_allowed_public_metadata</code> filter.",
642
		'discussion'    => '(object) A hash containing one or more of the following boolean values, which default to the blog\'s discussion preferences: `comments_open`, `pings_open`',
643
		'likes_enabled' => "(bool) Should the post be open to likes? Defaults to the blog's preference.",
644
		'sharing_enabled' => "(bool) Should sharing buttons show on this post? Defaults to true.",
645
		'menu_order'    => "(int) (Pages Only) the order pages should appear in. Use 0 to maintain alphabetical order.",
646
		'page_template' => '(string) (Pages Only) The page template this page should use.',
647
	),
648
649
	'example_request'      => 'https://public-api.wordpress.com/rest/v1.1/sites/82974409/posts/new/',
650
651
	'example_request_data' => array(
652
		'headers' => array(
653
			'authorization' => 'Bearer YOUR_API_TOKEN'
654
		),
655
656
		'body' => array(
657
			'title'      => 'Hello World',
658
			'content'    => 'Hello. I am a test post. I was created by the API',
659
			'tags'       => 'tests',
660
			'categories' => 'API'
661
		)
662
	)
663
) );
664
665
new WPCOM_JSON_API_Update_Post_v1_2_Endpoint( array(
666
	'description' => 'Create a post.',
667
	'group'       => 'posts',
668
	'stat'        => 'posts:new',
669
	'min_version' => '1.2',
670
	'max_version' => '1.2',
671
	'method'      => 'POST',
672
	'path'        => '/sites/%s/posts/new',
673
	'path_labels' => array(
674
		'$site' => '(int|string) Site ID or domain',
675
	),
676
677
	'request_format' => array(
678
		// explicitly document all input
679
		'date'      => "(ISO 8601 datetime) The post's creation time.",
680
		'title'     => '(HTML) The post title.',
681
		'content'   => '(HTML) The post content.',
682
		'excerpt'   => '(HTML) An optional post excerpt.',
683
		'slug'      => '(string) The name (slug) for the post, used in URLs.',
684
		'author'    => '(string) The username or ID for the user to assign the post to.',
685
		'publicize' => '(array|bool) True or false if the post be publicized to external services. An array of services if we only want to publicize to a select few. Defaults to true.',
686
		'publicize_message' => '(string) Custom message to be publicized to external services.',
687
		'status'    => array(
688
			'publish' => 'Publish the post.',
689
			'private' => 'Privately publish the post.',
690
			'draft'   => 'Save the post as a draft.',
691
			'pending' => 'Mark the post as pending editorial approval.',
692
			'future'  => 'Schedule the post (alias for publish; you must also set a future date).',
693
			'auto-draft' => 'Save a placeholder for a newly created post, with no content.',
694
		),
695
		'sticky'    => array(
696
			'false'   => 'Post is not marked as sticky.',
697
			'true'    => 'Stick the post to the front page.',
698
		),
699
		'password'  => '(string) The plaintext password protecting the post, or, more likely, the empty string if the post is not password protected.',
700
		'parent'    => "(int) The post ID of the new post's parent.",
701
		'type'      => "(string) The post type. Defaults to 'post'. Post types besides post and page need to be whitelisted using the <code>rest_api_allowed_post_types</code> filter.",
702
		'categories' => "(array|string) Comma-separated list or array of category names",
703
		'tags'       => "(array|string) Comma-separated list or array of tag names",
704
		'categories_by_id' => "(array|string) Comma-separated list or array of category IDs",
705
		'tags_by_id'       => "(array|string) Comma-separated list or array of tag IDs",
706
		'format'     => array_merge( array( 'default' => 'Use default post format' ), get_post_format_strings() ),
707
		'featured_image' => "(string) The post ID of an existing attachment to set as the featured image. Pass an empty string to delete the existing image.",
708
		'media'      => "(media) An array of files to attach to the post. To upload media, the entire request should be multipart/form-data encoded. Multiple media items will be displayed in a gallery. Accepts  jpg, jpeg, png, gif, pdf, doc, ppt, odt, pptx, docx, pps, ppsx, xls, xlsx, key. Audio and Video may also be available. See <code>allowed_file_types</code> in the options response of the site endpoint. Errors produced by media uploads, if any, will be in `media_errors` in the response. <br /><br /><strong>Example</strong>:<br />" .
1 ignored issue
show
String concat is not required here; use a single string instead
Loading history...
709
		 				"<code>curl \<br />--form 'title=Image Post' \<br />--form 'media[0]=@/path/to/file.jpg' \<br />--form 'media_attrs[0][caption]=My Great Photo' \<br />-H 'Authorization: BEARER your-token' \<br />'https://public-api.wordpress.com/rest/v1/sites/123/posts/new'</code>",
710
		'media_urls' => "(array) An array of URLs for images to attach to a post. Sideloads the media in for a post. Errors produced by media sideloading, if any, will be in `media_errors` in the response.",
711
		'media_attrs' => "(array) An array of attributes (`title`, `description` and `caption`) are supported to assign to the media uploaded via the `media` or `media_urls` properties. You must use a numeric index for the keys of `media_attrs` which follow the same sequence as `media` and `media_urls`. <br /><br /><strong>Example</strong>:<br />" .
1 ignored issue
show
String concat is not required here; use a single string instead
Loading history...
712
		                 "<code>curl \<br />--form 'title=Gallery Post' \<br />--form 'media[]=@/path/to/file1.jpg' \<br />--form 'media_urls[]=http://exapmple.com/file2.jpg' \<br /> \<br />--form 'media_attrs[0][caption]=This will be the caption for file1.jpg' \<br />--form 'media_attrs[1][title]=This will be the title for file2.jpg' \<br />-H 'Authorization: BEARER your-token' \<br />'https://public-api.wordpress.com/rest/v1/sites/123/posts/new'</code>",
713
		'metadata'      => "(array) Array of metadata objects containing the following properties: `key` (metadata key), `id` (meta ID), `previous_value` (if set, the action will only occur for the provided previous value), `value` (the new value to set the meta to), `operation` (the operation to perform: `update` or `add`; defaults to `update`). All unprotected meta keys are available by default for read requests. Both unprotected and protected meta keys are avaiable for authenticated requests with proper capabilities. Protected meta keys can be made available with the <code>rest_api_allowed_public_metadata</code> filter.",
714
		'discussion'    => '(object) A hash containing one or more of the following boolean values, which default to the blog\'s discussion preferences: `comments_open`, `pings_open`',
715
		'likes_enabled' => "(bool) Should the post be open to likes? Defaults to the blog's preference.",
716
		'sharing_enabled' => "(bool) Should sharing buttons show on this post? Defaults to true.",
717
		'menu_order'    => "(int) (Pages Only) the order pages should appear in. Use 0 to maintain alphabetical order.",
718
		'page_template' => '(string) (Pages Only) The page template this page should use.',
719
	),
720
721
	'example_request'      => 'https://public-api.wordpress.com/rest/v1.2/sites/82974409/posts/new/',
722
723
	'example_request_data' => array(
724
		'headers' => array(
725
			'authorization' => 'Bearer YOUR_API_TOKEN'
726
		),
727
728
		'body' => array(
729
			'title'      => 'Hello World',
730
			'content'    => 'Hello. I am a test post. I was created by the API',
731
			'tags'       => 'tests',
732
			'categories' => 'API'
733
		)
734
	)
735
) );
736
737
new WPCOM_JSON_API_Update_Post_Endpoint( array(
738
	'description' => 'Edit a post.',
739
	'group'       => 'posts',
740
	'stat'        => 'posts:1:POST',
741
	'new_version' => '1.1',
742
	'max_version' => '1',
743
	'method'      => 'POST',
744
	'path'        => '/sites/%s/posts/%d',
745
	'path_labels' => array(
746
		'$site'    => '(int|string) Site ID or domain',
747
		'$post_ID' => '(int) The post ID',
748
	),
749
750
	'request_format' => array(
751
		'date'      => "(ISO 8601 datetime) The post's creation time.",
752
		'title'     => '(HTML) The post title.',
753
		'content'   => '(HTML) The post content.',
754
		'excerpt'   => '(HTML) An optional post excerpt.',
755
		'slug'      => '(string) The name (slug) for the post, used in URLs.',
756
		'author'    => '(string) The username or ID for the user to assign the post to.',
757
		'publicize' => '(array|bool) True or false if the post be publicized to external services. An array of services if we only want to publicize to a select few. Defaults to true.',
758
		'publicize_message' => '(string) Custom message to be publicized to external services.',
759
		'status'    => array(
760
			'publish' => 'Publish the post.',
761
			'private' => 'Privately publish the post.',
762
			'draft'   => 'Save the post as a draft.',
763
			'pending' => 'Mark the post as pending editorial approval.',
764
		),
765
		'sticky'    => array(
766
			'false'   => 'Post is not marked as sticky.',
767
			'true'    => 'Stick the post to the front page.',
768
		),
769
		'password'   => '(string) The plaintext password protecting the post, or, more likely, the empty string if the post is not password protected.',
770
		'parent'     => "(int) The post ID of the new post's parent.",
771
		'categories' => "(array|string) Comma-separated list or array of categories (name or id)",
772
		'tags'       => "(array|string) Comma-separated list or array of tags (name or id)",
773
		'format'     => array_merge( array( 'default' => 'Use default post format' ), get_post_format_strings() ),
774
		'comments_open' => '(bool) Should the post be open to comments?',
775
		'pings_open'    => '(bool) Should the post be open to comments?',
776
		'likes_enabled' => "(bool) Should the post be open to likes?",
777
		'menu_order'    => "(int) (Pages Only) the order pages should appear in. Use 0 to maintain alphabetical order.",
778
		'sharing_enabled' => "(bool) Should sharing buttons show on this post?",
779
		'featured_image' => "(string) The post ID of an existing attachment to set as the featured image. Pass an empty string to delete the existing image.",
780
		'media'      => "(media) An array of files to attach to the post. To upload media, the entire request should be multipart/form-data encoded. Multiple media items will be displayed in a gallery. Accepts  jpg, jpeg, png, gif, pdf, doc, ppt, odt, pptx, docx, pps, ppsx, xls, xlsx, key. Audio and Video may also be available. See <code>allowed_file_types</code> in the options resposne of the site endpoint. <br /><br /><strong>Example</strong>:<br />" .
1 ignored issue
show
String concat is not required here; use a single string instead
Loading history...
781
		 				"<code>curl \<br />--form 'title=Image' \<br />--form 'media[]=@/path/to/file.jpg' \<br />-H 'Authorization: BEARER your-token' \<br />'https://public-api.wordpress.com/rest/v1/sites/123/posts/new'</code>",
782
		'media_urls' => "(array) An array of URLs for images to attach to a post. Sideloads the media in for a post.",
783
		'metadata'      => "(array) Array of metadata objects containing the following properties: `key` (metadata key), `id` (meta ID), `previous_value` (if set, the action will only occur for the provided previous value), `value` (the new value to set the meta to), `operation` (the operation to perform: `update` or `add`; defaults to `update`). All unprotected meta keys are available by default for read requests. Both unprotected and protected meta keys are available for authenticated requests with proper capabilities. Protected meta keys can be made available with the <code>rest_api_allowed_public_metadata</code> filter.",
784
	),
785
786
	'example_request'      => 'https://public-api.wordpress.com/rest/v1/sites/82974409/posts/881',
787
788
	'example_request_data' => array(
789
		'headers' => array(
790
			'authorization' => 'Bearer YOUR_API_TOKEN'
791
		),
792
793
		'body' => array(
794
			'title'      => 'Hello World (Again)',
795
			'content'    => 'Hello. I am an edited post. I was edited by the API',
796
			'tags'       => 'tests',
797
			'categories' => 'API'
798
		)
799
	)
800
) );
801
802
new WPCOM_JSON_API_Update_Post_v1_1_Endpoint( array(
803
	'description' => 'Edit a post.',
804
	'group'       => 'posts',
805
	'stat'        => 'posts:1:POST',
806
	'min_version' => '1.1',
807
	'max_version' => '1.1',
808
	'method'      => 'POST',
809
	'path'        => '/sites/%s/posts/%d',
810
	'path_labels' => array(
811
		'$site'    => '(int|string) Site ID or domain',
812
		'$post_ID' => '(int) The post ID',
813
	),
814
815
	'request_format' => array(
816
		'date'      => "(ISO 8601 datetime) The post's creation time.",
817
		'title'     => '(HTML) The post title.',
818
		'content'   => '(HTML) The post content.',
819
		'excerpt'   => '(HTML) An optional post excerpt.',
820
		'slug'      => '(string) The name (slug) for the post, used in URLs.',
821
		'author'    => '(string) The username or ID for the user to assign the post to.',
822
		'publicize' => '(array|bool) True or false if the post be publicized to external services. An array of services if we only want to publicize to a select few. Defaults to true.',
823
		'publicize_message' => '(string) Custom message to be publicized to external services.',
824
		'status'    => array(
825
			'publish' => 'Publish the post.',
826
			'private' => 'Privately publish the post.',
827
			'draft'   => 'Save the post as a draft.',
828
			'future'  => 'Schedule the post (alias for publish; you must also set a future date).',
829
			'pending' => 'Mark the post as pending editorial approval.',
830
		),
831
		'sticky'    => array(
832
			'false'   => 'Post is not marked as sticky.',
833
			'true'    => 'Stick the post to the front page.',
834
		),
835
		'password'   => '(string) The plaintext password protecting the post, or, more likely, the empty string if the post is not password protected.',
836
		'parent'     => "(int) The post ID of the new post's parent.",
837
		'categories' => "(array|string) Comma-separated list or array of categories (name or id)",
838
		'tags'       => "(array|string) Comma-separated list or array of tags (name or id)",
839
		'format'     => array_merge( array( 'default' => 'Use default post format' ), get_post_format_strings() ),
840
		'discussion' => '(object) A hash containing one or more of the following boolean values, which default to the blog\'s discussion preferences: `comments_open`, `pings_open`',
841
		'likes_enabled' => "(bool) Should the post be open to likes?",
842
		'menu_order'    => "(int) (Pages only) the order pages should appear in. Use 0 to maintain alphabetical order.",
843
		'page_template' => '(string) (Pages Only) The page template this page should use.',
844
		'sharing_enabled' => "(bool) Should sharing buttons show on this post?",
845
		'featured_image' => "(string) The post ID of an existing attachment to set as the featured image. Pass an empty string to delete the existing image.",
846
		'media'      => "(media) An array of files to attach to the post. To upload media, the entire request should be multipart/form-data encoded. Multiple media items will be displayed in a gallery. Accepts  jpg, jpeg, png, gif, pdf, doc, ppt, odt, pptx, docx, pps, ppsx, xls, xlsx, key. Audio and Video may also be available. See <code>allowed_file_types</code> in the options resposne of the site endpoint. <br /><br /><strong>Example</strong>:<br />" .
1 ignored issue
show
String concat is not required here; use a single string instead
Loading history...
847
		 				"<code>curl \<br />--form 'title=Image' \<br />--form 'media[]=@/path/to/file.jpg' \<br />-H 'Authorization: BEARER your-token' \<br />'https://public-api.wordpress.com/rest/v1/sites/123/posts/new'</code>",
848
		'media_urls' => "(array) An array of URLs for images to attach to a post. Sideloads the media in for a post.",
849
		'metadata'      => "(array) Array of metadata objects containing the following properties: `key` (metadata key), `id` (meta ID), `previous_value` (if set, the action will only occur for the provided previous value), `value` (the new value to set the meta to), `operation` (the operation to perform: `update` or `add`; defaults to `update`). All unprotected meta keys are available by default for read requests. Both unprotected and protected meta keys are available for authenticated requests with proper capabilities. Protected meta keys can be made available with the <code>rest_api_allowed_public_metadata</code> filter.",
850
	),
851
852
	'example_request'      => 'https://public-api.wordpress.com/rest/v1.1/sites/82974409/posts/881',
853
854
	'example_request_data' => array(
855
		'headers' => array(
856
			'authorization' => 'Bearer YOUR_API_TOKEN'
857
		),
858
859
		'body' => array(
860
			'title'      => 'Hello World (Again)',
861
			'content'    => 'Hello. I am an edited post. I was edited by the API',
862
			'tags'       => 'tests',
863
			'categories' => 'API'
864
		)
865
	)
866
) );
867
868
new WPCOM_JSON_API_Update_Post_v1_2_Endpoint( array(
869
	'description' => 'Edit a post.',
870
	'group'       => 'posts',
871
	'stat'        => 'posts:1:POST',
872
	'min_version' => '1.2',
873
	'max_version' => '1.2',
874
	'method'      => 'POST',
875
	'path'        => '/sites/%s/posts/%d',
876
	'path_labels' => array(
877
		'$site'    => '(int|string) Site ID or domain',
878
		'$post_ID' => '(int) The post ID',
879
	),
880
881
	'request_format' => array(
882
		'date'      => "(ISO 8601 datetime) The post's creation time.",
883
		'title'     => '(HTML) The post title.',
884
		'content'   => '(HTML) The post content.',
885
		'excerpt'   => '(HTML) An optional post excerpt.',
886
		'slug'      => '(string) The name (slug) for the post, used in URLs.',
887
		'author'    => '(string) The username or ID for the user to assign the post to.',
888
		'publicize' => '(array|bool) True or false if the post be publicized to external services. An array of services if we only want to publicize to a select few. Defaults to true.',
889
		'publicize_message' => '(string) Custom message to be publicized to external services.',
890
		'status'    => array(
891
			'publish' => 'Publish the post.',
892
			'private' => 'Privately publish the post.',
893
			'draft'   => 'Save the post as a draft.',
894
			'future'  => 'Schedule the post (alias for publish; you must also set a future date).',
895
			'pending' => 'Mark the post as pending editorial approval.',
896
		),
897
		'sticky'    => array(
898
			'false'   => 'Post is not marked as sticky.',
899
			'true'    => 'Stick the post to the front page.',
900
		),
901
		'password'   => '(string) The plaintext password protecting the post, or, more likely, the empty string if the post is not password protected.',
902
		'parent'     => "(int) The post ID of the new post's parent.",
903
		'categories' => "(array|string) Comma-separated list or array of category names",
904
		'categories_by_id' => "(array|string) Comma-separated list or array of category IDs",
905
		'tags'       => "(array|string) Comma-separated list or array of tag names",
906
		'tags_by_id'       => "(array|string) Comma-separated list or array of tag IDs",
907
		'format'     => array_merge( array( 'default' => 'Use default post format' ), get_post_format_strings() ),
908
		'discussion' => '(object) A hash containing one or more of the following boolean values, which default to the blog\'s discussion preferences: `comments_open`, `pings_open`',
909
		'likes_enabled' => "(bool) Should the post be open to likes?",
910
		'menu_order'    => "(int) (Pages only) the order pages should appear in. Use 0 to maintain alphabetical order.",
911
		'page_template' => '(string) (Pages Only) The page template this page should use.',
912
		'sharing_enabled' => "(bool) Should sharing buttons show on this post?",
913
		'featured_image' => "(string) The post ID of an existing attachment to set as the featured image. Pass an empty string to delete the existing image.",
914
		'media'      => "(media) An array of files to attach to the post. To upload media, the entire request should be multipart/form-data encoded. Multiple media items will be displayed in a gallery. Accepts  jpg, jpeg, png, gif, pdf, doc, ppt, odt, pptx, docx, pps, ppsx, xls, xlsx, key. Audio and Video may also be available. See <code>allowed_file_types</code> in the options resposne of the site endpoint. <br /><br /><strong>Example</strong>:<br />" .
1 ignored issue
show
String concat is not required here; use a single string instead
Loading history...
915
		 				"<code>curl \<br />--form 'title=Image' \<br />--form 'media[]=@/path/to/file.jpg' \<br />-H 'Authorization: BEARER your-token' \<br />'https://public-api.wordpress.com/rest/v1/sites/123/posts/new'</code>",
916
		'media_urls' => "(array) An array of URLs for images to attach to a post. Sideloads the media in for a post.",
917
		'metadata'      => "(array) Array of metadata objects containing the following properties: `key` (metadata key), `id` (meta ID), `previous_value` (if set, the action will only occur for the provided previous value), `value` (the new value to set the meta to), `operation` (the operation to perform: `update` or `add`; defaults to `update`). All unprotected meta keys are available by default for read requests. Both unprotected and protected meta keys are available for authenticated requests with proper capabilities. Protected meta keys can be made available with the <code>rest_api_allowed_public_metadata</code> filter.",
918
	),
919
920
	'example_request'      => 'https://public-api.wordpress.com/rest/v1.2/sites/82974409/posts/881',
921
922
	'example_request_data' => array(
923
		'headers' => array(
924
			'authorization' => 'Bearer YOUR_API_TOKEN'
925
		),
926
927
		'body' => array(
928
			'title'      => 'Hello World (Again)',
929
			'content'    => 'Hello. I am an edited post. I was edited by the API',
930
			'tags'       => 'tests',
931
			'categories' => 'API'
932
		)
933
	)
934
) );
935
936
new WPCOM_JSON_API_Update_Post_Endpoint( array(
937
	'description' => 'Delete a post. Note: If the post object is of type post or page and the trash is enabled, this request will send the post to the trash. A second request will permanently delete the post.',
938
	'group'       => 'posts',
939
	'stat'        => 'posts:1:delete',
940
	'new_version' => '1.1',
941
	'max_version' => '1',
942
	'method'      => 'POST',
943
	'path'        => '/sites/%s/posts/%d/delete',
944
	'path_labels' => array(
945
		'$site'    => '(int|string) Site ID or domain',
946
		'$post_ID' => '(int) The post ID',
947
	),
948
949
	'example_request'      => 'https://public-api.wordpress.com/rest/v1/sites/82974409/posts/$post_ID/delete/',
950
951
	'example_request_data' => array(
952
		'headers' => array(
953
			'authorization' => 'Bearer YOUR_API_TOKEN'
954
		)
955
	)
956
) );
957
958
new WPCOM_JSON_API_Update_Post_v1_1_Endpoint( array(
959
	'description' => 'Delete a post. Note: If the post object is of type post or page and the trash is enabled, this request will send the post to the trash. A second request will permanently delete the post.',
960
	'group'       => 'posts',
961
	'stat'        => 'posts:1:delete',
962
	'min_version' => '1.1',
963
	'max_version' => '1.1',
964
	'method'      => 'POST',
965
	'path'        => '/sites/%s/posts/%d/delete',
966
	'path_labels' => array(
967
		'$site'    => '(int|string) Site ID or domain',
968
		'$post_ID' => '(int) The post ID',
969
	),
970
971
	'example_request'      => 'https://public-api.wordpress.com/rest/v1.1/sites/82974409/posts/$post_ID/delete/',
972
973
	'example_request_data' => array(
974
		'headers' => array(
975
			'authorization' => 'Bearer YOUR_API_TOKEN'
976
		)
977
	)
978
) );
979
980
new WPCOM_JSON_API_Update_Post_Endpoint( array(
981
	'description' => 'Restore a post or page from the trash to its previous status.',
982
	'group'       => 'posts',
983
	'stat'        => 'posts:1:restore',
984
985
	'method'      => 'POST',
986
	'new_version' => '1.1',
987
	'max_version' => '1',
988
	'path'        => '/sites/%s/posts/%d/restore',
989
	'path_labels' => array(
990
		'$site'    => '(int|string) Site ID or domain',
991
		'$post_ID' => '(int) The post ID',
992
	),
993
994
	'example_request'      => 'https://public-api.wordpress.com/rest/v1/sites/82974409/posts/$post_ID/restore/',
995
996
	'example_request_data' => array(
997
		'headers' => array(
998
			'authorization' => 'Bearer YOUR_API_TOKEN'
999
		)
1000
	)
1001
) );
1002
1003
new WPCOM_JSON_API_Update_Post_v1_1_Endpoint( array(
1004
	'description' => 'Restore a post or page from the trash to its previous status.',
1005
	'group'       => 'posts',
1006
	'stat'        => 'posts:1:restore',
1007
	'min_version' => '1.1',
1008
	'max_version' => '1.1',
1009
	'method'      => 'POST',
1010
	'path'        => '/sites/%s/posts/%d/restore',
1011
	'path_labels' => array(
1012
		'$site'    => '(int|string) Site ID or domain',
1013
		'$post_ID' => '(int) The post ID',
1014
	),
1015
1016
	'example_request'      => 'https://public-api.wordpress.com/rest/v1.1/sites/82974409/posts/$post_ID/restore/',
1017
1018
	'example_request_data' => array(
1019
		'headers' => array(
1020
			'authorization' => 'Bearer YOUR_API_TOKEN'
1021
		)
1022
	)
1023
) );
1024
1025
new WPCOM_JSON_API_Get_Autosave_v1_1_Endpoint( array(
1026
	'description' => 'Get the most recent autosave for a post.',
1027
	'group'       => '__do_not_document',
1028
	'stat'        => 'posts:autosave',
1029
	'min_version' => '1.1',
1030
	'method'      => 'GET',
1031
	'path'        => '/sites/%s/posts/%d/autosave',
1032
	'path_labels' => array(
1033
		'$site'    => '(int|string) Site ID or domain',
1034
		'$post_ID' => '(int) The post ID',
1035
	),
1036
	'response_format' => array(
1037
		'ID'          => '(int) autodraft post ID',
1038
		'post_ID'     => '(int) post ID',
1039
		'author_ID'   => '(int) author ID',
1040
		'title'       => '(HTML) The post title.',
1041
		'content'     => '(HTML) The post content.',
1042
		'excerpt'     => '(HTML) The post excerpt.',
1043
		'preview_URL' => '(string) preview URL for the post',
1044
		'modified'    => '(ISO 8601 datetime) modified time',
1045
	),
1046
1047
	'example_request' => 'https://public-api.wordpress.com/rest/v1.1/sites/82974409/posts/1/autosave',
1048
) );
1049
1050
new WPCOM_JSON_API_Autosave_Post_v1_1_Endpoint( array(
1051
	'description' => 'Create a post autosave.',
1052
	'group'       => '__do_not_document',
1053
	'stat'        => 'posts:autosave',
1054
	'min_version' => '1.1',
1055
	'method'      => 'POST',
1056
	'path'        => '/sites/%s/posts/%d/autosave',
1057
	'path_labels' => array(
1058
		'$site'    => '(int|string) Site ID or domain',
1059
		'$post_ID' => '(int) The post ID',
1060
	),
1061
	'request_format' => array(
1062
		'content' => '(HTML) The post content.',
1063
		'title'   => '(HTML) The post title.',
1064
		'excerpt' => '(HTML) The post excerpt.',
1065
	),
1066
	'response_format' => array(
1067
		'ID'          => '(int) autodraft post ID',
1068
		'post_ID'     => '(int) post ID',
1069
		'preview_URL' => '(string) preview URL for the post',
1070
		'modified'    => '(ISO 8601 datetime) modified time',
1071
	),
1072
1073
	'example_request' => 'https://public-api.wordpress.com/rest/v1.1/sites/82974409/posts/1/autosave',
1074
1075
	'example_request_data' => array(
1076
		'headers' => array(
1077
			'authorization' => 'Bearer YOUR_API_TOKEN'
1078
		),
1079
1080
		'body' => array(
1081
			'title'    => 'Howdy',
1082
			'content'    => 'Hello. I am a test post. I was created by the API',
1083
		)
1084
	)
1085
) );
1086
1087
/*
1088
 * Media Endpoints
1089
 */
1090
new WPCOM_JSON_API_List_Media_Endpoint( array(
1091
	'description' => 'Get a list of items in the media library.',
1092
	'group'       => 'media',
1093
	'stat'        => 'media',
1094
1095
	'method'      => 'GET',
1096
	'path'        => '/sites/%s/media/',
1097
	'deprecated'  => true,
1098
	'new_version' => '1.1',
1099
	'max_version' => '1',
1100
	'path_labels' => array(
1101
		'$site' => '(int|string) Site ID or domain',
1102
	),
1103
1104
	'query_parameters' => array(
1105
		'number'    => '(int=20) The number of media items to return. Limit: 100.',
1106
		'offset'    => '(int=0) 0-indexed offset.',
1107
		'parent_id' => '(int) Default is showing all items. The post where the media item is attached. 0 shows unattached media items.',
1108
		'mime_type' => "(string) Default is empty. Filter by mime type (e.g., 'image/jpeg', 'application/pdf'). Partial searches also work (e.g. passing 'image' will search for all image files).",
1109
	),
1110
1111
	'response_format' => array(
1112
		'media' => '(array) Array of media',
1113
		'found' => '(int) The number of total results found'
1114
	),
1115
1116
	'example_request'      => 'https://public-api.wordpress.com/rest/v1/sites/82974409/media/?number=2',
1117
	'example_request_data' =>  array(
1118
		'headers' => array(
1119
			'authorization' => 'Bearer YOUR_API_TOKEN'
1120
		)
1121
	)
1122
) );
1123
1124
new WPCOM_JSON_API_List_Media_v1_1_Endpoint( array(
1125
	'description' => 'Get a list of items in the media library.',
1126
	'group'       => 'media',
1127
	'stat'        => 'media',
1128
	'min_version' => '1.1',
1129
	'max_version' => '1.1',
1130
	'method'      => 'GET',
1131
	'path'        => '/sites/%s/media/',
1132
	'path_labels' => array(
1133
		'$site' => '(int|string) Site ID or domain',
1134
	),
1135
1136
	'query_parameters' => array(
1137
		'number'    => '(int=20) The number of media items to return. Limit: 100.',
1138
		'offset'    => '(int=0) 0-indexed offset.',
1139
		'page'     => '(int) Return the Nth 1-indexed page of posts. Takes precedence over the <code>offset</code> parameter.',
1140
		'page_handle' => '(string) A page handle, returned from a previous API call as a <code>meta.next_page</code> property. This is the most efficient way to fetch the next page of results.',
1141
		'order'    => array(
1142
			'DESC' => 'Return files in descending order. For dates, that means newest to oldest.',
1143
			'ASC'  => 'Return files in ascending order. For dates, that means oldest to newest.',
1144
		),
1145
		'order_by' => array(
1146
			'date'          => 'Order by the uploaded time of each file.',
1147
			'title'         => "Order lexicographically by file titles.",
1148
			'ID'            => 'Order by media ID.',
1149
		),
1150
		'search'    => '(string) Search query.',
1151
		'post_ID'   => '(int) Default is showing all items. The post where the media item is attached. 0 shows unattached media items.',
1152
		'mime_type' => "(string) Default is empty. Filter by mime type (e.g., 'image/jpeg', 'application/pdf'). Partial searches also work (e.g. passing 'image' will search for all image files).",
1153
		'after'     => '(ISO 8601 datetime) Return media items uploaded after the specified datetime.',
1154
		'before'    => '(ISO 8601 datetime) Return media items uploaded before the specified datetime.',
1155
	),
1156
1157
	'response_format' => array(
1158
		'media' => '(array) Array of media objects',
1159
		'found' => '(int) The number of total results found'
1160
	),
1161
1162
	'example_request'      => 'https://public-api.wordpress.com/rest/v1.1/sites/82974409/media',
1163
	'example_request_data' =>  array(
1164
		'headers' => array(
1165
			'authorization' => 'Bearer YOUR_API_TOKEN'
1166
		)
1167
	)
1168
) );
1169
1170
new WPCOM_JSON_API_Get_Media_Endpoint( array(
1171
	'description' => 'Get a single media item (by ID).',
1172
	'group'       => 'media',
1173
	'stat'        => 'media:1',
1174
	'method'      => 'GET',
1175
	'path'        => '/sites/%s/media/%d',
1176
	'deprecated'  => true,
1177
	'new_version' => '1.1',
1178
	'max_version' => '1',
1179
	'path_labels' => array(
1180
		'$site'    => '(int|string) Site ID or domain',
1181
		'$media_ID' => '(int) The ID of the media item',
1182
	),
1183
	'response_format' => array(
1184
		'id'    => '(int) The ID of the media item',
1185
		'date' =>  '(ISO 8601 datetime) The date the media was uploaded',
1186
		'parent'           => '(int) ID of the post this media is attached to',
1187
		'link'             => '(string) URL to the file',
1188
		'title'            => '(string) Filename',
1189
		'caption'          => '(string) User-provided caption of the file',
1190
		'description'      => '(string) Description of the file',
1191
		'metadata'         => '(array) Array of metadata about the file, such as Exif data or sizes',
1192
	),
1193
1194
	'example_request'      => 'https://public-api.wordpress.com/rest/v1/sites/82974409/media/934',
1195
	'example_request_data' =>  array(
1196
		'headers' => array(
1197
			'authorization' => 'Bearer YOUR_API_TOKEN'
1198
		)
1199
	)
1200
) );
1201
1202
new WPCOM_JSON_API_Get_Media_v1_1_Endpoint( array(
1203
	'description' => 'Get a single media item (by ID).',
1204
	'group'       => 'media',
1205
	'stat'        => 'media:1',
1206
	'min_version' => '1.1',
1207
	'max_version' => '1.1',
1208
	'method'      => 'GET',
1209
	'path'        => '/sites/%s/media/%d',
1210
	'path_labels' => array(
1211
		'$site'    => '(int|string) Site ID or domain',
1212
		'$media_ID' => '(int) The ID of the media item',
1213
	),
1214
	'response_format' => array(
1215
		'ID'               => '(int) The ID of the media item',
1216
		'date'             => '(ISO 8601 datetime) The date the media was uploaded',
1217
		'post_ID'          => '(int) ID of the post this media is attached to',
1218
		'URL'              => '(string) URL to the file',
1219
		'guid'             => '(string) Unique identifier',
1220
		'file'			   => '(string) Filename',
1221
		'extension'        => '(string) File extension',
1222
		'mime_type'        => '(string) File MIME type',
1223
		'title'            => '(string) Filename',
1224
		'caption'          => '(string) User-provided caption of the file',
1225
		'description'      => '(string) Description of the file',
1226
		'alt'              => '(string)  Alternative text for image files.',
1227
		'thumbnails'       => '(object) Media item thumbnail URL options',
1228
		'height'           => '(int) (Image & video only) Height of the media item',
1229
		'width'            => '(int) (Image & video only) Width of the media item',
1230
		'length'           => '(int) (Video & audio only) Duration of the media item, in seconds',
1231
		'exif'             => '(array) (Image & audio only) Exif (meta) information about the media item',
1232
		'videopress_guid'  => '(string) (Video only) VideoPress GUID of the video when uploaded on a blog with VideoPress',
1233
		'videopress_processing_done'  => '(bool) (Video only) If the video is uploaded on a blog with VideoPress, this will return the status of processing on the video.'
1234
	),
1235
1236
	'example_request'      => 'https://public-api.wordpress.com/rest/v1.1/sites/82974409/media/934',
1237
	'example_request_data' =>  array(
1238
		'headers' => array(
1239
			'authorization' => 'Bearer YOUR_API_TOKEN'
1240
		)
1241
	)
1242
) );
1243
1244
new WPCOM_JSON_API_Upload_Media_Endpoint( array(
1245
	'description' => 'Upload a new media item.',
1246
	'group'       => 'media',
1247
	'stat'        => 'media:new',
1248
	'method'      => 'POST',
1249
	'path'        => '/sites/%s/media/new',
1250
	'deprecated'  => true,
1251
	'new_version' => '1.1',
1252
	'max_version' => '1',
1253
	'path_labels' => array(
1254
		'$site' => '(int|string) Site ID or domain',
1255
	),
1256
1257
	'request_format' => array(
1258
		'media'      => "(media) An array of media to attach to the post. To upload media, the entire request should be multipart/form-data encoded. Accepts images (image/gif, image/jpeg, image/png) only at this time.<br /><br /><strong>Example</strong>:<br />" .
1259
		                "<code>curl \<br />--form 'media[]=@/path/to/file.jpg' \<br />-H 'Authorization: BEARER your-token' \<br />'https://public-api.wordpress.com/rest/v1/sites/123/media/new'</code>",
1260
		'media_urls' => "(array) An array of URLs to upload to the post."
1261
	),
1262
1263
	'example_request'      => 'https://public-api.wordpress.com/rest/v1/sites/82974409/media/new/',
1264
1265
	'response_format' => array(
1266
		'media' => '(array) Array of uploaded media',
1267
		'errors' => '(array) Array of error messages of uploading media failures'
1268
	),
1269
	'example_request_data' =>  array(
1270
		'headers' => array(
1271
			'authorization' => 'Bearer YOUR_API_TOKEN'
1272
		),
1273
		'body' => array(
1274
			'media_urls' => "https://s.w.org/about/images/logos/codeispoetry-rgb.png"
1275
		)
1276
	)
1277
) );
1278
1279
new WPCOM_JSON_API_Upload_Media_v1_1_Endpoint( array(
1280
	'description' => 'Upload a new piece of media.',
1281
	'group'       => 'media',
1282
	'stat'        => 'media:new',
1283
	'min_version' => '1.1',
1284
	'max_version' => '1.1',
1285
	'method'      => 'POST',
1286
	'path'        => '/sites/%s/media/new',
1287
	'path_labels' => array(
1288
		'$site' => '(int|string) Site ID or domain',
1289
	),
1290
1291
	'request_format' => array(
1292
		'media'      => "(media) An array of media to attach to the post. To upload media, the entire request should be multipart/form-data encoded. Accepts  jpg, jpeg, png, gif, pdf, doc, ppt, odt, pptx, docx, pps, ppsx, xls, xlsx, key. Audio and Video may also be available. See <code>allowed_file_types</code> in the options response of the site endpoint.<br /><br /><strong>Example</strong>:<br />" .
1 ignored issue
show
String concat is not required here; use a single string instead
Loading history...
1293
		                "<code>curl \<br />--form 'media[]=@/path/to/file.jpg' \<br />-H 'Authorization: BEARER your-token' \<br />'https://public-api.wordpress.com/rest/v1/sites/123/media/new'</code>",
1294
		'media_urls' => "(array) An array of URLs to upload to the post. Errors produced by media uploads, if any, will be in `media_errors` in the response.",
1295
		'attrs' => "(array) An array of attributes (`title`, `description`, `caption` `alt` for images, `artist` for audio, `album` for audio, and `parent_id`) are supported to assign to the media uploaded via the `media` or `media_urls` properties. You must use a numeric index for the keys of `attrs` which follows the same sequence as `media` and `media_urls`. <br /><br /><strong>Example</strong>:<br />" .
1 ignored issue
show
String concat is not required here; use a single string instead
Loading history...
1296
		                 "<code>curl \<br />--form 'media[]=@/path/to/file1.jpg' \<br />--form 'media_urls[]=http://example.com/file2.jpg' \<br /> \<br />--form 'attrs[0][caption]=This will be the caption for file1.jpg' \<br />--form 'attrs[1][title]=This will be the title for file2.jpg' \<br />-H 'Authorization: BEARER your-token' \<br />'https://public-api.wordpress.com/rest/v1/sites/123/posts/new'</code>",
1297
	),
1298
1299
	'response_format' => array(
1300
		'media' => '(array) Array of uploaded media objects',
1301
		'errors' => '(array) Array of error messages of uploading media failures'
1302
	),
1303
1304
	'example_request' => 'https://public-api.wordpress.com/rest/v1.1/sites/82974409/media/new',
1305
	'example_request_data' =>  array(
1306
		'headers' => array(
1307
			'authorization' => 'Bearer YOUR_API_TOKEN'
1308
		),
1309
		'body' => array(
1310
			'media_urls' => "https://s.w.org/about/images/logos/codeispoetry-rgb.png"
1311
		)
1312
	)
1313
) );
1314
1315
new WPCOM_JSON_API_Update_Media_Endpoint( array(
1316
	'description' => 'Edit basic information about a media item.',
1317
	'group'       => 'media',
1318
	'stat'        => 'media:1:POST',
1319
	'method'      => 'POST',
1320
	'path'        => '/sites/%s/media/%d',
1321
	'deprecated'  => true,
1322
	'new_version' => '1.1',
1323
	'path_labels' => array(
1324
		'$site'    => '(int|string) Site ID or domain',
1325
		'$media_ID' => '(int) The ID of the media item',
1326
	),
1327
1328
	'request_format' => array(
1329
		'title'       => '(string) The file name.',
1330
		'caption'     => '(string) File caption.',
1331
		'description' => '(HTML) Description of the file.',
1332
	),
1333
1334
	'response_format' => array(
1335
		'id'          => '(int) The ID of the media item',
1336
		'date'        =>  '(ISO 8601 datetime) The date the media was uploaded',
1337
		'parent'      => '(int) ID of the post this media is attached to',
1338
		'link'        => '(string) URL to the file',
1339
		'title'       => '(string) File name',
1340
		'caption'     => '(string) User provided caption of the file',
1341
		'description' => '(string) Description of the file',
1342
		'metadata'    => '(array) Array of metadata about the file, such as Exif data or sizes',
1343
	),
1344
	'example_request'      => 'https://public-api.wordpress.com/rest/v1.1/sites/82974409/media/446',
1345
	'example_request_data' =>  array(
1346
		'headers' => array(
1347
			'authorization' => 'Bearer YOUR_API_TOKEN'
1348
		),
1349
		'body' => array(
1350
			'title' => 'Updated Title'
1351
		)
1352
	)
1353
) );
1354
1355
new WPCOM_JSON_API_Update_Media_v1_1_Endpoint( array(
1356
	'description' => 'Edit basic information about a media item.',
1357
	'group'       => 'media',
1358
	'stat'        => 'media:1:POST',
1359
	'min_version' => '1.1',
1360
	'max_version' => '1.1',
1361
	'method'      => 'POST',
1362
	'path'        => '/sites/%s/media/%d',
1363
	'path_labels' => array(
1364
		'$site'    => '(int|string) Site ID or domain',
1365
		'$media_ID' => '(int) The ID of the media item',
1366
	),
1367
1368
	'request_format' => array(
1369
		'parent_id'   => '(int) ID of the post this media is attached to',
1370
		'title'       => '(string) The file name.',
1371
		'caption'     => '(string) File caption.',
1372
		'description' => '(HTML) Description of the file.',
1373
		'alt'         => "(string) Alternative text for image files.",
1374
		'artist'      => "(string) Audio Only. Artist metadata for the audio track.",
1375
		'album'       => "(string) Audio Only. Album metadata for the audio track.",
1376
	),
1377
1378
	'response_format' => array(
1379
		'ID'               => '(int) The ID of the media item',
1380
		'date'             => '(ISO 8601 datetime) The date the media was uploaded',
1381
		'post_ID'          => '(int) ID of the post this media is attached to',
1382
		'URL'              => '(string) URL to the file',
1383
		'guid'             => '(string) Unique identifier',
1384
		'file'			   => '(string) File name',
1385
		'extension'        => '(string) File extension',
1386
		'mime_type'        => '(string) File mime type',
1387
		'title'            => '(string) File name',
1388
		'caption'          => '(string) User provided caption of the file',
1389
		'description'      => '(string) Description of the file',
1390
		'alt'              => '(string)  Alternative text for image files.',
1391
		'thumbnails'       => '(object) Media item thumbnail URL options',
1392
		'height'           => '(int) (Image & video only) Height of the media item',
1393
		'width'            => '(int) (Image & video only) Width of the media item',
1394
		'length'           => '(int) (Video & audio only) Duration of the media item, in seconds',
1395
		'exif'             => '(array) (Image & audio only) Exif (meta) information about the media item',
1396
		'videopress_guid'  => '(string) (Video only) VideoPress GUID of the video when uploaded on a blog with VideoPress',
1397
		'videopress_processing_done'  => '(bool) (Video only) If the video is uploaded on a blog with VideoPress, this will return the status of processing on the video.'
1398
	),
1399
1400
	'example_request'      => 'https://public-api.wordpress.com/rest/v1.1/sites/82974409/media/446',
1401
	'example_request_data' =>  array(
1402
		'headers' => array(
1403
			'authorization' => 'Bearer YOUR_API_TOKEN'
1404
		),
1405
		'body' => array(
1406
			'title' => 'Updated Title'
1407
		)
1408
	)
1409
) );
1410
1411
1412
new WPCOM_JSON_API_Delete_Media_Endpoint( array(
1413
	'description' => 'Delete a piece of media.',
1414
	'group'       => 'media',
1415
	'stat'        => 'media:1:delete',
1416
	'method'      => 'POST',
1417
	'path'        => '/sites/%s/media/%d/delete',
1418
	'deprecated'  => true,
1419
	'new_version' => '1.1',
1420
	'max_version' => '1',
1421
	'path_labels' => array(
1422
		'$site'    => '(int|string) Site ID or domain',
1423
		'$media_ID' => '(int) The media ID',
1424
	),
1425
1426
	'response_format' => array(
1427
		'status' => '(string) Returns deleted if the media was successfully deleted',
1428
		'id'    => '(int) The ID of the media item',
1429
		'date' =>  '(ISO 8601 datetime) The date the media was uploaded',
1430
		'parent'           => '(int) ID of the post this media is attached to',
1431
		'link'             => '(string) URL to the file',
1432
		'title'            => '(string) File name',
1433
		'caption'          => '(string) User provided caption of the file',
1434
		'description'      => '(string) Description of the file',
1435
		'metadata'         => '(array) Misc array of information about the file, such as exif data or sizes',
1436
	),
1437
1438
	'example_request'      => 'https://public-api.wordpress.com/rest/v1.1/sites/82974409/media/$media_ID/delete',
1439
	'example_request_data' =>  array(
1440
		'headers' => array(
1441
			'authorization' => 'Bearer YOUR_API_TOKEN'
1442
		)
1443
	)
1444
) );
1445
1446
new WPCOM_JSON_API_Delete_Media_v1_1_Endpoint( array(
1447
	'description' => 'Delete a piece of media. Note: Media is deleted and not trashed.',
1448
	'group'       => 'media',
1449
	'stat'        => 'media:1:delete',
1450
	'min_version' => '1.1',
1451
	'max_version' => '1.1',
1452
	'method'      => 'POST',
1453
	'path'        => '/sites/%s/media/%d/delete',
1454
	'path_labels' => array(
1455
		'$site'    => '(int|string) Site ID or domain',
1456
		'$media_ID' => '(int) The media ID',
1457
	),
1458
1459
	'response_format' => array(
1460
		'status'           => '(string) Returns deleted if the media was successfully deleted',
1461
		'ID'               => '(int) The ID of the media item',
1462
		'date'             => '(ISO 8601 datetime) The date the media was uploaded',
1463
		'post_ID'          => '(int) ID of the post this media is attached to',
1464
		'URL'              => '(string) URL to the file',
1465
		'guid'             => '(string) Unique identifier',
1466
		'file'			   => '(string) File name',
1467
		'extension'        => '(string) File extension',
1468
		'mime_type'        => '(string) File mime type',
1469
		'title'            => '(string) File name',
1470
		'caption'          => '(string) User-provided caption of the file',
1471
		'description'      => '(string) Description of the file',
1472
		'alt'              => '(string)  Alternative text for image files.',
1473
		'thumbnails'       => '(object) Media item thumbnail URL options',
1474
		'height'           => '(int) (Image & video only) Height of the media item',
1475
		'width'            => '(int) (Image & video only) Width of the media item',
1476
		'length'           => '(int) (Video & audio only) Duration of the media item, in seconds',
1477
		'exif'             => '(array) (Image & audio only) Exif (meta) information about the media item',
1478
		'videopress_guid'  => '(string) (Video only) VideoPress GUID of the video when uploaded on a blog with VideoPress',
1479
		'videopress_processing_done'  => '(bool) (Video only) If the video is Uuploaded on a blog with VideoPress, this will return the status of processing on the Video'
1480
	),
1481
1482
	'example_request'      => 'https://public-api.wordpress.com/rest/v1.1/sites/82974409/media/$media_ID/delete',
1483
	'example_request_data' =>  array(
1484
		'headers' => array(
1485
			'authorization' => 'Bearer YOUR_API_TOKEN'
1486
		)
1487
	)
1488
) );
1489
1490
/*
1491
 * Comment endpoints
1492
 */
1493
new WPCOM_JSON_API_List_Comments_Endpoint( array(
1494
	'description' => 'Get a list of recent comments.',
1495
	'group'       => 'comments',
1496
	'stat'        => 'comments',
1497
1498
	'method'      => 'GET',
1499
	'path'        => '/sites/%s/comments/',
1500
	'path_labels' => array(
1501
		'$site' => '(int|string) Site ID or domain',
1502
	),
1503
1504
	'example_request' => 'https://public-api.wordpress.com/rest/v1/sites/en.blog.wordpress.com/comments/?number=2'
1505
) );
1506
1507
new WPCOM_JSON_API_List_Comments_Endpoint( array(
1508
	'description' => 'Get a list of recent comments on a post.',
1509
	'group'       => 'comments',
1510
	'stat'        => 'posts:1:replies',
1511
1512
	'method'      => 'GET',
1513
	'path'        => '/sites/%s/posts/%d/replies/',
1514
	'path_labels' => array(
1515
		'$site'    => '(int|string) Site ID or domain',
1516
		'$post_ID' => '(int) The post ID',
1517
	),
1518
1519
	'example_request' => 'https://public-api.wordpress.com/rest/v1/sites/en.blog.wordpress.com/posts/7/replies/?number=2'
1520
) );
1521
1522
new WPCOM_JSON_API_Get_Comment_Endpoint( array(
1523
	'description' => 'Get a single comment.',
1524
	'group'       => 'comments',
1525
	'stat'        => 'comments:1',
1526
1527
	'method'      => 'GET',
1528
	'path'        => '/sites/%s/comments/%d',
1529
	'path_labels' => array(
1530
		'$site'       => '(int|string) Site ID or domain',
1531
		'$comment_ID' => '(int) The comment ID'
1532
	),
1533
1534
	'example_request' => 'https://public-api.wordpress.com/rest/v1/sites/en.blog.wordpress.com/comments/147564'
1535
) );
1536
1537
new WPCOM_JSON_API_Update_Comment_Endpoint( array(
1538
	'description' => 'Create a comment on a post.',
1539
	'group'       => 'comments',
1540
	'stat'        => 'posts:1:replies:new',
1541
1542
	'method'      => 'POST',
1543
	'path'        => '/sites/%s/posts/%d/replies/new',
1544
	'path_labels' => array(
1545
		'$site'    => '(int|string) Site ID or domain',
1546
		'$post_ID' => '(int) The post ID'
1547
	),
1548
1549
	'request_format' => array(
1550
		// explicitly document all input
1551
		'content'   => '(HTML) The comment text.',
1552
//		@todo Should we open this up to unauthenticated requests too?
1553
//		'author'    => '(author object) The author of the comment.',
1554
	),
1555
1556
	'pass_wpcom_user_details' => true,
1557
	'can_use_user_details_instead_of_blog_membership' => true,
1558
1559
	'example_request'      => 'https://public-api.wordpress.com/rest/v1/sites/82974409/posts/843/replies/new/',
1560
	'example_request_data' =>  array(
1561
		'headers' => array(
1562
			'authorization' => 'Bearer YOUR_API_TOKEN'
1563
		),
1564
		'body' => array(
1565
			'content' => 'Your reply is very interesting. This is a reply.'
1566
		)
1567
	)
1568
) );
1569
1570
new WPCOM_JSON_API_Update_Comment_Endpoint( array(
1571
	'description' => 'Create a comment as a reply to another comment.',
1572
	'group'       => 'comments',
1573
	'stat'        => 'comments:1:replies:new',
1574
1575
	'method'      => 'POST',
1576
	'path'        => '/sites/%s/comments/%d/replies/new',
1577
	'path_labels' => array(
1578
		'$site'       => '(int|string) Site ID or domain',
1579
		'$comment_ID' => '(int) The comment ID'
1580
	),
1581
1582
	'request_format' => array(
1583
		'content'   => '(HTML) The comment text.',
1584
//		@todo Should we open this up to unauthenticated requests too?
1585
//		'author'    => '(author object) The author of the comment.',
1586
	),
1587
1588
	'pass_wpcom_user_details' => true,
1589
	'can_use_user_details_instead_of_blog_membership' => true,
1590
1591
	'example_request'      => 'https://public-api.wordpress.com/rest/v1/sites/82974409/comments/29/replies/new',
1592
	'example_request_data' => array(
1593
		'headers' => array(
1594
			'authorization' => 'Bearer YOUR_API_TOKEN'
1595
		),
1596
		'body' => array(
1597
			'content' => 'This reply is very interesting. This is editing a comment reply via the API.',
1598
		)
1599
	)
1600
) );
1601
1602
new WPCOM_JSON_API_Update_Comment_Endpoint( array(
1603
	'description' => 'Edit a comment.',
1604
	'group'       => 'comments',
1605
	'stat'        => 'comments:1:POST',
1606
1607
	'method'      => 'POST',
1608
	'path'        => '/sites/%s/comments/%d',
1609
	'path_labels' => array(
1610
		'$site'       => '(int|string) Site ID or domain',
1611
		'$comment_ID' => '(int) The comment ID'
1612
	),
1613
1614
	'request_format' => array(
1615
		'date'    => "(ISO 8601 datetime) The comment's creation time.",
1616
		'content' => '(HTML) The comment text.',
1617
		'status'  => array(
1618
			'approved'   => 'Approve the comment.',
1619
			'unapproved' => 'Remove the comment from public view and send it to the moderation queue.',
1620
			'spam'       => 'Mark the comment as spam.',
1621
			'unspam'     => 'Unmark the comment as spam. Will attempt to set it to the previous status.',
1622
			'trash'      => 'Send a comment to the trash if trashing is enabled (see constant: EMPTY_TRASH_DAYS).',
1623
			'untrash'    => 'Untrash a comment. Only works when the comment is in the trash.',
1624
		),
1625
	),
1626
1627
	'example_request'      => 'https://public-api.wordpress.com/rest/v1/sites/82974409/comments/29',
1628
	'example_request_data' => array(
1629
		'headers' => array(
1630
			'authorization' => 'Bearer YOUR_API_TOKEN'
1631
		),
1632
		'body' => array(
1633
			'content' => 'This reply is now edited via the API.',
1634
			'status'  => 'approved',
1635
		)
1636
	)
1637
) );
1638
1639
new WPCOM_JSON_API_Update_Comment_Endpoint( array(
1640
	'description' => 'Delete a comment.',
1641
	'group'       => 'comments',
1642
	'stat'        => 'comments:1:delete',
1643
1644
	'method'      => 'POST',
1645
	'path'        => '/sites/%s/comments/%d/delete',
1646
	'path_labels' => array(
1647
		'$site'       => '(int|string) Site ID or domain',
1648
		'$comment_ID' => '(int) The comment ID'
1649
	),
1650
1651
	'example_request'      => 'https://public-api.wordpress.com/rest/v1/sites/82974409/comments/$comment_ID/delete',
1652
	'example_request_data' => array(
1653
		'headers' => array(
1654
			'authorization' => 'Bearer YOUR_API_TOKEN'
1655
		)
1656
	)
1657
) );
1658
1659
/**
1660
 * Taxonomy Management Endpoints
1661
 */
1662
new WPCOM_JSON_API_Get_Taxonomy_Endpoint( array(
1663
	'description' => 'Get information about a single category.',
1664
	'group'       => 'taxonomy',
1665
	'stat'        => 'categories:1',
1666
1667
	'method'      => 'GET',
1668
	'path'        => '/sites/%s/categories/slug:%s',
1669
	'path_labels' => array(
1670
		'$site'     => '(int|string) Site ID or domain',
1671
		'$category' => '(string) The category slug'
1672
	),
1673
1674
	'example_request'  => 'https://public-api.wordpress.com/rest/v1/sites/en.blog.wordpress.com/categories/slug:community'
1675
) );
1676
1677
new WPCOM_JSON_API_Get_Taxonomies_Endpoint( array(
1678
	'description' => "Get a list of a site's categories.",
1679
	'group'       => 'taxonomy',
1680
	'stat'        => 'categories',
1681
	'method'      => 'GET',
1682
	'path'        => '/sites/%s/categories',
1683
	'path_labels' => array(
1684
		'$site'     => '(int|string) Site ID or domain'
1685
	),
1686
	'query_parameters' => array(
1687
		'number'   => '(int=100) The number of categories to return. Limit: 1000.',
1688
		'offset'   => '(int=0) 0-indexed offset.',
1689
		'page'     => '(int) Return the Nth 1-indexed page of categories. Takes precedence over the <code>offset</code> parameter.',
1690
		'search'   => '(string) Limit response to include only categories whose names or slugs match the provided search query.',
1691
		'order'    => array(
1692
			'ASC'  => 'Return categories in ascending order.',
1693
			'DESC' => 'Return categories in decending order.',
1694
		),
1695
		'order_by' => array(
1696
			'name'  => 'Order by the name of each category.',
1697
			'count' => 'Order by the number of posts in each category.',
1698
		),
1699
	),
1700
	'response_format' => array(
1701
		'found'      => '(int) The number of categories returned.',
1702
		'categories' => '(array) Array of category objects.',
1703
	),
1704
	'example_request'  => 'https://public-api.wordpress.com/rest/v1/sites/en.blog.wordpress.com/categories/?number=5'
1705
) );
1706
1707
new WPCOM_JSON_API_Get_Taxonomies_Endpoint( array(
1708
	'description' => "Get a list of a site's tags.",
1709
	'group'       => 'taxonomy',
1710
	'stat'        => 'tags',
1711
	'method'      => 'GET',
1712
	'path'        => '/sites/%s/tags',
1713
	'path_labels' => array(
1714
		'$site'     => '(int|string) Site ID or domain'
1715
	),
1716
	'query_parameters' => array(
1717
		'number'   => '(int=100) The number of tags to return. Limit: 1000.',
1718
		'offset'   => '(int=0) 0-indexed offset.',
1719
		'page'     => '(int) Return the Nth 1-indexed page of tags. Takes precedence over the <code>offset</code> parameter.',
1720
		'search'   => '(string) Limit response to include only tags whose names or slugs match the provided search query.',
1721
		'order'    => array(
1722
			'ASC'  => 'Return tags in ascending order.',
1723
			'DESC' => 'Return tags in decending order.',
1724
		),
1725
		'order_by' => array(
1726
			'name'  => 'Order by the name of each tag.',
1727
			'count' => 'Order by the number of posts in each tag.',
1728
		),
1729
	),
1730
	'response_format' => array(
1731
		'found'    => '(int) The number of tags returned.',
1732
		'tags'     => '(array) Array of tag objects.',
1733
	),
1734
	'example_request'  => 'https://public-api.wordpress.com/rest/v1/sites/en.blog.wordpress.com/tags/?number=5'
1735
) );
1736
1737
new WPCOM_JSON_API_Get_Taxonomy_Endpoint( array(
1738
	'description' => 'Get information about a single tag.',
1739
	'group'       => 'taxonomy',
1740
	'stat'        => 'tags:1',
1741
1742
	'method'      => 'GET',
1743
	'path'        => '/sites/%s/tags/slug:%s',
1744
	'path_labels' => array(
1745
		'$site' => '(int|string) Site ID or domain',
1746
		'$tag'  => '(string) The tag slug'
1747
	),
1748
1749
	'example_request'  => 'https://public-api.wordpress.com/rest/v1/sites/en.blog.wordpress.com/tags/slug:wordpresscom'
1750
) );
1751
1752
new WPCOM_JSON_API_Update_Taxonomy_Endpoint( array(
1753
	'description' => 'Create a new category.',
1754
	'group'       => 'taxonomy',
1755
	'stat'        => 'categories:new',
1756
1757
	'method'      => 'POST',
1758
	'path'        => '/sites/%s/categories/new',
1759
	'path_labels' => array(
1760
		'$site' => '(int|string) Site ID or domain',
1761
	),
1762
1763
	'request_format' => array(
1764
		'name'        => '(string) Name of the category',
1765
		'description' => '(string) A description of the category',
1766
		'parent'      => '(int) ID of the parent category',
1767
	),
1768
1769
	'example_request'      => 'https://public-api.wordpress.com/rest/v1/sites/82974409/categories/new/',
1770
	'example_request_data' => array(
1771
		'headers' => array(
1772
			'authorization' => 'Bearer YOUR_API_TOKEN'
1773
		),
1774
		'body' => array(
1775
			'name' => 'Puppies',
1776
		)
1777
	)
1778
) );
1779
1780
new WPCOM_JSON_API_Update_Taxonomy_Endpoint( array(
1781
	'description' => 'Create a new tag.',
1782
	'group'       => 'taxonomy',
1783
	'stat'        => 'tags:new',
1784
1785
	'method'      => 'POST',
1786
	'path'        => '/sites/%s/tags/new',
1787
	'path_labels' => array(
1788
		'$site' => '(int|string) Site ID or domain',
1789
	),
1790
1791
	'request_format' => array(
1792
		'name'        => '(string) Name of the tag',
1793
		'description' => '(string) A description of the tag',
1794
	),
1795
1796
	'example_request'      => 'https://public-api.wordpress.com/rest/v1/sites/82974409/tags/new/',
1797
	'example_request_data' => array(
1798
		'headers' => array(
1799
			'authorization' => 'Bearer YOUR_API_TOKEN'
1800
		),
1801
		'body' => array(
1802
			'name' => 'Kitties'
1803
		)
1804
	)
1805
) );
1806
1807
new WPCOM_JSON_API_Update_Taxonomy_Endpoint( array(
1808
	'description' => 'Edit a tag.',
1809
	'group'       => 'taxonomy',
1810
	'stat'        => 'tags:1:POST',
1811
1812
	'method'      => 'POST',
1813
	'path'        => '/sites/%s/tags/slug:%s',
1814
	'path_labels' => array(
1815
		'$site' => '(int|string) Site ID or domain',
1816
		'$tag'  => '(string) The tag slug',
1817
	),
1818
1819
	'request_format' => array(
1820
		'name'        => '(string) Name of the tag',
1821
		'description' => '(string) A description of the tag',
1822
	),
1823
1824
	'example_request'      => 'https://public-api.wordpress.com/rest/v1/sites/82974409/tags/slug:testing-tag',
1825
	'example_request_data' => array(
1826
		'headers' => array(
1827
			'authorization' => 'Bearer YOUR_API_TOKEN'
1828
		),
1829
		'body' => array(
1830
			'description' => 'Kitties are awesome!'
1831
		)
1832
	)
1833
) );
1834
1835
new WPCOM_JSON_API_Update_Taxonomy_Endpoint( array(
1836
	'description' => 'Edit a category.',
1837
	'group'       => 'taxonomy',
1838
	'stat'        => 'categories:1:POST',
1839
1840
	'method'      => 'POST',
1841
	'path'        => '/sites/%s/categories/slug:%s',
1842
	'path_labels' => array(
1843
		'$site'     => '(int|string) Site ID or domain',
1844
		'$category' => '(string) The category slug',
1845
	),
1846
1847
	'request_format' => array(
1848
		'name'        => '(string) Name of the category',
1849
		'description' => '(string) A description of the category',
1850
		'parent'      => '(int) ID of the parent category',
1851
	),
1852
1853
	'example_request'      => 'https://public-api.wordpress.com/rest/v1/sites/82974409/categories/slug:testing-category',
1854
	'example_request_data' => array(
1855
		'headers' => array(
1856
			'authorization' => 'Bearer YOUR_API_TOKEN'
1857
		),
1858
		'body' => array(
1859
			'description' => 'Puppies are great!'
1860
		)
1861
	)
1862
) );
1863
1864
new WPCOM_JSON_API_Update_Taxonomy_Endpoint( array(
1865
	'description' => 'Delete a category.',
1866
	'group'       => 'taxonomy',
1867
	'stat'        => 'categories:1:delete',
1868
1869
	'method'      => 'POST',
1870
	'path'        => '/sites/%s/categories/slug:%s/delete',
1871
	'path_labels' => array(
1872
		'$site'     => '(int|string) Site ID or domain',
1873
		'$category' => '(string) The category slug',
1874
	),
1875
	'response_format' => array(
1876
		'slug'    => '(string) The slug of the deleted category',
1877
		'success' => '(bool) Was the operation successful?',
1878
	),
1879
1880
	'example_request'      => 'https://public-api.wordpress.com/rest/v1/sites/82974409/categories/slug:$category/delete',
1881
	'example_request_data' => array(
1882
		'headers' => array(
1883
			'authorization' => 'Bearer YOUR_API_TOKEN'
1884
		),
1885
	)
1886
) );
1887
1888
new WPCOM_JSON_API_Update_Taxonomy_Endpoint( array(
1889
	'description' => 'Delete a tag.',
1890
	'group'       => 'taxonomy',
1891
	'stat'        => 'tags:1:delete',
1892
1893
	'method'      => 'POST',
1894
	'path'        => '/sites/%s/tags/slug:%s/delete',
1895
	'path_labels' => array(
1896
		'$site' => '(int|string) Site ID or domain',
1897
		'$tag'  => '(string) The tag slug',
1898
	),
1899
	'response_format' => array(
1900
		'slug'    => '(string) The slug of the deleted tag',
1901
		'success' => '(bool) Was the operation successful?',
1902
	),
1903
1904
	'example_request'      => 'https://public-api.wordpress.com/rest/v1/sites/82974409/tags/slug:$tag/delete',
1905
	'example_request_data' => array(
1906
		'headers' => array(
1907
			'authorization' => 'Bearer YOUR_API_TOKEN'
1908
		),
1909
	)
1910
) );
1911
1912
new WPCOM_JSON_API_List_Roles_Endpoint( array(
1913
	'description' => 'List the user roles of a site.',
1914
	'group'       => '__do_not_document',
1915
	'stat'        => 'roles:list',
1916
1917
	'method'      => 'GET',
1918
	'path'        => '/sites/%s/roles',
1919
	'path_labels' => array(
1920
		'$site' => '(int|string) Site ID or domain',
1921
	),
1922
1923
	'query_parameters' => array(
1924
	),
1925
1926
	'response_format' => array(
1927
		'roles'  => '(array:role) Array of role objects.',
1928
	),
1929
1930
	'example_request'      => 'https://public-api.wordpress.com/rest/v1/sites/82974409/roles',
1931
	'example_request_data' => array(
1932
		'headers' => array(
1933
			'authorization' => 'Bearer YOUR_API_TOKEN'
1934
		),
1935
	)
1936
) );
1937
1938
new WPCOM_JSON_API_List_Users_Endpoint( array(
1939
	'description' => 'List the users of a site.',
1940
	'group'       => 'users',
1941
	'stat'        => 'users:list',
1942
1943
	'method'      => 'GET',
1944
	'path'        => '/sites/%s/users',
1945
	'path_labels' => array(
1946
		'$site' => '(int|string) Site ID or domain',
1947
	),
1948
1949
	'query_parameters' => array(
1950
		'number'   => '(int=20) Limit the total number of authors returned.',
1951
		'offset'   => '(int=0) The first n authors to be skipped in the returned array.',
1952
		'order'    => array(
1953
			'DESC' => 'Return authors in descending order.',
1954
			'ASC'  => 'Return authors in ascending order.',
1955
		),
1956
		'order_by' => array(
1957
			'ID'            => 'Order by ID (default).',
1958
			'login'         => 'Order by username.',
1959
			'nicename'      => "Order by nicename.",
1960
			'email'         => 'Order by author email address.',
1961
			'url'           => 'Order by author URL.',
1962
			'registered'    => 'Order by registered date.',
1963
			'display_name'  => 'Order by display name.',
1964
			'post_count'    => 'Order by number of posts published.',
1965
		),
1966
		'authors_only'      => '(bool) Set to true to fetch authors only',
1967
		'type'              => "(string) Specify the post type to query authors for. Only works when combined with the `authors_only` flag. Defaults to 'post'. Post types besides post and page need to be whitelisted using the <code>rest_api_allowed_post_types</code> filter.",
1968
		'search'            => '(string) Find matching users.',
1969
		'search_columns'    => "(array) Specify which columns to check for matching users. Can be any of 'ID', 'user_login', 'user_email', 'user_url', 'user_nicename', and 'display_name'. Only works when combined with `search` parameter. Default is [ 'user_login', 'user_nicename' ]",
1970
		'role'              => "(string) Specify a specific user role to fetch.",
1971
	),
1972
1973
	'response_format' => array(
1974
		'found'    => '(int) The total number of authors found that match the request (ignoring limits and offsets).',
1975
		'authors'  => '(array:author) Array of author objects.',
1976
	),
1977
1978
	'example_response' => '{
1979
		"found": 1,
1980
		"users": [
1981
			{
1982
				"ID": 78972699,
1983
				"login": "apiexamples",
1984
				"email": "[email protected]",
1985
				"name": "apiexamples",
1986
				"first_name": "",
1987
				"last_name": "",
1988
				"nice_name": "apiexamples",
1989
				"URL": "http://apiexamples.wordpress.com",
1990
				"avatar_URL": "https://1.gravatar.com/avatar/a2afb7b6c0e23e5d363d8612fb1bd5ad?s=96&d=identicon&r=G",
1991
				"profile_URL": "http://en.gravatar.com/apiexamples",
1992
				"site_ID": 82974409,
1993
				"roles": [
1994
					"administrator"
1995
				],
1996
				"is_super_admin": false
1997
			}
1998
		]
1999
	}',
2000
2001
	'example_request'      => 'https://public-api.wordpress.com/rest/v1/sites/82974409/users',
2002
	'example_request_data' => array(
2003
		'headers' => array(
2004
			'authorization' => 'Bearer YOUR_API_TOKEN'
2005
		),
2006
	)
2007
) );
2008
2009
new WPCOM_JSON_API_Update_User_Endpoint( array(
2010
	'description' => 'Delete a user of a site.',
2011
	'group'       => '__do_not_document',
2012
	'stat'        => 'users:delete',
2013
2014
	'method'      => 'POST',
2015
	'path'        => '/sites/%s/users/%d/delete',
2016
	'path_labels' => array(
2017
		'$site'       => '(int|string) Site ID or domain',
2018
		'$user_ID'    => '(int) User ID'
2019
	),
2020
2021
	'request_format' => array(
2022
		'reassign' => '(int) An optional id of a user to reassign posts to.',
2023
	),
2024
2025
	'response_format' => array(
2026
		'success' => '(bool) Was the deletion of user successful?',
2027
	),
2028
2029
	'example_request'      => 'https://public-api.wordpress.com/rest/v1/sites/82974409/users/1/delete',
2030
	'example_request_data' => array(
2031
		'headers' => array(
2032
			'authorization' => 'Bearer YOUR_API_TOKEN'
2033
		),
2034
	)
2035
) );
2036
2037
new WPCOM_JSON_API_Site_User_Endpoint( array(
2038
	'description' => 'Get details of a user of a site by ID.',
2039
	'group'       => '__do_not_document', //'users'
2040
	'stat'        => 'sites:1:user',
2041
	'method'      => 'GET',
2042
	'path'        => '/sites/%s/users/%d',
2043
	'path_labels' => array(
2044
		'$site'    => '(int|string) Site ID or domain',
2045
		'$user_id' => '(int) User ID',
2046
	),
2047
	'response_format' => WPCOM_JSON_API_Site_User_Endpoint::$user_format,
2048
	'example_request'      => 'https://public-api.wordpress.com/rest/v1/sites/30434183/user/23',
2049
	'example_request_data' => array(
2050
		'headers' => array(
2051
			'authorization' => 'Bearer YOUR_API_TOKEN'
2052
		),
2053
	),
2054
	'example_response'     => '{
2055
		"ID": 18342963,
2056
		"login": "binarysmash"
2057
		"email": false,
2058
		"name": "binarysmash",
2059
		"URL": "http:\/\/binarysmash.wordpress.com",
2060
		"avatar_URL": "http:\/\/0.gravatar.com\/avatar\/a178ebb1731d432338e6bb0158720fcc?s=96&d=identicon&r=G",
2061
		"profile_URL": "http:\/\/en.gravatar.com\/binarysmash",
2062
		"roles": [ "administrator" ]
2063
	}'
2064
) );
2065
2066
new WPCOM_JSON_API_Site_User_Endpoint( array(
2067
	'description' => 'Get details of a user of a site by login.',
2068
	'group'       => '__do_not_document', //'users'
2069
	'stat'        => 'sites:1:user',
2070
	'method'      => 'GET',
2071
	'path'        => '/sites/%s/users/login:%s',
2072
	'path_labels' => array(
2073
		'$site'    => '(int|string) Site ID or domain',
2074
		'$user_id' => '(string) User login',
2075
	),
2076
	'response_format' => WPCOM_JSON_API_Site_User_Endpoint::$user_format,
2077
	'example_request'      => 'https://public-api.wordpress.com/rest/v1/sites/30434183/user/login:binarysmash',
2078
	'example_request_data' => array(
2079
		'headers' => array(
2080
			'authorization' => 'Bearer YOUR_API_TOKEN'
2081
		),
2082
	),
2083
	'example_response'     => '{
2084
		"ID": 18342963,
2085
		"login": "binarysmash"
2086
		"email": false,
2087
		"name": "binarysmash",
2088
		"URL": "http:\/\/binarysmash.wordpress.com",
2089
		"avatar_URL": "http:\/\/0.gravatar.com\/avatar\/a178ebb1731d432338e6bb0158720fcc?s=96&d=identicon&r=G",
2090
		"profile_URL": "http:\/\/en.gravatar.com\/binarysmash",
2091
		"roles": [ "administrator" ]
2092
	}'
2093
) );
2094
2095
new WPCOM_JSON_API_Site_User_Endpoint( array(
2096
	'description' => 'Update details of a users of a site.',
2097
	'group'       => '__do_not_document', //'users'
2098
	'stat'        => 'sites:1:user',
2099
	'method'      => 'POST',
2100
	'path'        => '/sites/%s/users/%d',
2101
	'path_labels' => array(
2102
		'$site' => '(int|string) Site ID or domain',
2103
		'$user_id' => '(int) User ID',
2104
	),
2105
	'request_format'  => WPCOM_JSON_API_Site_User_Endpoint::$user_format,
2106
	'response_format' => WPCOM_JSON_API_Site_User_Endpoint::$user_format,
2107
	'example_request'      => 'https://public-api.wordpress.com/rest/v1/sites/30434183/user/23',
2108
	'example_request_data' => array(
2109
		'headers' => array(
2110
			'authorization' => 'Bearer YOUR_API_TOKEN'
2111
		),
2112
		'body' => array(
2113
			'roles' => array(
2114
				array(
2115
					'administrator',
2116
				)
2117
			),
2118
			'first_name' => 'Rocco',
2119
			'last_name' => 'Tripaldi',
2120
		)
2121
	),
2122
) );
2123
2124
new WPCOM_JSON_API_List_Invites_Endpoint( array(
2125
	'description' => 'List the invites of a site.',
2126
	'group'       => '__do_not_document',
2127
	'stat'        => 'invites:list',
2128
2129
	'method'      => 'GET',
2130
	'path'        => '/sites/%s/invites',
2131
	'path_labels' => array(
2132
		'$site' => '(int|string) Site ID or domain',
2133
	),
2134
2135
	'query_parameters' => array(
2136
		'number'   => '(int=25) Limit the total number of invites to be returned.',
2137
		'offset'   => '(int=0) The first n invites to be skipped in the returned array.',
2138
		'status'   => array(
2139
			'pending' => 'Return only pending invites.',
2140
			'all'     => 'Return all invites, pending and accepted, that have not been deleted.',
2141
		)
2142
	),
2143
2144
	'response_format' => array(
2145
		'found'   => '(int) The total number of invites found that match the request (ignoring limits and offsets).',
2146
		'invites' => '(array) Array of invites.',
2147
	),
2148
2149
	'example_request'      => 'https://public-api.wordpress.com/rest/v1/sites/82974409/invites',
2150
	'example_request_data' => array(
2151
		'headers' => array(
2152
			'authorization' => 'Bearer YOUR_API_TOKEN'
2153
		),
2154
	),
2155
	'example_response'     => '{
2156
		"ID": 18342963,
2157
		"login": "binarysmash"
2158
		"email": false,
2159
		"name": "binarysmash",
2160
		"URL": "http:\/\/binarysmash.wordpress.com",
2161
		"avatar_URL": "http:\/\/0.gravatar.com\/avatar\/a178ebb1731d432338e6bb0158720fcc?s=96&d=identicon&r=G",
2162
		"profile_URL": "http:\/\/en.gravatar.com\/binarysmash",
2163
		"roles": [ "administrator" ]
2164
	}'
2165
) );
2166
2167
new WPCOM_JSON_API_Update_Invites_Endpoint( array(
2168
	'description' => 'Delete an invite for a user to join a site.',
2169
	'group'       => '__do_not_document',
2170
	'stat'        => 'invites:1:delete',
2171
	'method'      => 'POST',
2172
	'path'        => '/sites/%s/invites/%s/delete',
2173
	'path_labels' => array(
2174
		'$site'      => '(int|string) Site ID or domain',
2175
		'$invite_id' => '(string) The ID of the invite'
2176
	),
2177
	'response_format' => array(
2178
		'invite_key' => '(string) Identifier for the deleted invite',
2179
		'deleted' => '(bool) Was the invitation removed?'
2180
	),
2181
2182
	'example_request' => 'https://public-api.wordpress.com/rest/v1/sites/30434183/invites/123523562/delete',
2183
2184
	'example_request_data' => array(
2185
		'headers' => array( 'authorization' => 'Bearer YOUR_API_TOKEN' ),
2186
	),
2187
) );
2188
2189
new WPCOM_JSON_API_Update_Invites_Endpoint( array(
2190
	'description' => 'Resend invitation for a user to join a site.',
2191
	'group'       => '__do_not_document',
2192
	'stat'        => 'invites:1',
2193
	'method'      => 'POST',
2194
	'path'        => '/sites/%s/invites/%s',
2195
	'path_labels' => array(
2196
		'$site'      => '(int|string) Site ID or domain',
2197
		'$invite_id' => '(string) The ID of the invite'
2198
	),
2199
	'response_format' => array(
2200
		'result' => '(bool) Was the invitation resent?'
2201
	),
2202
2203
	'example_request' => 'https://public-api.wordpress.com/rest/v1/sites/30434183/invites/123523562',
2204
2205
	'example_request_data' => array(
2206
		'headers' => array( 'authorization' => 'Bearer YOUR_API_TOKEN' ),
2207
	),
2208
) );
2209
2210
new WPCOM_JSON_API_Site_User_Endpoint( array(
2211
	'description' => 'Get details of a user of a site by ID.',
2212
	'group'       => '__do_not_document', //'users'
2213
	'stat'        => 'sites:1:user',
2214
	'method'      => 'GET',
2215
	'path'        => '/sites/%s/users/%d',
2216
	'path_labels' => array(
2217
		'$site'    => '(int|string) Site ID or domain',
2218
		'$user_id' => '(int) User ID',
2219
	),
2220
	'response_format' => WPCOM_JSON_API_Site_User_Endpoint::$user_format,
2221
	'example_request'      => 'https://public-api.wordpress.com/rest/v1/sites/30434183/user/23',
2222
	'example_request_data' => array(
2223
		'headers' => array(
2224
			'authorization' => 'Bearer YOUR_API_TOKEN'
2225
		),
2226
	),
2227
	'example_response'     => '{
2228
		"ID": 18342963,
2229
		"login": "binarysmash"
2230
		"email": false,
2231
		"name": "binarysmash",
2232
		"URL": "http:\/\/binarysmash.wordpress.com",
2233
		"avatar_URL": "http:\/\/0.gravatar.com\/avatar\/a178ebb1731d432338e6bb0158720fcc?s=96&d=identicon&r=G",
2234
		"profile_URL": "http:\/\/en.gravatar.com\/binarysmash",
2235
		"roles": [ "administrator" ]
2236
	}'
2237
) );
2238
2239
new WPCOM_JSON_API_Site_User_Endpoint( array(
2240
	'description' => 'Get details of a user of a site by login.',
2241
	'group'       => '__do_not_document', //'users'
2242
	'stat'        => 'sites:1:user',
2243
	'method'      => 'GET',
2244
	'path'        => '/sites/%s/users/login:%s',
2245
	'path_labels' => array(
2246
		'$site'    => '(int|string) Site ID or domain',
2247
		'$user_id' => '(string) User login',
2248
	),
2249
	'response_format' => WPCOM_JSON_API_Site_User_Endpoint::$user_format,
2250
	'example_request'      => 'https://public-api.wordpress.com/rest/v1/sites/30434183/user/login:binarysmash',
2251
	'example_request_data' => array(
2252
		'headers' => array(
2253
			'authorization' => 'Bearer YOUR_API_TOKEN'
2254
		),
2255
	),
2256
	'example_response'     => '{
2257
		"ID": 18342963,
2258
		"login": "binarysmash"
2259
		"email": false,
2260
		"name": "binarysmash",
2261
		"URL": "http:\/\/binarysmash.wordpress.com",
2262
		"avatar_URL": "http:\/\/0.gravatar.com\/avatar\/a178ebb1731d432338e6bb0158720fcc?s=96&d=identicon&r=G",
2263
		"profile_URL": "http:\/\/en.gravatar.com\/binarysmash",
2264
		"roles": [ "administrator" ]
2265
	}'
2266
) );
2267
2268
new WPCOM_JSON_API_Site_User_Endpoint( array(
2269
	'description' => 'Update details of a users of a site.',
2270
	'group'       => '__do_not_document', //'users'
2271
	'stat'        => 'sites:1:user',
2272
	'method'      => 'POST',
2273
	'path'        => '/sites/%s/users/%d',
2274
	'path_labels' => array(
2275
		'$site' => '(int|string) Site ID or domain',
2276
		'$user_id' => '(int) User ID',
2277
	),
2278
	'request_format'  => WPCOM_JSON_API_Site_User_Endpoint::$user_format,
2279
	'response_format' => WPCOM_JSON_API_Site_User_Endpoint::$user_format,
2280
	'example_request'      => 'https://public-api.wordpress.com/rest/v1/sites/30434183/user/23',
2281
	'example_request_data' => array(
2282
		'headers' => array(
2283
			'authorization' => 'Bearer YOUR_API_TOKEN'
2284
		),
2285
		'body' => array(
2286
			'roles' => array(
2287
				array(
2288
					'administrator',
2289
				)
2290
			),
2291
			'first_name' => 'Rocco',
2292
			'last_name' => 'Tripaldi',
2293
		)
2294
	),
2295
	'example_response'     => '{
2296
		"ID": 18342963,
2297
		"login": "binarysmash"
2298
		"email": false,
2299
		"name": "binarysmash",
2300
		"URL": "http:\/\/binarysmash.wordpress.com",
2301
		"avatar_URL": "http:\/\/0.gravatar.com\/avatar\/a178ebb1731d432338e6bb0158720fcc?s=96&d=identicon&r=G",
2302
		"profile_URL": "http:\/\/en.gravatar.com\/binarysmash",
2303
		"roles": [ "administrator" ]
2304
	}'
2305
) );
2306
2307
new WPCOM_JSON_API_Update_Invites_Endpoint( array(
2308
	'description' => 'Delete an invite for a user to join a site.',
2309
	'group'       => '__do_not_document',
2310
	'stat'        => 'invites:1:delete',
2311
	'method'      => 'POST',
2312
	'path'        => '/sites/%s/invites/%s/delete',
2313
	'path_labels' => array(
2314
		'$site'      => '(int|string) Site ID or domain',
2315
		'$invite_id' => '(string) The ID of the invite'
2316
	),
2317
	'response_format' => array(
2318
		'invite_key' => '(string) Identifier for the deleted invite',
2319
		'deleted' => '(bool) Was the invitation removed?'
2320
	),
2321
2322
	'example_request' => 'https://public-api.wordpress.com/rest/v1/sites/30434183/invites/123523562/delete',
2323
2324
	'example_request_data' => array(
2325
		'headers' => array( 'authorization' => 'Bearer YOUR_API_TOKEN' ),
2326
	),
2327
) );
2328
2329
new WPCOM_JSON_API_Update_Invites_Endpoint( array(
2330
	'description' => 'Resend invitation for a user to join a site.',
2331
	'group'       => '__do_not_document',
2332
	'stat'        => 'invites:1',
2333
	'method'      => 'POST',
2334
	'path'        => '/sites/%s/invites/%s',
2335
	'path_labels' => array(
2336
		'$site'      => '(int|string) Site ID or domain',
2337
		'$invite_id' => '(string) The ID of the invite'
2338
	),
2339
	'response_format' => array(
2340
		'result' => '(bool) Was the invitation resent?'
2341
	),
2342
2343
	'example_request' => 'https://public-api.wordpress.com/rest/v1/sites/30434183/invites/123523562',
2344
2345
	'example_request_data' => array(
2346
		'headers' => array( 'authorization' => 'Bearer YOUR_API_TOKEN' ),
2347
	),
2348
) );
2349
2350
new WPCOM_JSON_API_Site_Settings_Endpoint( array(
2351
	'description' => 'Get detailed settings information about a site.',
2352
	'group'	      => '__do_not_document',
2353
	'stat'        => 'sites:X',
2354
2355
	'method'      => 'GET',
2356
	'path'        => '/sites/%s/settings',
2357
	'path_labels' => array(
2358
		'$site' => '(int|string) Site ID or domain',
2359
	),
2360
2361
	'query_parameters' => array(
2362
		'context' => false,
2363
	),
2364
2365
	'response_format' => WPCOM_JSON_API_Site_Settings_Endpoint::$site_format,
2366
2367
	'example_request' => 'https://public-api.wordpress.com/rest/v1/sites/en.blog.wordpress.com/settings?pretty=1',
2368
) );
2369
2370
new WPCOM_JSON_API_Site_Settings_Endpoint( array(
2371
	'description' => 'Update settings for a site.',
2372
	'group'       => '__do_not_document',
2373
	'stat'        => 'sites:X',
2374
2375
	'method'      => 'POST',
2376
	'path'        => '/sites/%s/settings',
2377
	'path_labels' => array(
2378
		'$site' => '(int|string) Site ID or domain',
2379
	),
2380
2381
	'request_format'  => array(
2382
		'blogname'                     => '(string) Blog name',
2383
		'blogdescription'              => '(string) Blog description',
2384
		'default_pingback_flag'        => '(bool) Notify blogs linked from article?',
2385
		'default_ping_status'          => '(bool) Allow link notifications from other blogs?',
2386
		'default_comment_status'       => '(bool) Allow comments on new articles?',
2387
		'blog_public'                  => '(string) Site visibility; -1: private, 0: discourage search engines, 1: allow search engines',
2388
		'jetpack_sync_non_public_post_stati' => '(bool) allow sync of post and pages with non-public posts stati',
2389
		'jetpack_relatedposts_enabled' => '(bool) Enable related posts?',
2390
		'jetpack_relatedposts_show_headline' => '(bool) Show headline in related posts?',
2391
		'jetpack_relatedposts_show_thumbnails' => '(bool) Show thumbnails in related posts?',
2392
		'jetpack_protect_whitelist'    => '(array) List of IP addresses to whitelist',
2393
		'infinite_scroll'              => '(bool) Support infinite scroll of posts?',
2394
		'default_category'             => '(int) Default post category',
2395
		'default_post_format'          => '(string) Default post format',
2396
		'require_name_email'           => '(bool) Require comment authors to fill out name and email?',
2397
		'comment_registration'         => '(bool) Require users to be registered and logged in to comment?',
2398
		'close_comments_for_old_posts' => '(bool) Automatically close comments on old posts?',
2399
		'close_comments_days_old'      => '(int) Age at which to close comments',
2400
		'thread_comments'              => '(bool) Enable threaded comments?',
2401
		'thread_comments_depth'        => '(int) Depth to thread comments',
2402
		'page_comments'                => '(bool) Break comments into pages?',
2403
		'comments_per_page'            => '(int) Number of comments to display per page',
2404
		'default_comments_page'        => '(string) newest|oldest Which page of comments to display first',
2405
		'comment_order'                => '(string) asc|desc Order to display comments within page',
2406
		'comments_notify'              => '(bool) Email me when someone comments?',
2407
		'moderation_notify'            => '(bool) Email me when a comment is helf for moderation?',
2408
		'social_notifications_like'    => '(bool) Email me when someone likes my post?',
2409
		'social_notifications_reblog'  => '(bool) Email me when someone reblogs my post?',
2410
		'social_notifications_subscribe' => '(bool) Email me when someone follows my blog?',
2411
		'comment_moderation'           => '(bool) Moderate comments for manual approval?',
2412
		'comment_whitelist'            => '(bool) Moderate comments unless author has a previously-approved comment?',
2413
		'comment_max_links'            => '(int) Moderate comments that contain X or more links',
2414
		'moderation_keys'              => '(string) Words or phrases that trigger comment moderation, one per line',
2415
		'blacklist_keys'               => '(string) Words or phrases that mark comment spam, one per line',
2416
		'lang_id'                      => '(int) ID for language blog is written in',
2417
		'wga'                          => '(array) Google Analytics Settings',
2418
		'disabled_likes'               => '(bool) Are likes globally disabled (they can still be turned on per post)?',
2419
		'disabled_reblogs'             => '(bool) Are reblogs disabled on posts?',
2420
		'jetpack_comment_likes_enabled' => '(bool) Are comment likes enabled for all comments?',
2421
		'sharing_button_style'         => '(string) Style to use for sharing buttons (icon-text, icon, text, or official)',
2422
		'sharing_label'                => '(string) Label to use for sharing buttons, e.g. "Share this:"',
2423
		'sharing_show'                 => '(string|array:string) Post type or array of types where sharing buttons are to be displayed',
2424
		'sharing_open_links'           => '(string) Link target for sharing buttons (same or new)',
2425
		'twitter_via'                  => '(string) Twitter username to include in tweets when people share using the Twitter button',
2426
		'jetpack-twitter-cards-site-tag' => '(string) The Twitter username of the owner of the site\'s domain.',
2427
		'eventbrite_api_token'         => '(int) The Keyring token ID for an Eventbrite token to associate with the site',
2428
	),
2429
2430
	'response_format' => array(
2431
		'updated' => '(array)'
2432
	),
2433
2434
	'example_request' => 'https://public-api.wordpress.com/rest/v1/sites/en.blog.wordpress.com/settings?pretty=1',
2435
) );
2436
2437
/**
2438
 * Publicize Endpoints
2439
 */
2440
2441
new WPCOM_JSON_API_Get_Connections_Endpoint( array(
2442
	'description' => 'Get a list of a site\'s current Publicize connections to third-party services for the current user (personal or shared).',
2443
	'group'       => 'Publicize',
2444
	'stat'        => 'connections',
2445
	'method'      => 'GET',
2446
	'path'        => '/sites/%s/connections/',
2447
	'path_labels' => array(
2448
		'$site' => '(int|string) Site ID or domain',
2449
	),
2450
	'query_parameters' => array(
2451
		'service'   => "(string) Get Publicize connections for a specific service only. Default is 'all' but you can enter 'facebook', 'twitter', etc."
2452
	),
2453
	'response_format' => array(
2454
		'connections'    => '(array:object) List of Publicize connections'
2455
	)
2456
) );
2457
2458
new WPCOM_JSON_API_Get_Connection_Endpoint( array(
2459
	'description' => 'Get information about a specific Publicize connection.',
2460
	'group'       => 'Publicize',
2461
	'stat'        => 'connections:1',
2462
	'method'      => 'GET',
2463
	'path'        => '/sites/%s/connections/%d',
2464
	'path_labels' => array(
2465
		'$site'          => '(int|string) Site ID or domain',
2466
		'$connection_id' => '(int) The ID of the Publicize connection',
2467
	),
2468
	'response_format' => array(
2469
		'ID'               => '(int) Identifier for the Publicize connection',
2470
		'token_ID'         => '(int) Identifier for the Keyring token',
2471
		'conn_ID'          => '(int) Identifier for the Publicize connection',
2472
		'site_ID'          => '(int) Identifier for the Site',
2473
		'user_ID'          => '(int) Identifier for the Publicize connection user, or 0 if the connection is shared',
2474
		'shared'           => '(bool) Is this connection specific to the current user, or a shared one for the site?',
2475
		'service'          => '(string) An identifier for the type of service (facebook, linkedin, path, tumblr, etc)',
2476
		'label'            => '(string) Formatted nicename for the service.',
2477
		'issued'           => '(ISO 8601 datetime) When the conncetion was created',
2478
		'expires'          => '(ISO 8601 datetime) When the connection expires and needs to be refreshed',
2479
		'external_ID'      => '(string) An identifier for the user on the third-party service',
2480
		'external_name'    => '(string) Usually a username or login name.',
2481
		'external_display' => '(string) How the user prefers their name to be displayed on the third-party service.',
2482
		'URL'              => '(string|null) URL to the user\'s profile. NULL if there is no URL to link to.',
2483
		'status'           => '(string) The current status of the connection. "ok" for connections with no problems, and "broken" for connections that need fixed.',
2484
		'refresh_url'      => '(string) The URL to refresh a token if it is broken.',
2485
		'meta'             => '(object) Extra and optional metadata for the current Publicize connection',
2486
	)
2487
) );
2488
2489
new WPCOM_JSON_API_Delete_Connection_Endpoint( array(
2490
	'description' => 'Delete a publicize connection.',
2491
	'group'		  => 'Publicize',
2492
	'stat'		  => 'connections:1:delete',
2493
	'method'	  => 'POST',
2494
	'path'		  => '/sites/%s/connections/%d/delete',
2495
	'path_labels' => array(
2496
		'$site'          => '(int|string) Site ID or domain',
2497
		'$connection_id' => 'The ID of the connection',
2498
	),
2499
	'response_format' => array(
2500
		'ID'      => '(int) Identifier for the connection',
2501
		'deleted' => '(bool) Confirmation that the connection has been removed'
2502
	)
2503
) );
2504
2505
/**
2506
 * Sharing Button Endpoints
2507
 */
2508
2509
new WPCOM_JSON_API_Get_Sharing_Buttons_Endpoint( array(
2510
	'description' => 'Get a list of a site\'s sharing buttons.',
2511
	'group'       => '__do_not_document',
2512
	'stat'        => 'sharing-buttons',
2513
	'method'      => 'GET',
2514
	'path'        => '/sites/%s/sharing-buttons/',
2515
	'path_labels' => array(
2516
		'$site' => '(int|string) Site ID or domain',
2517
	),
2518
	'query_parameters' => array(
2519
		'enabled_only' => '(bool) If true, only enabled sharing buttons are included in the response',
2520
		'visibility'   => '(string) The type of enabled sharing buttons to filter by, either "visible" or "hidden"',
2521
	),
2522
	'response_format' => array(
2523
		'found'           => '(int) The total number of sharing buttons found that match the request.',
2524
 		'sharing_buttons' => '(array:object) Array of sharing button objects',
2525
	),
2526
	'example_request'      => 'https://public-api.wordpress.com/rest/v1/sites/30434183/sharing-buttons/',
2527
	'example_request_data' => array(
2528
		'headers' => array( 'authorization' => 'Bearer YOUR_API_TOKEN' ),
2529
	),
2530
	'example_response' => '{
2531
	"found": 1,
2532
	"sharing_buttons": [
2533
		{
2534
			"ID": "facebook",
2535
			"name": "Facebook"
2536
			"shortname": "facebook",
2537
			"custom": false,
2538
			"enabled": true,
2539
			"visibility": "visible",
2540
			"genericon": "\\f204"
2541
		}
2542
	]
2543
}'
2544
) );
2545
2546
new WPCOM_JSON_API_Get_Sharing_Button_Endpoint( array(
2547
	'description' => 'Get information about a single sharing button.',
2548
	'group'       => '__do_not_document',
2549
	'stat'        => 'sharing-buttons:1',
2550
	'method'      => 'GET',
2551
	'path'        => '/sites/%s/sharing-buttons/%s',
2552
	'path_labels' => array(
2553
		'$site'      => '(int|string) Site ID or domain',
2554
		'$button_id' => '(string) The button ID',
2555
	),
2556
	'response_format' => array(
2557
		'ID'           => '(int) Sharing button ID',
2558
		'name'         => '(string) Sharing button name, used as a label on the button itself',
2559
		'shortname'    => '(string) A generated short name for the sharing button',
2560
		'URL'          => '(string) The URL pattern defined for a custom sharing button',
2561
		'icon'         => '(string) URL to the 16x16 icon defined for a custom sharing button',
2562
		'genericon'    => '(string) Icon character in Genericons icon set',
2563
		'custom'       => '(bool) Is the button a user-created custom sharing button?',
2564
		'enabled'      => '(bool) Is the button currently enabled for the site?',
2565
		'visibility'   => '(string) If enabled, the current visibility of the sharing button, either "visible" or "hidden"',
2566
	),
2567
	'example_request' => 'https://public-api.wordpress.com/rest/v1/sites/30434183/sharing-buttons/facebook',
2568
	'example_request_data' => array(
2569
		'headers' => array( 'authorization' => 'Bearer YOUR_API_TOKEN' ),
2570
	),
2571
	'example_response' => '{
2572
	"ID": "facebook",
2573
	"name": "Facebook"
2574
	"shortname": "facebook",
2575
	"custom": false,
2576
	"enabled": true,
2577
	"visibility": "visible",
2578
	"genericon": "\\f204"
2579
}'
2580
) );
2581
2582
new WPCOM_JSON_API_Update_Sharing_Buttons_Endpoint( array(
2583
	'description' => 'Edit all sharing buttons for a site.',
2584
	'group'       => '__do_not_document',
2585
	'stat'        => 'sharing-buttons:X:POST',
2586
	'method'      => 'POST',
2587
	'path'        => '/sites/%s/sharing-buttons',
2588
	'path_labels' => array(
2589
		'$site'      => '(int|string) Site ID or domain',
2590
	),
2591
	'request_format' => array(
2592
		'sharing_buttons' => '(array:sharing_button) An array of sharing button objects',
2593
	),
2594
	'response_format' => array(
2595
		'success' => '(bool) Confirmation that all sharing buttons were updated as specified',
2596
		'updated' => '(array) An array of updated sharing buttons',
2597
	),
2598
	'example_request' => 'https://public-api.wordpress.com/rest/v1/sites/30434183/sharing-buttons',
2599
	'example_request_data' => array(
2600
		'headers' => array(
2601
			'authorization' => 'Bearer YOUR_API_TOKEN',
2602
		),
2603
		'body' => array(
2604
			'sharing_buttons' => array(
2605
				array(
2606
					'ID'         => 'facebook',
2607
					'visibility' => 'hidden',
2608
				)
2609
			)
2610
		)
2611
	),
2612
	'example_response' => '{
2613
	"success": true,
2614
	"updated": [
2615
		{
2616
			"ID": "facebook"
2617
			"name": "Facebook"
2618
			"shortname": "facebook"
2619
			"custom": false
2620
			"enabled": true,
2621
			"visibility": "hidden",
2622
			"genericon": "\f204"
2623
		}
2624
	]
2625
}'
2626
) );
2627
2628
new WPCOM_JSON_API_Update_Sharing_Button_Endpoint( array(
2629
	'description' => 'Create a new custom sharing button.',
2630
	'group'       => '__do_not_document',
2631
	'stat'        => 'sharing-buttons:new',
2632
	'method'      => 'POST',
2633
	'path'        => '/sites/%s/sharing-buttons/new',
2634
	'path_labels' => array(
2635
		'$site' => '(int|string) Site ID or domain',
2636
	),
2637
	'request_format' => array(
2638
		'name'       => '(string) The name for your custom sharing button, used as a label on the button itself',
2639
		'URL'        => '(string) The URL to use for share links, including optional placeholders (%post_title%, %post_url%, %post_full_url%, %post_excerpt%, %post_tags%)',
2640
		'icon'       => '(string) The full URL to a 16x16 icon to display on the sharing button',
2641
		'enabled'    => '(bool) Is the button currently enabled for the site?',
2642
		'visibility' => '(string) If enabled, the visibility of the sharing button, either "visible" (default) or "hidden"',
2643
	),
2644
	'response_format' => array(
2645
		'ID'           => '(string) Sharing button ID',
2646
		'name'         => '(string) Sharing button name, used as a label on the button itself',
2647
		'shortname'    => '(string) A generated short name for the sharing button',
2648
		'URL'          => '(string) The URL pattern defined for a custom sharing button',
2649
		'icon'         => '(string) URL to the 16x16 icon defined for a custom sharing button',
2650
		'genericon'    => '(string) Icon character in Genericons icon set',
2651
		'custom'       => '(bool) Is the button a user-created custom sharing button?',
2652
		'enabled'      => '(bool) Is the button currently enabled for the site?',
2653
		'visibility'   => '(string) If enabled, the current visibility of the sharing button, either "visible" or "hidden"',
2654
	),
2655
	'example_request' => 'https://public-api.wordpress.com/rest/v1/sites/30434183/sharing-buttons/new/',
2656
	'example_request_data' => array(
2657
		'headers' => array(
2658
			'authorization' => 'Bearer YOUR_API_TOKEN'
2659
		),
2660
		'body' => array(
2661
			'name'       => 'Custom',
2662
			'URL'        => 'https://www.wordpress.com/%post_name%',
2663
			'icon'       => 'https://en.wordpress.com/i/stats-icon.gif',
2664
			'enabled'    => true,
2665
			'visibility' => 'visible'
2666
		)
2667
	),
2668
	'example_response' => '{
2669
	"ID": "custom-123456789",
2670
	"name": "Custom"
2671
	"shortname": "ustom",
2672
	"url": "https://www.wordpress.com/%post_name%",
2673
	"icon": "https://en.wordpress.com/i/stats-icon.gif",
2674
	"custom": true,
2675
	"enabled": true,
2676
	"visibility": "visible"
2677
}'
2678
) );
2679
2680
new WPCOM_JSON_API_Update_Sharing_Button_Endpoint( array(
2681
	'description' => 'Edit a sharing button.',
2682
	'group'       => '__do_not_document',
2683
	'stat'        => 'sharing-buttons:1:POST',
2684
	'method'      => 'POST',
2685
	'path'        => '/sites/%s/sharing-buttons/%s',
2686
	'path_labels' => array(
2687
		'$site'      => '(int|string) Site ID or domain',
2688
		'$button_id' => '(string) The button ID',
2689
	),
2690
	'request_format' => array(
2691
		'name'       => '(string) Only if a custom sharing button, a new name used as a label on the button itself',
2692
		'URL'        => '(string) Only if a custom sharing button, the URL to use for share links, including optional placeholders (%post_title%, %post_url%, %post_full_url%, %post_excerpt%, %post_tags%)',
2693
		'icon'       => '(string) Only if a custom sharing button, the full URL to a 16x16 icon to display on the sharing button',
2694
		'enabled'    => '(bool) Is the button currently enabled for the site?',
2695
		'visibility' => '(string) If enabled, the visibility of the sharing button, either "visible" (default) or "hidden"',
2696
	),
2697
	'response_format' => array(
2698
		'ID'           => '(string) Sharing button ID',
2699
		'name'         => '(string) Sharing button name, used as a label on the button itself',
2700
		'shortname'    => '(string) A generated short name for the sharing button',
2701
		'URL'          => '(string) The URL pattern defined for a custom sharing button',
2702
		'icon'         => '(string) URL to the 16x16 icon defined for a custom sharing button',
2703
		'genericon'    => '(string) Icon character in Genericons icon set',
2704
		'custom'       => '(bool) Is the button a user-created custom sharing button?',
2705
		'enabled'      => '(bool) Is the button currently enabled for the site?',
2706
		'visibility'   => '(string) If enabled, the current visibility of the sharing button, either "visible" or "hidden"',
2707
	),
2708
	'example_request' => 'https://public-api.wordpress.com/rest/v1/sites/30434183/sharing-buttons/custom-123456789/',
2709
	'example_request_data' => array(
2710
		'headers' => array(
2711
			'authorization' => 'Bearer YOUR_API_TOKEN'
2712
		),
2713
		'body' => array(
2714
			'enabled' => false,
2715
		)
2716
	),
2717
	'example_response' => '{
2718
	"ID": "custom-123456789",
2719
	"name": "Custom"
2720
	"shortname": "ustom",
2721
	"custom": true,
2722
	"enabled": false,
2723
	"icon": "https://en.wordpress.com/i/stats-icon.gif",
2724
	"url": "https://www.wordpress.com/%post_name%"
2725
}'
2726
) );
2727
2728
new WPCOM_JSON_API_Delete_Sharing_Button_Endpoint( array(
2729
	'description' => 'Delete a custom sharing button.',
2730
	'group'		  => '__do_not_document',
2731
	'stat'		  => 'sharing-buttons:1:delete',
2732
	'method'	  => 'POST',
2733
	'path'        => '/sites/%s/sharing-buttons/%s/delete',
2734
	'path_labels' => array(
2735
		'$site'      => '(int|string) Site ID or domain',
2736
		'$button_id' => '(string) The button ID',
2737
	),
2738
	'response_format' => array(
2739
		'ID'      => '(int) The ID of the deleted sharing button',
2740
		'success' => '(bool) Confirmation that the sharing button has been removed'
2741
	),
2742
	'example_request' => 'https://public-api.wordpress.com/rest/v1/sites/30434183/sharing-buttons/custom-123456789/delete',
2743
	'example_request_data' => array(
2744
		'headers' => array( 'authorization' => 'Bearer YOUR_API_TOKEN' ),
2745
	),
2746
	'example_response' => '{
2747
	"ID": "custom-123456789",
2748
	"success": "true"
2749
}'
2750
) );
2751
2752
/*
2753
 * Custom CSS endpoints
2754
 */
2755
new WPCOM_JSON_API_Get_CustomCss_Endpoint( array (
2756
	'description'      => 'Retrieve custom-css data for a site.',
2757
	'group'            => '__do_not_document',
2758
	'stat'             => 'customcss:1:get',
2759
	'method'           => 'GET',
2760
	'min_version'      => '1.1',
2761
	'path'             => '/sites/%s/customcss',
2762
	'path_labels'      => array(
2763
		'$site' => '(string) Site ID or domain.',
2764
	),
2765
	'response_format'  => array(
2766
		'css' => '(string) The raw CSS.',
2767
		'preprocessor' => '(string) The name of the preprocessor if any.',
2768
		'add_to_existing' => '(bool) False to skip the existing styles.',
2769
	),
2770
	'example_request'  => 'https://public-api.wordpress.com/rest/v1.1/sites/12345678/customcss',
2771
	'example_response' => array(
2772
		array(
2773
			'css' => '.stie-title { color: #fff; }',
2774
			'preprocessor' => 'sass',
2775
			'add_to_existing' => 'true',
2776
		)
2777
	)
2778
) );
2779
2780
new WPCOM_JSON_API_Update_CustomCss_Endpoint( array (
2781
	'description'      => 'Set custom-css data for a site.',
2782
	'group'            => '__do_not_document',
2783
	'stat'             => 'customcss:1:update',
2784
	'method'           => 'POST',
2785
	'min_version'      => '1.1',
2786
	'path'             => '/sites/%s/customcss',
2787
	'path_labels'      => array(
2788
		'$site' => '(string) Site ID or domain.',
2789
	),
2790
	'request_format'  => array(
2791
		'css' => '(string) Optional. The raw CSS.',
2792
		'preprocessor' => '(string) Optional. The name of the preprocessor if any.',
2793
		'add_to_existing' => '(bool) Optional. False to skip the existing styles.',
2794
	),
2795
	'response_format'  => array(
2796
		'css' => '(string) The raw CSS.',
2797
		'preprocessor' => '(string) The name of the preprocessor if any.',
2798
		'add_to_existing' => '(bool) False to skip the existing styles.',
2799
	),
2800
	'example_request'  => 'https://public-api.wordpress.com/rest/v1.1/sites/12345678/customcss',
2801
	'example_request_data' => array(
2802
		'headers' => array( 'authorization' => 'Bearer YOUR_API_TOKEN' ),
2803
		'body' => array(
2804
			'css' => '.stie-title { color: #fff; }',
2805
			'preprocessor' => 'sass'
2806
		),
2807
	),
2808
	'example_response' => array(
2809
		array(
2810
			'css' => '.stie-title { color: #fff; }',
2811
			'preprocessor' => 'sass',
2812
			'add_to_existing' => 'true',
2813
		)
2814
	)
2815
) );
2816
2817
/*
2818
 * Custom Menus endpoints
2819
 */
2820
new WPCOM_JSON_API_Menus_New_Menu_Endpoint( array (
2821
	'method' => 'POST',
2822
	'description' => 'Create a new navigation menu.',
2823
	'group' => 'menus',
2824
	'stat' => 'menus:new-menu',
2825
	'path' => '/sites/%s/menus/new',
2826
	'path_labels' => array(
2827
		'$site' => '(int|string) Site ID or domain',
2828
	),
2829
	'request_format'  => array(
2830
		'name' => '(string) Name of menu',
2831
	),
2832
	'response_format' => array(
2833
		'id' => '(int) Newly created menu ID',
2834
	),
2835
	'example_request' => 'https://public-api.wordpress.com/rest/v1.1/sites/82974409/menus/new',
2836
	'example_request_data' => array(
2837
		'headers' => array( 'authorization' => 'Bearer YOUR_API_TOKEN' ),
2838
		'body' => array(
2839
			'name' => 'Menu 1'
2840
		)
2841
	),
2842
) );
2843
2844
new WPCOM_JSON_API_Menus_Update_Menu_Endpoint( array (
2845
	'method' => 'POST',
2846
	'description' => 'Update a navigation menu.',
2847
	'group' => 'menus',
2848
	'stat' => 'menus:update-menu',
2849
	'path' => '/sites/%s/menus/%d',
2850
	'path_labels' => array(
2851
		'$site' => '(int|string) Site ID or domain',
2852
		'$menu_id' => '(int) Menu ID',
2853
	),
2854
	'request_format'  => array(
2855
		'name'  => '(string) Name of menu',
2856
		'items' => '(array) A list of menu item objects.
2857
			<br/><br/>
2858
			Item objects contain fields relating to that item, e.g. id, type, content_id,
2859
			but they can also contain other items objects - this nesting represents parents
2860
			and child items in the item tree.'
2861
	),
2862
	'response_format' => array(
2863
		'menu' => '(object) Updated menu object',
2864
	),
2865
	'example_request' => 'https://public-api.wordpress.com/rest/v1.1/sites/82974409/menus/347757165',
2866
	'example_request_data' => array(
2867
		'headers' => array( 'authorization' => 'Bearer YOUR_API_TOKEN' ),
2868
		'body' => array(
2869
			'name' => 'Menu 1'
2870
		),
2871
	),
2872
) );
2873
2874
new WPCOM_JSON_API_Menus_List_Menus_Endpoint( array (
2875
	'method'=> 'GET',
2876
	'description' => 'Get a list of all navigation menus.',
2877
	'group' => 'menus',
2878
	'stat' => 'menus:list-menu',
2879
	'path' => '/sites/%s/menus',
2880
	'path_labels' => array(
2881
		'$site' => '(int|string) Site ID or domain',
2882
	),
2883
	'response_format' => array(
2884
		'menus' => '(array) A list of menu objects.<br/><br/>
2885
			A menu object contains a name, items, locations, etc.
2886
			Check the example response for the full structure.
2887
			<br/><br/>
2888
			Item objects contain fields relating to that item, e.g. id, type, content_id,
2889
			but they can also contain other items objects - this nesting represents parents
2890
			and child items in the item tree.',
2891
		'locations' => '(array) Locations where menus can be placed. List of objects, one per location.'
2892
	),
2893
	'example_request' => 'https://public-api.wordpress.com/rest/v1.1/sites/82974409/menus',
2894
	'example_request_data' => array(
2895
		'headers' => array( 'authorization' => 'Bearer YOUR_API_TOKEN' ),
2896
	),
2897
) );
2898
2899
new WPCOM_JSON_API_Menus_Get_Menu_Endpoint( array (
2900
	'method'=> 'GET',
2901
	'description' => 'Get a single navigation menu.',
2902
	'group' => 'menus',
2903
	'stat' => 'menus:get-menu',
2904
	'path' => '/sites/%s/menus/%d',
2905
	'path_labels' => array(
2906
		'$site' => '(int|string) Site ID or domain',
2907
		'$menu_id' => '(int) Menu ID',
2908
	),
2909
	'response_format' => array(
2910
		'menu' => '(object) A menu object.<br/><br/>
2911
			A menu object contains a name, items, locations, etc.
2912
			Check the example response for the full structure.
2913
			<br/><br/>
2914
			Item objects contain fields relating to that item, e.g. id, type, content_id,
2915
			but they can also contain other items objects - this nesting represents parents
2916
			and child items in the item tree.'
2917
	),
2918
	'example_request' => 'https://public-api.wordpress.com/rest/v1.1/sites/82974409/menus/347757165',
2919
	'example_request_data' => array(
2920
		'headers' => array( 'authorization' => 'Bearer YOUR_API_TOKEN' ),
2921
	),
2922
) );
2923
2924
new WPCOM_JSON_API_Menus_Delete_Menu_Endpoint( array (
2925
	'method' => 'POST',
2926
	'description' => 'Delete a navigation menu',
2927
	'group' => 'menus',
2928
	'stat' => 'menus:delete-menu',
2929
	'path' => '/sites/%s/menus/%d/delete',
2930
	'path_labels' => array(
2931
		'$site' => '(int|string) Site ID or domain',
2932
		'$menu_id' => '(int) Menu ID',
2933
	),
2934
	'response_format' => array(
2935
		'deleted' => '(bool) Has the menu been deleted?',
2936
	),
2937
	'example_request' => 'https://public-api.wordpress.com/rest/v1.1/sites/82974409/menus/$menu_id/delete',
2938
	'example_request_data' => array(
2939
		'headers' => array( 'authorization' => 'Bearer YOUR_API_TOKEN' ),
2940
	),
2941
) );
2942