REST API: Modify the structure of our DELETE responses to be more explicit.

Add the `deleted` property to the root of the Response object to communicate if the delete action was successful. Move the state of the resource prior to the delete request under a new `previous` property.  As a result DELETE responses are now structured like so:
 `{ deleted: true, previous: { ... } }`

Also includes helpful information to DELETE requests for resources that are not trashable.

Props timmydcrawford, rmccue, jnylen0.
Fixes #38494.
Built from https://develop.svn.wordpress.org/trunk@39126


git-svn-id: http://core.svn.wordpress.org/trunk@39066 1a063a9b-81f0-0310-95a4-ce76da25c4cd

wp-includes/rest-api/endpoints/class-wp-rest-comments-controller.php

@@ -83,6 +83,7 @@ class WP_REST_Comments_Controller extends WP_REST_Controller {
 				'permission_callback' => array( $this, 'delete_item_permissions_check' ),
 				'args'     => array(
 					'force'    => array(
+						'type'        => 'boolean',
 						'default'     => false,
 						'description' => __( 'Whether to bypass trash and force deletion.' ),
 					),
@@ -738,14 +739,15 @@ class WP_REST_Comments_Controller extends WP_REST_Controller {
 
 		$request->set_param( 'context', 'edit' );
 
-		$response = $this->prepare_item_for_response( $comment, $request );
-
 		if ( $force ) {
+			$previous = $this->prepare_item_for_response( $comment, $request );
 			$result = wp_delete_comment( $comment->comment_ID, true );
+			$response = new WP_REST_Response();
+			$response->set_data( array( 'deleted' => true, 'previous' => $previous->get_data() ) );
 		} else {
 			// If this type doesn't support trashing, error out.
 			if ( ! $supports_trash ) {
-				return new WP_Error( 'rest_trash_not_supported', __( 'The comment does not support trashing.' ), array( 'status' => 501 ) );
+				return new WP_Error( 'rest_trash_not_supported', __( 'The comment does not support trashing. Set force=true to delete.' ), array( 'status' => 501 ) );
 			}
 
 			if ( 'trash' === $comment->comment_approved ) {
@@ -753,6 +755,8 @@ class WP_REST_Comments_Controller extends WP_REST_Controller {
 			}
 
 			$result = wp_trash_comment( $comment->comment_ID );
+			$comment = get_comment( $comment->comment_ID );
+			$response = $this->prepare_item_for_response( $comment, $request );
 		}
 
 		if ( ! $result ) {

wp-includes/rest-api/endpoints/class-wp-rest-posts-controller.php

@@ -101,6 +101,7 @@ class WP_REST_Posts_Controller extends WP_REST_Controller {
 				'permission_callback' => array( $this, 'delete_item_permissions_check' ),
 				'args'                => array(
 					'force' => array(
+						'type'        => 'boolean',
 						'default'     => false,
 						'description' => __( 'Whether to bypass trash and force deletion.' ),
 					),
@@ -757,15 +758,17 @@ class WP_REST_Posts_Controller extends WP_REST_Controller {
 
 		$request->set_param( 'context', 'edit' );
 
-		$response = $this->prepare_item_for_response( $post, $request );
 
 		// If we're forcing, then delete permanently.
 		if ( $force ) {
+			$previous = $this->prepare_item_for_response( $post, $request );
 			$result = wp_delete_post( $id, true );
+			$response = new WP_REST_Response();
+			$response->set_data( array( 'deleted' => true, 'previous' => $previous->get_data() ) );
 		} else {
 			// If we don't support trashing for this type, error out.
 			if ( ! $supports_trash ) {
-				return new WP_Error( 'rest_trash_not_supported', __( 'The post does not support trashing.' ), array( 'status' => 501 ) );
+				return new WP_Error( 'rest_trash_not_supported', __( 'The post does not support trashing. Set force=true to delete.' ), array( 'status' => 501 ) );
 			}
 
 			// Otherwise, only trash if we haven't already.
@@ -776,6 +779,8 @@ class WP_REST_Posts_Controller extends WP_REST_Controller {
 			// (Note that internally this falls through to `wp_delete_post` if
 			// the trash is disabled.)
 			$result = wp_trash_post( $id );
+			$post = $this->get_post( $id );
+			$response = $this->prepare_item_for_response( $post, $request );
 		}
 
 		if ( ! $result ) {

wp-includes/rest-api/endpoints/class-wp-rest-revisions-controller.php

@@ -93,6 +93,13 @@ class WP_REST_Revisions_Controller extends WP_REST_Controller {
 				'methods'             => WP_REST_Server::DELETABLE,
 				'callback'            => array( $this, 'delete_item' ),
 				'permission_callback' => array( $this, 'delete_item_permissions_check' ),
+				'args'                => array(
+					'force' => array(
+						'type'        => 'boolean',
+						'default'     => false,
+						'description' => __( 'Required to be true, as resource does not support trashing.' ),
+					),
+				),
 			),
 			'schema' => array( $this, 'get_public_item_schema' ),
 		));
@@ -220,6 +227,16 @@ class WP_REST_Revisions_Controller extends WP_REST_Controller {
 	 * @return true|WP_Error True on success, or WP_Error object on failure.
 	 */
 	public function delete_item( $request ) {
+		$force = isset( $request['force'] ) ? (bool) $request['force'] : false;
+
+		// We don't support trashing for this resource type.
+		if ( ! $force ) {
+			return new WP_Error( 'rest_trash_not_supported', __( 'Revisions do not support trashing. Set force=true to delete.' ), array( 'status' => 501 ) );
+		}
+
+		$revision = $this->get_post( $request['id'] );
+		$previous = $this->prepare_item_for_response( $revision, $request );
+
 		$result = wp_delete_post( $request['id'], true );
 
 		/**
@@ -234,11 +251,13 @@ class WP_REST_Revisions_Controller extends WP_REST_Controller {
 		 */
 		do_action( 'rest_delete_revision', $result, $request );
 
-		if ( $result ) {
+		if ( ! $result ) {
-			return true;
-		} else {
 			return new WP_Error( 'rest_cannot_delete', __( 'The post cannot be deleted.' ), array( 'status' => 500 ) );
 		}
+
+		$response = new WP_REST_Response();
+		$response->set_data( array( 'deleted' => true, 'previous' => $previous->get_data() ) );
+		return $response;
 	}
 
 	/**

wp-includes/rest-api/endpoints/class-wp-rest-terms-controller.php

@@ -116,6 +116,7 @@ class WP_REST_Terms_Controller extends WP_REST_Controller {
 				'permission_callback' => array( $this, 'delete_item_permissions_check' ),
 				'args'                => array(
 					'force' => array(
+						'type'        => 'boolean',
 						'default'     => false,
 						'description' => __( 'Required to be true, as resource does not support trashing.' ),
 					),
@@ -566,14 +567,14 @@ class WP_REST_Terms_Controller extends WP_REST_Controller {
 
 		// We don't support trashing for this resource type.
 		if ( ! $force ) {
-			return new WP_Error( 'rest_trash_not_supported', __( 'Resource does not support trashing.' ), array( 'status' => 501 ) );
+			return new WP_Error( 'rest_trash_not_supported', __( 'Terms do not support trashing. Set force=true to delete.' ), array( 'status' => 501 ) );
 		}
 
 		$term = get_term( (int) $request['id'], $this->taxonomy );
 
 		$request->set_param( 'context', 'view' );
 
-		$response = $this->prepare_item_for_response( $term, $request );
+		$previous = $this->prepare_item_for_response( $term, $request );
 
 		$retval = wp_delete_term( $term->term_id, $term->taxonomy );
 
@@ -581,6 +582,9 @@ class WP_REST_Terms_Controller extends WP_REST_Controller {
 			return new WP_Error( 'rest_cannot_delete', __( 'The resource cannot be deleted.' ), array( 'status' => 500 ) );
 		}
 
+		$response = new WP_REST_Response();
+		$response->set_data( array( 'deleted' => true, 'previous' => $previous->get_data() ) );
+
 		/**
 		 * Fires after a single term is deleted via the REST API.
 		 *

wp-includes/rest-api/endpoints/class-wp-rest-users-controller.php

@@ -85,6 +85,7 @@ class WP_REST_Users_Controller extends WP_REST_Controller {
 				'permission_callback' => array( $this, 'delete_item_permissions_check' ),
 				'args'                => array(
 					'force'    => array(
+						'type'        => 'boolean',
 						'default'     => false,
 						'description' => __( 'Required to be true, as resource does not support trashing.' ),
 					),
@@ -114,6 +115,7 @@ class WP_REST_Users_Controller extends WP_REST_Controller {
 				'permission_callback' => array( $this, 'delete_current_item_permissions_check' ),
 				'args'                => array(
 					'force'    => array(
+						'type'        => 'boolean',
 						'default'     => false,
 						'description' => __( 'Required to be true, as resource does not support trashing.' ),
 					),
@@ -653,7 +655,7 @@ class WP_REST_Users_Controller extends WP_REST_Controller {
 
 		// We don't support trashing for this type, error out.
 		if ( ! $force ) {
-			return new WP_Error( 'rest_trash_not_supported', __( 'Users do not support trashing.' ), array( 'status' => 501 ) );
+			return new WP_Error( 'rest_trash_not_supported', __( 'Users do not support trashing. Set force=true to delete.' ), array( 'status' => 501 ) );
 		}
 
 		$user = get_userdata( $id );
@@ -670,7 +672,7 @@ class WP_REST_Users_Controller extends WP_REST_Controller {
 
 		$request->set_param( 'context', 'edit' );
 
-		$response = $this->prepare_item_for_response( $user, $request );
+		$previous = $this->prepare_item_for_response( $user, $request );
 
 		/** Include admin user functions to get access to wp_delete_user() */
 		require_once ABSPATH . 'wp-admin/includes/user.php';
@@ -681,6 +683,9 @@ class WP_REST_Users_Controller extends WP_REST_Controller {
 			return new WP_Error( 'rest_cannot_delete', __( 'The resource cannot be deleted.' ), array( 'status' => 500 ) );
 		}
 
+		$response = new WP_REST_Response();
+		$response->set_data( array( 'deleted' => true, 'previous' => $previous->get_data() ) );
+
 		/**
 		 * Fires immediately after a user is deleted via the REST API.
 		 *

wp-includes/version.php

@@ -4,7 +4,7 @@
  *
  * @global string $wp_version
  */
-$wp_version = '4.7-beta1-39125';
+$wp_version = '4.7-beta1-39126';
 
 /**
  * Holds the WordPress DB revision, increments when changes are made to the WordPress DB schema.