WordPress.org

Make WordPress Core

Opened 15 months ago

Last modified 14 months ago

#39953 new enhancement

REST API: Add `date_floating` flag for posts

Reported by: jnylen0 Owned by:
Milestone: Awaiting Review Priority: normal
Severity: normal Version: 4.7
Component: REST API Keywords: needs-patch needs-unit-tests
Focuses: rest-api Cc:

Description

If the post_date_gmt field for a draft is 0000-00-00 00:00:00, WP core uses this as a marker to update the date of the draft to the current time whenever the post is updated. See ticket:5698#comment:14.

After #38883, there's not a way to determine whether a post is in this status (being able to use the date_gmt field is far more important). To restore this ability (and also add the ability to modify this status, which has never been present in the REST API), we need to add a new boolean field.

Storing this piece of information ("should we update the date of this post when it's saved?") in a separate field is the way this functionality should have been implemented from the beginning. It's probably too late to make this change for WP core, but we can at least provide a better design in the REST API.

Change History (8)

#1 @nerrad
15 months ago

I'm still trying to decipher what the purpose of this ticket is so looking for clarification.

So are you saying prior to the changes in #38883, the marker for whether a date got set to the current date when a draft post has its status changed is the post_date_gmt field being 0000-00-00 00:00:00 and AFTER the changes, that field has an actual specified date so there's no reliable marker to indicate updating the post to the current time of when the request is changing the post status?

If so, I'm not sure I like the idea of adding a flag. Instead I think the client should be responsible for setting the date period. I realize there may be implications with this stance but I don't want to respond to those until I know that my interpretation of the purpose for this ticket is correct.

#2 @jnylen0
15 months ago

When you create a draft in WP, whether via wp-admin or the REST API, it has a post_date_gmt value of 0000-00-00 00:00:00.

When you update the draft again, most importantly when you publish it, WP looks for this special value of post_date_gmt. If it's present, the post date is reset to the current timestamp (ref). Usually this is what you want (by default, a post is dated when it's published, not when its draft is created).

This behavior dates back to [8920], we can't change it in the WP internals.

If you update the date of the draft before publishing it, whether via wp-admin or the REST API, both the post_date and post_date_gmt fields are set to the new date you've specified. It's currently possible to undo this operation and set the date back to "floating" in wp-admin, but this hasn't been possible via any public release of the REST API.

After #38883, there's no way to tell via the REST API whether a post actually has an internal post_date_gmt value of 0000-00-00 00:00:00 or not, because if it does, we use the post_date field to calculate and provide a reasonable value for date_gmt. Guaranteeing a usable value in the date_gmt field is many times more useful than being able to know the status of this internal flag.

The new field proposed in this ticket would contain (and allow updating) this extra piece of information about the internal state of a post. If the new field has a value of true, then the post is a draft with a post_date_gmt value of 0000-00-00 00:00:00; otherwise, the new field is false.

Something like date_floating might make a better name for this field.

#3 follow-up: @nerrad
15 months ago

Thanks for explaining things, I was aware of how things worked on the WP side of things but clarifying what prompted the proposal in this ticket helps.

After the explanation I'm still wary of the need for an flag for auto-updating (whatever its called) on the endpoint. I believe we need to be careful about controlling behaviour of data properties based on some other flag in the package. It's more predictable and sets expectations better I think if the behaviour of the endpoint is that whatever you have the date set at on that field during an update is what gets saved.

Practically that means that its up to the consumer to save the current post_date_gmt value to the equivalent of "now" in the PUT call if they want that to be the publish date (when publishing) the post.

The other concern with setting a flag for controlling this behaviour is whether this is something applicable only on the post endpoint, or if its something that would apply to any custom post type (pages? menus?) If its only on the "posts" endpoint, then that does changing the schema for a post_type request depending on what "type" it is matter? If it's including it on every post_type response, is it a fair assumption that all post types will follow the same behaviour patterns as a post?

This ticket was mentioned in Slack in #core-restapi by kadamwhite. View the logs.


15 months ago

#5 in reply to: ↑ 3 @jnylen0
15 months ago

Replying to nerrad:

After the explanation I'm still wary of the need for an flag for auto-updating (whatever its called) on the endpoint. I believe we need to be careful about controlling behaviour of data properties based on some other flag in the package. It's more predictable and sets expectations better I think if the behaviour of the endpoint is that whatever you have the date set at on that field during an update is what gets saved.

This bundling of multiple pieces of information/functionality into a single field is the way WP currently behaves, and it's broken. It should have been a separate field from the start.

Practically that means that its up to the consumer to save the current post_date_gmt value to the equivalent of "now" in the PUT call if they want that to be the publish date (when publishing) the post.

This isn't going to work because it would break the default behavior where a post is dated when it is published.

The other concern with setting a flag for controlling this behaviour is whether this is something applicable only on the post endpoint, or if its something that would apply to any custom post type (pages? menus?) If its only on the "posts" endpoint, then that does changing the schema for a post_type request depending on what "type" it is matter? If it's including it on every post_type response, is it a fair assumption that all post types will follow the same behaviour patterns as a post?

This applies equally to every post type which has a concept of a draft (not attachment).

#6 @jnylen0
15 months ago

  • Summary changed from REST API: Add `date_auto_update` field for posts to REST API: Add `date_floating` flag for posts

#7 @joehoyle
14 months ago

-1 on the proposed solution, but I don't have a better suggestion right now. That's probably totally not very helpful, but I think this additional field would also suck.

#8 @jnylen0
14 months ago

@joehoyle what are your concerns with this approach? This is an extra piece of functionality, so it should have lived in an extra field from the beginning.

Note that without some kind of implementation for this feature it won't be possible to build a full-featured editor using the REST API.

Note: See TracTickets for help on using tickets.