I think this would be better in a sibling property to _links, _actions, or something like that. _links is entirely used as a list of shortcuts to related information about the current object, adding in "here is an action the current user can perform" is confusing.

This would have the added benefit that such information could be omitted using _fields when the client does not need to know about actions

I think this would be better in a sibling property to _links, _actions, or something like that. _links is entirely used as a list of shortcuts to related information about the current object, adding in "here is an action the current user can perform" is confusing.

Can you point me to the existing spec where this is documented?

Can you point me to the existing spec where this is documented?

It isn't documented as far as I'm aware, this is just how _links seems to be used in the core REST API. It's suggested by the name, too: a link is something you click (or in HTTP verbs, something you GET), it's not a thing that you POST.

As far as adhering to the JSON API spec goes, I'm fine with using something that exists within the spec, if that fits our requirements. If not, I'm 💯 in favour of doing something that works, rather than something that's shoe-horned into a vaguely related structure.

It isn't documented as far as I'm aware, this is just how _links seems to be used in the core REST API.

_links is an implementation of HAL. targetSchema is a part of the current JSON Hyper-Schema spec.

If not, I'm 💯 in favour of doing something that works, rather than something that's shoe-horned into a vaguely related structure.

I'm not particularly interested in spending a ton of time bikeshedding an alternative spec. Can you describe the alternative implementation you'd accept?

cc @TimothyBJacobs for any thoughts he has.

Sure, here's a rough idea of something I think would be extensible, would clearly show the difference between _links and _actions.

In the schema, _actions would be defined as an array of all the possible actions, with a description of what they're for, and what they're related to, like so:

{
	"routes": {
		"/wp/v2/posts/(?P<id>[\\d]+)": {
			"endpoints": [
				{
					"methods": [ "POST", "PUT", "PATCH" ],
					"args": {
						// ...
					},
					"_actions": {
						"wp:sticky": {
							"title": "Sticky Post",
							"description": "Whether the current user can sticky the post or not",
							"targetSchema": {
								// Something in here about being related to the "sticky" property.
							}
						}
					}
				},
			],
		},
	},
}

Then, in the post object, the _actions property would define whether each action is available or not:

{
	"id": 1,
	// ...
	"_actions": {
		"wp:sticky": true,
	},
}

Alternatively, _actions could be an array of available actions, the difference seems to mostly be a choice of style:

{
	"id": 1,
	// ...
	"_actions": [
		"wp:sticky",
	],
}

Again, I'm strongly opposed to inventing a new spec when the existing spec is sufficient. In inventing a new spec, we'll need to go through multiple iterations of relearning past mistake/decision cycles. This doesn't seem like a judicious use of our time.

To address response size concerns, what if we only included these action links if context=edit?

I agree with @danielbachhuber. I don't see why including them in a separate "magic" field makes much sense. As I mentioned earlier, we can definitely omit the description fields which would considerably reduce the response size.

We've talked in #core-restapi a few times about adding links to the actual schemas. We could revisit this and try to land it for 5.0. This would allow us to replace the entire property description with a $ref like "$ref": "https://example.org/wp-json/wp/v2/?_method=OPTIONS&context=schema#/properties/sticky"

I also think including the links only if the context=edit makes a lot of sense as well. However, these can be added to the $schema document like this:

{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "title": "post",
  "type": "object",
  "properties": {
    "date": {
      "description": "The date the object was published, in the site's timezone.",
      "type": "string",
      "format": "date-time",
      "context": [
        "view",
        "edit",
        "embed"
      ]
    }
  },
  "links": [
    {
      "rel": "https://api.w.org/action-sticky",
      "href": "https://actualwebsite.com/wp-json/wp/v2/posts/{id}",
      "targetSchema": {
        "type": "object",
        "properties": {
          "sticky": {
            "$ref": "#/properties/sticky"
          }
        }
      }
    }
  ]
}

Our response could possibly then look something like.

{
  "_links": {
    "self": [],
    "wp:action-sticky": [
      {
        "href": "https://w.org/wp-json/wp/v2/posts/5"
      }
    ]
  }
}

However, we are not currently using this pattern anywhere else and we are introducing concepts like URI Templates and JSON Pointers, which while I'd be in favor of the API supporting, are not things we have looked at before.

To address response size concerns, what if we only included these action links if context=edit?

Yah, that'd be fine. I don't think there's a need for them in other contexts, we can always add it to them if there is. That's not really the issue, though.

The specific concern I have is that, when reading these new links, there's nothing to suggest what they mean, or how you use them. The same problem exists in @TimothyBJacobs' example: there's nothing to suggest what wp:action-sticky means, someone might guess it's related to the https://api.w.org/action-sticky thing in the schema, but I wouldn't rely on that. Even if they do, there's still nothing to tell them what it actually means.

The problem we need to solve is that there are pieces of UI that should only be displayed when a certain set of conditions are met: we want to be calculating those conditions on the server, rather than leaving it up to the client. targetSchema is nice, but it's a super complex way making available what are essentially a list of flags.

So, here's what I would like to see:

• The post object returning a list of these flags.
• The schema containing a description of the list, and of each flag.

_actions happens to be the name I gave that list in my earlier example, but I have no attachment to that: if there's a spec that more readily fits this, then use that. If targetSchema can be adjusted to do those things, then use it.

If there isn't a spec, then we can just make something that works, and iterate it on it later if needed.

@pento I'm not sure I follow your specific recommendation. What do you think about cce57b8? Or, if there's other changes you'd like to make, can you communicate them in a pull request against this branch?

I disagree. If you understand what targetSchema means, then it is immediately obvious what is going on. Gutenberg is filled with dozens of these technical hurdles that aren't immediately obvious to WordPress developers until you understand what a HoC is, or Slot & Fill, etc... The same thing is true with a number of patterns in WordPress core as well.

I also disagree that it is super complex. Its a fairly pattern of representing what the target resource looks like and is certainly no more complex than many other G7g patterns that are necessary to fulfill a complex requirement.

To clarify my own position: I'm open to being convinced there is an implementation superior to that proposed on this pull request. However, at this point, I'm unclear as to what the alternative implementation is, and how it's functionally better.

From my perspective, the targetSchema implementation on this pull request is correct because:

1. It conveys the information needed by the client.
2. It follows an existing, documented spec that much of the REST API already follows.

In case it wasn’t clear, I of course have no issue with some other mechanism being used to indicate what actions are available, but I very much do not want to see WordPress adopt another standard in a weird way that isn’t really applicable and break the purpose of it being standard without a very good reason. And I don’t think that targetSchema is complicated enough to warrant that breakage.

Thank you for the discussion, @danielbachhuber and @TimothyBJacobs. cce57b8 is a step in a good direction. I've opened #6613 with some small tweaks, but I think we can go with this.

Thanks @pento.

What is the best method to remove 'Sticky' option/toggle from Posts globally now?