[wp-trac] [WordPress Trac] #63928: Add additional fields to the `/wp-json/wp/v2/comments` endpoints

[WordPress Trac]

#63928: Add additional fields to the `/wp-json/wp/v2/comments` endpoints
--------------------------------------+------------------------------
 Reporter:  hannahtinkler             |       Owner:  hannahtinkler
     Type:  enhancement               |      Status:  assigned
 Priority:  normal                    |   Milestone:  Awaiting Review
Component:  REST API                  |     Version:  trunk
 Severity:  normal                    |  Resolution:
 Keywords:  has-patch has-unit-tests  |     Focuses:  rest-api
--------------------------------------+------------------------------

Comment (by rmccue):

 Replying to [comment:3 hannahtinkler]:
 > I can't see anything in `_links` that would indicate the authenticated
 user is able to edit the given comment - have I misunderstood?

 The idiomatic approach to this for the basic CRUD operations is to check
 the `Allow` header for an item - eg if it contains `PUT`, then edits are
 allowed. This is [https://github.com/WordPress/wordpress-
 develop/blob/7badd6df9905346023b8c7ee7a65d0eda92b29e2/src/wp-includes
 /rest-api.php#L854 generated using the permission callbacks], combined
 with whether the callback is actually registered.

 Those headers are embedded for `self` via `targetHints`, so you can check
 `_links.self.0.targetHints` to see if it contains `PUT`. This is new as of
 6.7 as @swissspidy mentions (#61739); older sites will only have it
 available on the individual endpoint `Allow` headers.

 For custom actions beyond CRUD/REST verbs, the pattern we use in other
 places (eg the posts controller) is [https://github.com/WordPress
 /wordpress-develop/blob/7badd6df9905346023b8c7ee7a65d0eda92b29e2/src/wp-
 includes/rest-api/endpoints/class-wp-rest-posts-controller.php#L2279 a
 self link with custom relations] like `https://api.w.org/action-{name}` -
 I don't think that's necessary here, but could be if eg core had a
 separate cap for spamming a comment vs editing it.

 > > Ditto here, can't this be done by embedding the `up` link?
 > Do you mean re-using the `_links.up.href` value for `post_details.link`
 in the response, or using the `_links.up.href` value in the app to request
 the post information?

 The `up` link contains the parent post, so setting `?_embed` (or
 `?_embed[]=up`) will bring the post's details in too, eg
 https://wordpress.org/news/wp-json/wp/v2/comments?_embed[]=up has
 `_embedded.up.0` for the post's details.

 > Comments render in the WordPress app in a list; the team's intention is
 to use this data in a the list along side each comment. Supplying a link
 to retrieve the children belonging to the current user would require the
 app to make an extra call per comment displayed, which would not be ideal
 for performance or network usage.

 Generally, we try and keep the data as a clean representation of the
 objects stored in WP, and non-client-specific. This data might make sense
 for the Automattic app, but would cause extra database queries for
 ''every'' client, even those that don't need this data.

 We could potentially add a custom link relation here - it's a combination
 of `replies` and `me` so I don't think there's a registered one - with
 targetHints including X-WP-Total. You could then detect if there's a reply
 by checking if X-WP-Total > 0. (We actually don't have a `replies` link at
 all right now which we probably should.)

 That said, it's relatively expensive to look up and it's very specific to
 a particular design, so again I'm not sure it's appropriate to include.

 You could potentially pull the comments list + batch request for
 `/comments?parent={id}&author={userid}` as a way to do this in only two
 HTTP requests.

-- 
Ticket URL: <https://core.trac.wordpress.org/ticket/63928#comment:7>
WordPress Trac <https://core.trac.wordpress.org/>
WordPress publishing platform