Delete requests shouldn't return response with message body

[danielbachhuber]

In the user's controller, we return this response when the delete request is successful:

return array( 'message' => __( 'Deleted user' ) );

As a matter of practice, I don't think we should ever return a "message" in a 2xx response. "Success" is implied by the response code, and it's inconsistent generally.

@WP-API/amigos opinions?

[joehoyle]

Yup, agreed - success is 200

[rmccue]

We should return a response here for sure, whether it's a message or not I'm not sure. RFC7231 notes:

If a DELETE method is successfully applied, the origin server SHOULD
send [...] a 200 (OK) status code if the action has been enacted and the
response message includes a representation describing the status.

[rachelbaker]

For reference other APIs handle DELETE requests both ways.

The Github API returns a 204 response for DELETE requests: https://developer.github.com/v3/activity/notifications/#delete-a-thread-subscription

The Stripe API returns a response message: https://stripe.com/docs/api#delete_card

[rmccue]

So, here's a thought: what if we return the post data, along with the deleted status? Something like:

{
    "deleted": false,
    "data": { ... }
}

(Whether a post is trashed or not is indicated by status: "trash")

This means you can do a couple of things:

• You now know exactly whether the post is deleted or trashed
• For trashed posts, it's simple to untrash it (POST {data._links.self} with the old status)
• For deleted posts, you have the full post data if you want to offer an "undo" link (that could recreate the post)

I think this makes sense if we're going to return data, since we should be doing something useful. For reference, Twitter does the same if you delete a tweet.

[danielbachhuber]

I like the idea of returning the post data. I don't like this new response format where the actual data is in a data attribute.

[rmccue]

I don't like this new response format where the actual data is in a data attribute.

Yeah, not a fan either. Should we include a deleted: false at all, or just infer that from the response code?

[danielbachhuber]

Should we include a deleted: false at all, or just infer that from the response code?

I think you'd infer from the response code, but a 200 for both trashed and deleted could be confusing.

Which begs the question: why should we permit trashing, or even default to trashing, with a DELETE request? I'd think that trashing is PUT post_status=trash, and we keep DELETE semantically clean.

[nacin]

That's an interesting thought. I wonder how else others treat DELETE, though. In many systems, no delete is permanent. It's either recoverable (trash etc) or logged (audit etc). Is there a standard way to handle these? It's not like "trash" vs "delete" is a WordPress-specific concept.