Add annotations REST API using custom post type.

[jaswrks]

Description

A REST API for annotations using a custom post type (take 2).
This PR is an alternative to annotations as comment types in #4386

API Documentation

See: https://speca.io/jaswrks/wp-annotation-posts

Conforms to the W3C annotation data model for annotation selectors and maintains some parity with the W3C annotation object model and protocol — while still doing things the WordPress way, which maximizes compatibility with WP REST API utilities, including those in JavaScript.

Tip: Review annotation creation examples to see how W3C annotation selectors work.

In the future, we could add an additional API controller that supports the JSON-LD annotation protocol, and simply map those requests to the official WP REST API internally; e.g., rest_do_request(). I've been over that protocol carefully. The API presented in this PR collects enough information, in the right way, to eventually support it if we'd like to.

For now, my feeling is that the JSON-LD protocol for annotations is still very young, and so are annotations in WordPress. From a practical standpoint, I suggest that we make the JSON-LD protocol a secondary objective once Gutenberg annotations have matured somewhat; i.e., to maximize compatibility with other annotation clients following the W3C.

How Has This Been Tested?

• PHPUnit (included with this PR)
• Postman (extract from docs)

Types of changes

My initial work on an API for annotations began in #3807. Since then, the main change has been to consider the W3C Annotation Data model. See note above regarding W3C conformity/parity.

There has also been some refactoring, code cleanup, docBlock, and unit test enhancement.

Checklist:

• My code is tested.
• My code follows the WordPress code style.
• My code follows has proper inline documentation.

Annotations as a Custom Post Type

Pros and cons. Can you think of any others?

Post Type Pros

• Leverages powerful extensibility features provided by WP core; e.g., register_post_type() and all that comes with a custom post type. So everything from the post type, to the capabilities, to statuses. All of that is well-supported by core and many plugins.

• Given post type extensibility, with this approach it seems less likely we'll run into technical roadblocks in the future. For example, what if annotations mature into something that requires additional features or functionality that's only feasible to develop in a registered post type?

Post Type Cons

• Post semantics are not as close to those of annotations. An annotation is more like a comment than anything else. It would be awesome if there was a register_comment_type() function supported by core. https://core.trac.wordpress.org/ticket/25674

• Given it's a 'post' type, we don't get to easily inherit functionality and semantics associated with comments. Such as spam-checking, flood-checking, content filters, author handling, notifications, etc. Therefore, adding an entirely new post type for annotations (much like comments) will require just a little more work if front-end annotations become a thing.

Back-End Annotation Permissions

Simplified Explanation

• If you can edit_posts, and you can edit_post (this post). Or, if you're the post author. Then you can read all, and create, edit, delete your own back-end annotations in this post.

• Administrators and Editors can edit and delete any post, so they can read, edit, and delete any annotation without restriction.

• Subscribers and the public have no access to back-end annotations whatsoever.

Front-End Annotation Permissions

Simplified Explanation

Almost exactly the same as comments. They adhere to the same rules with respect to comments being open, or not, and anyone who can moderate_comments can moderate front-end annotations.

Note: As a security precaution, front-end annotations are disabled internally for now. At this time, the main focus is on back-end annotations. Front-end annotations are simply being considered for the purpose of optimizing our approach and the object model.

TODO

• Collect feedback and decide which approach is better (post type vs. comment type).
• In the PR with the right approach, add additional unit tests, security review, polish.

[jaswrks]

Other Thoughts / Conclusions

See: #4386 (comment)

[jaswrks]

Ready for review.

[jaswrks]

Closing in favor of #4685

[atimmer]

I get the following error when requesting /wp-json/wp/v2/annotations using a GET request without arguments:

<b>Notice</b>:  Array to string conversion in <b>/srv/www/wordpress-default/public_html/wp-content/plugins/gutenberg/lib/class-wp-rest-annotations-controller.php</b> on line <b>440</b><br />. I think the official way to get parameters is to use the `get_param` method on the `$request`.

[jaswrks]

@atimmer Confirmed. Thanks for reporting that.

This seems to stem from rest_send_allow_header, where it's sending default collection parameters to a method that expects to be called on a POST request. I will take a closer look.