Over the weekend, the WP REST API team published a proposal to merge the API endpoints for content types into WordPress 4.7. This is the second in a two-part proposal, which merged the infrastructure for the API into core in October 2015. Since that time the team has worked on polishing the content endpoints and making changes to core that are necessary to support the API.
The endpoints proposed for merge include posts, comments, terms, users, meta, and settings management. This includes public access as well as authenticated access via the OAuth 1 protocol. The team selected OAuth 1 over the newer OAuth 2 protocol, because OAuth 2 requires HTTPS with a modern version of TLS. As WordPress core doesn’t require HTTPS, the team did not want to make it a requirement for using the API.
“This merge proposal represents a complete and functional Content API, providing the necessary endpoints for mobile apps and frontends, and lays the groundwork for future releases focused on providing a Management API interface for full site administration,” said Ryan McCue in the proposal posted on behalf of the WP REST API team.
Preliminary feedback in the comments so far has been supportive of merging the API, with a few WordPress contributors expressing concerns regarding the authentication scheme. WordPress sites don’t have a centralized OAuth server, which means those using the API to create applications would need to have those apps registered with every single WordPress site it connects to. To get around this, the WP REST API team created a brokered authentication solution with the main broker system running at apps.wp-api.org. The team is proposing brokered authentication for WordPress 4.8 to allow for more testing. Eventually, the broker would be hosted on WordPress.org.
“The concept of a third-party broker feels very antithetical to WordPress Core,” George Stephanis commented on the proposal. “To have to ping the third-party server for every login to check for invalidations of their applications, let alone the initial confirmation of an application … for me, it doesn’t pass the gut check.” Stephanis said he would rather see something similar to the Application Password System feature plugin that is being developed for core, as it provides a simple flow for applications to request passwords and get the generated passwords passed back. It’s also compatible with the legacy XML-RPC API.
WordPress lead developer Dion Hulse commented that he does not like the idea of having a third-party broker but thinks that Application Passwords would be worse than the complications that OAuth options introduce.
“At the end of the day moving towards OAuth is going to provide a far better developer and user experience for API clients,” Hulse said. “In an ideal world, a central provider wouldn’t be needed, but we don’t have a decentralized platform for WordPress yet, so there’s no other mechanism for WordPresses out there to be told the sort of information they need to know.”
WordPress project lead Matt Mullenweg commented on the proposal, citing authentication challenges as the primary reason he is not in favor of merging the endpoints into 4.7.
“Given the hurdles of authentication, I don’t think that bringing this into core provides benefits for WP beyond what the community gets from the plugin,” Mullenweg said. “I don’t believe in its current state the benefit outweighs the cost, and we should err on the side of simplicity.”
Mullenweg was also not convinced that brokered authentication is the best route to solve the problems with OAuth.
“I am not interested in hosting the centralized brokered authentication server on WordPress.org in the 4.8 timeframe, and hesitant about the implications it has for WP more broadly,” he said. “I do appreciate the thought that has been put into solving this tricky problem.”
The proposal is open for comments and the WP REST API team welcomes feedback in the #core-restapi Slack channel as well. They are particularly interested in getting security feedback on the REST API plugin and the OAuth plugin, which are both available on WordPress.org. If the endpoints are merged, the team plans to implement feedback throughout the next few weeks before 4.7 ships in early December.
“During the remaining parts of this release cycle and through into the 4.8 cycle, additional work will go into other parts of the API,” McCue said. “This includes further work and refinement on the broker authentication system, including work on WordPress.org infrastructure. Additionally, we plan to continue working on the Management API endpoints, including theme and appearance endpoints to support the Customizer team.”
The team outlined an iterative approach that would not include full wp-admin coverage at merge into 4.7, a controversial sticking point which contributors were divided on when they discussed the possibility of merging the endpoints earlier this year. They are proposing that the Management API endpoints and theme/appearance endpoints be maintained as separate feature projects on GitHub until they are ready for merge. Development related to the content endpoints would move from GitHub to Trac if the merge is approved.