In the earlier article WordPress JSON REST API (WP API) introduction, development prospects, and documentation translation plan, I gave a brief introduction to the WordPress JSON REST API. After that, I noticed from Baidu statistics that many readers had found that article through search. That earlier post also mentioned the plan to translate the WordPress JSON REST API documentation. This article is the first part of that translation plan and covers how to create, retrieve, edit, and delete posts with the WordPress JSON REST API.
Create a post
POST /postsAuthentication required.
Input
The incoming data parameter is used to create the post object. The data can be submitted as an HTTP multipart body, or it can be sent directly in JSON format. So the following two methods are equivalent.
Content-Type: application/x-www-form-urlencoded
data[title]=Hello%20World!&data[content_raw]=Content&data[excerpt_raw]=ExcerptContent-Type: application/json
{”title”:”Hello World!”,”content_raw”:”Content”,”excerpt_raw”:”Excerpt”}The data parameter should be an object containing the following key-value pairs.
title – the post title (string) required
content_raw – the post content (string) required
excerpt_raw – the post excerpt (string) optional
name – the post slug (string) optional
status – the post status, which can be: draft, publish, pending, future, private, or another custom post status. If the provided post status is future, you must also submit a date to use as the publish date. The default is draft. (string) optional
type – the post type, which can be: post, page, link, nav_menu_item, or another custom post type. The default is post. (string) optional
date – the local date and time the post was published. The date should be an RFC3339 timestamp (http://tools.ietf.org/html/rfc3339), for example: 2014-01-01T12:20:52Z. The default is the local date and time. (string) optional
date_gmt – the UTC date and time when the post was published. The date should be an RFC3339 timestamp. For example: 2014-01-01T12:20:52Z. The default is the current GMT date and time. (string) optional
author – the post author. The author can be an author ID or an author object. The default is the current author. (object | string) optional
password – the password used to protect the post. The default is an empty string. (string) optional
post_parent – the parent post ID. The default is 0. (integer) optional
post_format – the post format. The default is standard. (string) optional
menu_order – the page order value. The default is 0. (integer) optional
comment_status – the post comment status: open or closed. It determines whether users can leave comments. The default is the value of the default_comment_status setting, or closed. (string) optional
ping_status – the post ping status: open or closed. It determines whether users can submit pingbacks and trackbacks. The default is the value of the default_ping_status setting. (string) optional
sticky – the sticky status of the post: true or false. The default is false. (boolean) optional
post_meta – the post metadata. Post metadata should be an array containing one or more metadata objects. See the section about using key-value pairs to create post metadata through the endpoint. (array) optional
Return
If the post is created successfully, the endpoint returns a 201 status code indicating that the post has been created. The Location header contains the post URL, and for convenience the main post content is also included in the returned HTTP body.
If the client is not authorized, a 403 unauthorized status code is returned.
Retrieve posts
The posts endpoint returns a subset of the posts on the site.
GET /postsInput
Filter
The filter parameter controls the query parameters used for the post query.
Note: only “public” query parameters can be used through the API, because not every query parameter can be exposed safely. Only authorized users with the edit_posts capability can use “private” query parameters. Other query parameters can be registered through the query_vars filter, or through json_query_vars for API-specific query parameters.
For more available query parameters, refer to the official WordPress documentation. The following query parameters can be used through the API:
mppostswcatwithcommentswithoutcommentsssearchexactsentencecalendarpagepagedmoretbpbauthororderorderbyyearmonthnumdayhourminutesecondnamecategory_nametagfeedauthor_namestaticpagenamepage_iderrorcomments_popupattachmentattachment_idsubpostsubpost_idpreviewrobotstaxonomytermcpagepost_typeposts_per_page
If the user has already been authenticated, the following private query parameters can be used when publishing or editing posts:
offsetposts_per_archive_pageshowpostsnopagingpost_typepost_statuscategory__incategory__not_incategory__andtag__intag__not_intag__andtag_slug__intag_slug__andtag_idpost_mime_typepermcomments_per_pagepost__inpost__not_inpost_parentpost_parent__inpost_parent__not_in
GET /posts?filter[posts_per_page]=8&filter[order]=ASC
Context
The context parameter controls the type of data returned. See the available contexts for the retrieve-posts endpoint.
The default is view. (string)
Type
The type parameter specifies the post type to retrieve. It can be a string or an array of post types.
Note that arrays need to be defined with [] URL syntax. For example:
GET /posts?type[]=post&type[]=pageThe default is post. (string)
Return
If the requested posts exist, the endpoint returns a collection containing the requested posts.
Retrieve a single post
GET /posts/Input
context
The context parameter controls the format of the returned data. The available context values are:
view: the default context, used to output standard public-facing content.
edit: used when updating a post, and adds extra fields such as title_raw, content_raw, guid_raw, and custom fields to support post editing.
parent: a context used when the post is embedded inside another response, such as an author response. This reduces response size by using a minimal subset of the user data. Parent fields are returned as IDs instead of fully embedded objects so the response does not recurse through the entire hierarchy.
Return
If the requested post exists, the endpoint returns the requested post content. The returned fields depend on the context parameter.
Update a post
PUT /posts/Authentication required.
For compatibility reasons, this endpoint also accepts POST and PATCH. Because they all behave like PUT, the behavior is the same. It is recommended to use PUT when possible so the request follows REST conventions more closely.
Input
The data parameter includes the post ID that needs to be modified and the post object itself. The data can be submitted as an HTTP multipart body or directly in JSON format. See the examples under the create-post endpoint.
Just like publishing a post, the data parameter should be an object containing the key-value pairs listed above. The only extra part when editing a post is the post ID. The rest of the parameters are the same as the publish-post parameters, so I will not translate them one by one again here. Please refer to the key-value section under create-post.
Return
If the post is updated successfully, the endpoint returns a 201 status code indicating that the post has been updated. The Location header contains the post URL, and for convenience the main content is also shown in the returned body.
Delete a post
DELETE /posts/Authentication required.
Input
force
The force parameter controls whether the delete operation moves the post to the trash or deletes it permanently. The default is false, which means the post is moved to the trash. If it is set to true, the post is deleted permanently.
The default is false. (boolean)
Return
If deletion succeeds, the endpoint returns a 202 Accepted status code indicating that the post has been moved to the trash and can be permanently deleted later. If the request includes the force option, the endpoint returns a 200 OK status code indicating that the post has been deleted permanently.
If the client making the request is not authorized, a 403 error code is returned.
Retrieve post revisions
GET /posts//revisionsAuthentication required.
Return
If the request succeeds, the endpoint returns a 200 OK status code together with the revisions for the specified post.
If the client making the request is not authorized, a 403 error code is returned.
The content above is the Chinese translation of the post-related section of the WordPress JSON REST API (WP API) documentation. Because my English proficiency was limited at the time, there may still be errors or awkward phrasing in this translation. Feel free to point them out in the comments.
