REST API Merge Proposal, Part 2: Content API

Hi everyone, it’s your friendly REST APIREST API The REST API is an acronym for the RESTful Application Program Interface (API) that uses HTTP requests to GET, PUT, POST and DELETE data. It is how the front end of an application (think “phone app” or “website”) can communicate with the data store (think “database” or “file system”) https://developer.wordpress.org/rest-api/. team here with our second merge proposal for WordPress coreCore Core is the set of software required to run WordPress. The Core Development Team builds WordPress.. (WordPress 4.4 included the REST API Infrastructure, if you’d like to check out our previous merge proposal.) Even if you’re familiar with the REST API right now, we’ve made some changes to how the project is organised, so it’s worth reading everything here.

(If you haven’t done so already, now would be a great time to install the REST API and OAuth plugins from WordPress.orgWordPress.org The community site where WordPress code is created and shared by the users. This is where you can download the source code for WordPress core, plugins and themes as well as the central location for community conversations and organization. https://wordpress.org/.)

A brief history of the REST API

The REST API was created as a proof-of-concept by Ryan McCue (hey, that’s me!) at the WordPress Contributor Summit in 2012, but the project kicked off during the 2013 Google Summer of Code. The end result was Version 1.0, which grew into a community supported initiative that saw adoption and provided for a solid learning platform. The team used Version 1 to test out the fundamental ideas behind the APIAPI An API or Application Programming Interface is a software intermediary that allows programs to interact with each other and share data in limited, clearly defined ways., and then iterated with Version 2, which made some major breaking changes, including explicit versioning, the introduction of namespacing for forwards compatibility, and a restructure of the internals. Version 2 also led to the infrastructure of the REST API being committed to WordPress core in 4.4.

This infrastructure is the core of the REST API, and provides the external interface to send and receive RESTful HTTPHTTP HTTP is an acronym for Hyper Text Transfer Protocol. HTTP is the underlying protocol used by the World Wide Web and this protocol defines how messages are formatted and transmitted, and what actions Web servers and browsers should take in response to various commands. requests. Since shipping in 4.4, the infrastructure is now used by WordPress Core for oEmbed responses, and by plugins like WooCommerce and Jetpack, enabling anyone to create their own REST API endpoints.

The team has also been hard at work on the API endpoints. This has included core changes to WordPress to support the API, including deeper changes to both settings and meta.

Today the REST API team is proposing the inclusion of a collection of endpoints that we term the “Content API” into WordPress Core.

Proposals for Merge

Content Endpoints

For WordPress 4.7 the API team proposes to merge API endpoints for WordPress content types. These endpoints provide machine-readable external access to your WordPress site with a clear, standards-driven interface, allowing new and innovative apps for interacting with your site. These endpoints support all of the following:

  • Content:
    • Posts: Read and write access to all post data, for all types of post-based data, including pages and media.
    • Comments: Read and write access to all comment data. This includes pingbacks and trackbacks.
    • Terms: Read and write access to all term data.
    • Users: Read and write access to all user data. This includes public access to some data for post authors.
    • MetaMeta Meta is a term that refers to the inside workings of a group. For us, this is the team that works on internal WordPress sites like WordCamp Central and Make WordPress.: Read and write access to metadata for posts, comments, terms, and users, on an opt-in basis from plugins.
  • Management:
    • Settings: Read and write access to settings, on an opt-in basis from plugins and core. This enables API management of key site content values that are technically stored in options, such as site title and byline.

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.

Content API endpoints support both public and authenticated access. Authenticated access allows both read and write access to anything your user has access to, including post meta and settings. Public access is available for any already-public data, such as posts, terms, and limited user data for published post authors. To avoid potential privacy issues we’ve taken pains to ensure that everything we’re exposing is already public, and the API uses WordPress’ capability system extensively to ensure that all data is properly secured.

Just like the rest of WordPress, the Content API is fully extensibleExtensible This is the ability to add additional functionality to the code. Plugins extend the WordPress core software., supporting custom post meta, as well as allowing more complex data to be added via register_rest_field. The API is built around standard parts of WordPress, including the capability system and filters, so extending the API in plugins should feel as familiar to developers as extending any other part of WordPress.

This Content API is targeted at a few primary use cases, including enhancing themes with interactivity, creating powerful pluginPlugin A plugin is a piece of software containing a group of functions that can be added to a WordPress website. They can extend functionality or add new features to your WordPress websites. WordPress plugins are written in the PHP programming language and integrate seamlessly with WordPress. These can be free in the WordPress.org Plugin Directory https://wordpress.org/plugins/ or can be cost-based plugin from a third-party interfaces, building mobile and desktop applications, and providing alternative authoring experiences. We’ve been working on first-party examples of these, including a mobile app using React Native and a liveblogging web app, as well as getting feedback from others, including WIRED, the New York Times, and The Times of London. Based on experience building on the API, we’ve polished the endpoints and expanded to support settings endpoints, which are included as the first part of the Management API.

Authentication

The API Infrastructure already in WordPress core includes support for regular cookie-based authentication. This is useful for plugins and themes that want to use the API, but requires access to cookies and nonces, and is hence only useful for internal usage.

To complement the Content Endpoints, for WordPress 4.7 the API team also proposes merging the REST API OAuth 1 server plugin into WordPress Core. This plugin provides remote authentication via the OAuth 1 protocol, allowing remote servers and applications to interact securely with the WordPress API.

OAuth is a standardised system for delegated authorisation. With OAuth, rather than providing your password to a third-party app, you can authorise it to operate on your behalf. Apps are also required to be registered with the site beforehand, which gives site administrators control over third-party access. Access to these apps can be revoked by the user if they are no longer using the app, or by a site administrator. This also allows apps with known vulnerabilities to have compromised credentials revoked to protect users.

We’ve chosen OAuth 1 over the newer OAuth 2 protocol because OAuth 1 includes a complex system for request signing to ensure credentials remain secure even over unsecured HTTP, while OAuth 2 requires HTTPSHTTPS HTTPS is an acronym for Hyper Text Transfer Protocol Secure. HTTPS is the secure version of HTTP, the protocol over which data is sent between your browser and the website that you are connected to. The 'S' at the end of HTTPS stands for 'Secure'. It means all communications between your browser and the website are encrypted. This is especially helpful for protecting sensitive data like banking information. with a modern version of TLS. While it is strongly encouraged for sites to use HTTPS whenever possible (Let’s Encrypt makes it easier than ever to do so), WordPress itself does not require HTTPS and we do not believe WordPress should make HTTPS a requirement for using the API. The additional complexity that OAuth 1 adds can be easily supported by a library, and many such libraries already exist in most programming languages. OAuth 1 remains supported around the web, including for the Twitter API, and we also provide extensive documentation on using it.

Authentication Beyond 4.7

One issue with OAuth over direct username and password authentication is that it requires applications to be registered on the site. For centralized OAuth servers this wouldn’t be a problem, but the distributed nature of WordPress installations makes this tough to handle: your application must be independently registered with every WordPress site it connects to. If you’ve ever had to create a Twitter or Facebook app just to use an existing plugin on your site, you’ll know this can be a less-than-optimal experience for users.

To solve this distribution problem, we’ve created a solution called brokered authentication. This allows a centralised server (called the “broker”) to handle app registration and to vouch for these apps to individual sites. It simplifies app registration by allowing app developers to register once for all sites, and improves security by allowing the broker to vet applications and revoke them across the entire networknetwork (versus site, blog). The system is designed to allow multiple brokers; while the main broker is run at apps.wp-api.org, organisations can run their own broker for internal usage, and developers can run a broker locally for testing.

While the broker system has been running live at apps.wp-api.org for months, we want to stay conservative in our approach to the API, especially where security is concerned. We are therefore proposing brokered authentication for WordPress 4.8 to ensure we have further time to continue testing and refining the broker system. In addition, this will require an installation of the broker on a centralised server to act as the canonical broker for out-of-the-box WordPress. While apps.wp-api.org is currently acting in this role, this is currently hosted by a third-party (Human Made) on behalf of the API team. For long-term usage the broker should instead be hosted on WordPress.org, alongside the existing plugin and theme repositories. This migrationMigration Moving the code, database and media files for a website site from one server to another. Most typically done when changing hosting companies. will take time but we remain committed to continuing to develop and support the broker.

After Merge

After merging the REST API, the team plans to continue developing the API as before. We expect that integrating the REST API into WordPress core will bring additional feedback, and we plan on incorporating this feedback through the rest of the 4.7 cycle.

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. 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 Customiser team. Both of these components will be maintained as separate feature projects on GitHubGitHub GitHub is a website that offers online implementation of git repositories that can easily be shared, copied and modified by other developers. Public repositories are free to host, private repositories require a paid subscription. GitHub introduced the concept of the ‘pull request’ where code changes done in branches by contributors can be reviewed and discussed before being merged be the repository owner. https://github.com/ until they’re ready for merge into core.

The team remains committed to supporting the API in core, and the Content API will switch from GitHub to TracTrac An open source project by Edgewall Software that serves as a bug tracker and project management tool for WordPress. for project management and contributions. This same process occurred for the API Infrastructure in WordPress 4.4.

Reviews and Feedback

With this merge proposal, we’re looking for feedback and review of the project. In particular, we’re focussing on feedback on the security of the API and OAuth projects, and are also reaching out to specific people for reviews. (We take the security of the API seriously, and bugbug A bug is an error or unexpected result. Performance improvements, code optimization, and are considered enhancements, not defects. After feature freeze, only bugs are dealt with, with regressions (adverse changes from the previous version) being the highest priority. reports are welcomed on HackerOne at any time.) Design and accessibilityAccessibility Accessibility (commonly shortened to a11y) refers to the design of products, devices, services, or environments for people with disabilities. The concept of accessible design ensures both “direct access” (i.e. unassisted) and “indirect access” meaning compatibility with a person’s assistive technology (for example, computer screen readers). (https://en.wikipedia.org/wiki/Accessibility) reviews for the OAuth authorisation UIUI User interface are also welcomed to ensure we maintain the high standards of WordPress core.

Both the REST API plugin and the OAuth plugin are available on WordPress.org, and issues can be reported to the GitHub tracker for the API and the OAuth plugin respectively. We have released a final betaBeta A pre-release of software that is given out to a large group of users to trial under real conditions. Beta versions have gone through alpha testing in-house and are generally fairly close in look, feel and function to the final product; however, design changes often occur as part of the process. (Beta 15 “International Drainage Commission”) which includes the meta and settings endpoints.

With Love from Us

As always, this is a merge proposal, and is not final until 4.7 is released. We’re eager to hear your thoughts and feedback; the comments below are a perfect place for that, or you can pop along to one of our regular meetings. We’re also always available in the #core-restapi room on SlackSlack Slack is a Collaborative Group Chat Platform https://slack.com/. The WordPress community has its own Slack Channel at https://make.wordpress.org/chat/..

We’d like to thank every single one of our contributors, including 88 contributors to the main repository and 23 contributors to the OAuth repository. Particular thanks goes to my (@rmccue) wonderful co-lead Rachel Baker (@rachelbaker), our 2.0 release leads Daniel Bachhuber (@danielbachuber) and Joe Hoyle (@joehoyle), and our key contributors for the 4.7 cycle: Adam Silverstein (@adamsilverstein), Brian Krogsgard (@krogsgard), David Remer (@websupporter), Edwin Cromley (@chopinbach), and K. Adam White (@kadamwhite). Thanks also to the core committers helping us out through the 4.7 cycle, including Aaron D. Campbell (@aaroncampbell) and Aaron Jorbin (@aaronjorbin), and to the fantastic release leadRelease Lead The community member ultimately responsible for the Release., Helen Hou-Sandí (@helen).

Thanks also to everyone who has used the REST API, and to you for reading this. We built the REST API for you, and we hope you like it.

With love, The REST API Team

#feature-plugins, #json-api, #merge-proposals, #rest-api

WordPress REST API – 2.0 Beta 14

Hey folks! I’m excited to announce the release of BetaBeta A pre-release of software that is given out to a large group of users to trial under real conditions. Beta versions have gone through alpha testing in-house and are generally fairly close in look, feel and function to the final product; however, design changes often occur as part of the process. 14 of the REST APIREST API The REST API is an acronym for the RESTful Application Program Interface (API) that uses HTTP requests to GET, PUT, POST and DELETE data. It is how the front end of an application (think “phone app” or “website”) can communicate with the data store (think “database” or “file system”) https://developer.wordpress.org/rest-api/.. It’s been a while since our last release, beta 14 is jam packed with general improvements, bugbug A bug is an error or unexpected result. Performance improvements, code optimization, and are considered enhancements, not defects. After feature freeze, only bugs are dealt with, with regressions (adverse changes from the previous version) being the highest priority. fixes and general refinement to polish the feature pluginFeature Plugin A plugin that was created with the intention of eventually being proposed for inclusion in WordPress Core. See Features as Plugins. before coreCore Core is the set of software required to run WordPress. The Core Development Team builds WordPress. merge.

Get it at WordPress.org or GitHub. View all changes on GitHub; here are the highlights:

  • Add support for password protected posts. There is now a protected attribute in the content and excerpt fields in post response. To view password protected posts via the APIAPI An API or Application Programming Interface is a software intermediary that allows programs to interact with each other and share data in limited, clearly defined ways., use the password query parameter to provide the post’s password.
  • Allow returning an error from field update callbacks.
    Simply have your update_callback return a WP_Error.
  • Add relevance orderby to posts endpoint
  • Ability to order by slug, email and url on the users endpoints.
  • Add sticky parameter to the posts endpoint.
  • Update the wp-api.js client from the client-js repo.
  • Many many more

Thanks to all the contributors and special thanks to @chopinbach, @kadamwhite and @websupporter for their effort this release.

We’ll be kicking Beta 15 which will be focused on metaMeta Meta is a term that refers to the inside workings of a group. For us, this is the team that works on internal WordPress sites like WordCamp Central and Make WordPress. support for posts, terms, comments and users as well as a brand new settings endpoint. These are currently in review awaiting feedback, check out the meta pull request and the settings pull request and let us know what you think.

In addition we will be publishing a merge proposal for WordPress 4.7 this week, stay tuned!

#feature-plugins, #json-api, #rest-api

WP REST API: 2.0 Beta 13 & Roadmap

Hi folks! I’m here with another exciting update from the APIAPI An API or Application Programming Interface is a software intermediary that allows programs to interact with each other and share data in limited, clearly defined ways. team.

BetaBeta A pre-release of software that is given out to a large group of users to trial under real conditions. Beta versions have gone through alpha testing in-house and are generally fairly close in look, feel and function to the final product; however, design changes often occur as part of the process. 13

First off, we’re excited to announce 2.0 Beta 13 “yoink.adios\losers” is now available. Grab it from the plugins repo or GitHub while it’s hot. Here’s some of the key updates:

  • BREAKING CHANGE: Fix Content-Disposition headerHeader The header of your site is typically the first thing people will experience. The masthead or header art located across the top of your page is part of the look and feel of your website. It can influence a visitor’s opinion about your content and you/ your organization’s brand. It may also look different on different screen sizes. parsing. This technically breaks backwards compatibility to correctly match the header specification. (#2239)

  • BREAKING CHANGE: Use compact links for embedded responses if they are available. We now use CURIEs for sites on 4.5+, which look like wp:term (but canonicalise to the full URI relation). (#2412)

  • Updated JSJS JavaScript, a web scripting language typically executed in the browser. Often used for advanced user interfaces and behaviors. client to the latest version. (#2403)

There’s lots more changes in this release; check out the release notes or the commits for this release.

Roadmap

We’ve been thinking about how to tackle the API in the coming future. We want to do the most we can to ensure you can build sites with confidence.

Along these lines, we’re going to release a 2.0 final version in the coming months. This will be a completely stable release with guaranteed backwards compatibility for the foreseeable future. This backwards compatibility ensures that your sites can remain up-to-date with minimal maintenance or issues with upgrading.

We originally held the software in beta for a long period to ensure that breaking changes could be rolled in if deemed necessary to move the project forward. However, the majority of these breaks occurred at the start of the 2.0 lifecycle, and the API is mostly stable at this point. Keeping the ability to break compatibility benefits only us, whereas moving to a stable release benefits everyone.

Moving forward, version 2.0 of the WP REST APIREST API The REST API is an acronym for the RESTful Application Program Interface (API) that uses HTTP requests to GET, PUT, POST and DELETE data. It is how the front end of an application (think “phone app” or “website”) can communicate with the data store (think “database” or “file system”) https://developer.wordpress.org/rest-api/. will follow a normal project release cycle. We will have minor releases in the 2.x series as new features are added, and bugfix releases in the 2.0.x series.

As for the coreCore Core is the set of software required to run WordPress. The Core Development Team builds WordPress. merge itself, we are not submitting a merge proposal of the core endpoints for WordPress 4.6. We believe endpoints for the main WordPress objects (posts, users, comments, terms, and taxonomies) are not enough to garner the support needed for the proposal to be accepted. Our hope is that with a stable version 2.0 release, we will attract our community members that have been waiting for the endpoints to be available in core, and submit a merge proposal for the WordPress 4.7 release cycle.

In addition to attracting more developers within our community, we are also looking to get more contributors involved with the project. As noted in previous discussions, the four of us on the API team can’t keep pace with WordPress itself without help. We’re looking to get WordPress core component maintainers involved in their relevant components, as well as new developers from outside the project. Moving forward, the API team sees our role as advisory over the API itself, with the API treated as an integral part of the component rather than maintained by a separate team. We’re also going to continue to work on our feature plugins (metadata, site/multisitemultisite Used to describe a WordPress installation with a network of multiple blogs, grouped by sites. This installation type has shared users tables, and creates separate database tables for each blog (wp_posts becomes wp_0_posts). See also network, blog, site, menus/widgets, and authentication) in parallel, and are looking for help on these as well. (There’s also more news regarding authentication coming very soon.)

If you’d like to get involved with the API, please let us know. You can comment here, pingPing The act of sending a very small amount of data to an end point. Ping is used in computer science to illicit a response from a target server to test it’s connection. Ping is also a term used by Slack users to @ someone or send them a direct message (DM). Users might say something along the lines of “Ping me when the meeting starts.” us on SlackSlack Slack is a Collaborative Group Chat Platform https://slack.com/. The WordPress community has its own Slack Channel at https://make.wordpress.org/chat/. in the #core-restapi room, or via GitHubGitHub GitHub is a website that offers online implementation of git repositories that can easily be shared, copied and modified by other developers. Public repositories are free to host, private repositories require a paid subscription. GitHub introduced the concept of the ‘pull request’ where code changes done in branches by contributors can be reviewed and discussed before being merged be the repository owner. https://github.com/ issues. We’re looking at spending significant time onboarding new users, so if you’d like to get involved, now’s the time! Our weekly meeting is at Monday 23:00 UTC

Thanks for catching up with us, and have a wonderful day.

With love,

Ryan, Rachel, Daniel, and Joe

#json-api, #rest-api

WP REST API: Version 2.0 Beta 12

Happy Tuesday 🙂 The WP REST APIREST API The REST API is an acronym for the RESTful Application Program Interface (API) that uses HTTP requests to GET, PUT, POST and DELETE data. It is how the front end of an application (think “phone app” or “website”) can communicate with the data store (think “database” or “file system”) https://developer.wordpress.org/rest-api/. team is proud to bring you: 2.0 BetaBeta A pre-release of software that is given out to a large group of users to trial under real conditions. Beta versions have gone through alpha testing in-house and are generally fairly close in look, feel and function to the final product; however, design changes often occur as part of the process. 12 “Canyonero”. Download it from the plugin repository or from GitHub.

Here are some highlightsbreaking changes from the changelog:

  • Removes metaMeta Meta is a term that refers to the inside workings of a group. For us, this is the team that works on internal WordPress sites like WordCamp Central and Make WordPress. endpoints from primary pluginPlugin A plugin is a piece of software containing a group of functions that can be added to a WordPress website. They can extend functionality or add new features to your WordPress websites. WordPress plugins are written in the PHP programming language and integrate seamlessly with WordPress. These can be free in the WordPress.org Plugin Directory https://wordpress.org/plugins/ or can be cost-based plugin from a third-party. If your project depends on post meta endpoints, please install WP REST API Meta Endpoints. For the gory history of meta, read #1425 and linked issues. At this time, we recommend using register_rest_field() to expose meta (docs).
  • Returns original resource when deleting PTCU. Now that all resources require the force param, we don’t need to wrap delete responses with the trash state.
  • Uses roles rather than role in the Users controller. Building the REST API gives us the opportunity to standardize on roles, instead of having both roles and role.
  • Moves to consistent use of context throughout controllers. Contexts limit the data present in the response. Here’s how to think of them: embed correlates with sidebarSidebar A sidebar in WordPress is referred to a widget-ready area used by WordPress themes to display information that is not a part of the main content. It is not always a vertical column on the side. It can be a horizontal rectangle below or above the content area, footer, header, or any where in the theme. representation, view represents the primary public view, and edit is the data expected for an editor.
  • Removes post_* query param support for GET /wp/v2/comments. The proper pattern is to use GET /wp/v2/posts to fetch the post IDs to limit the request to.
  • Introduces rest_validate_request_arg()/rest_sanitize_request_arg(). Dedicated functions means we can use them for validating / sanitizing query args too. Removes WP_REST_Controller::validate_schema_property() and WP_REST_Controller::sanitize_schema_property().

As always, we have a detailed changelog as well as the full set of changes if you’re interested.

What’s the future of the WP REST API? I’d like to leave you with this final thought:

What came first, the chicken or the egg?
I egged the chicken, and then I ate his leg

#feature-plugins, #json-api, #rest-api

Thar be a WP REST API meeting tomorrow

Curious as to when the WP REST APIREST API The REST API is an acronym for the RESTful Application Program Interface (API) that uses HTTP requests to GET, PUT, POST and DELETE data. It is how the front end of an application (think “phone app” or “website”) can communicate with the data store (think “database” or “file system”) https://developer.wordpress.org/rest-api/. endpoints will land in WordPress coreCore Core is the set of software required to run WordPress. The Core Development Team builds WordPress.? Me too!

We’re meeting to discuss the State of the REST API just under 24 hours from now in #core-restapi on SlackSlack Slack is a Collaborative Group Chat Platform https://slack.com/. The WordPress community has its own Slack Channel at https://make.wordpress.org/chat/.: Thursday, February 4 at 23:00 UTC

The primary points of discussion are:

  • Existing Post, Term, User and Comment endpoints.
  • New Site, Widgets, Menus, Plugins and Themes endpoints we started on Friday.
  • REST API clients — those that exist, and those that don’t yet.
  • Happy fun authentication methods.

See you there!

#feature-plugins, #json-api, #rest-api

WP REST API: Version 2.0 Beta 11

Just days before the first conference dedicated to the REST API, we bring you: 2.0 BetaBeta A pre-release of software that is given out to a large group of users to trial under real conditions. Beta versions have gone through alpha testing in-house and are generally fairly close in look, feel and function to the final product; however, design changes often occur as part of the process. 11 “Give me a white wine spritzer!”. Download it from the plugin repository or from GitHub.

Here are some highlightsbreaking changes from the changelog:

  • Moves Post->Term relations to the Post Resource. Previously, a client would fetch a Post’s Tags with GET /wp/v2/posts/<id>/tags. In Beta 11, an array of term ids is included on the Post resource. The collection of terms for a Post can be fetched with GET /wp/v2/tags?post=<id>. The WP_REST_Posts_Terms_Controller class no longer exists.
  • Changes featured_image attribute on Posts to featured_media. While featuring other attachment types isn’t yet officially supported, this makes it easier for us to introduce the possibility in the future.
  • Uses discrete schema title for categories and tags. If you’ve used register_rest_field( 'term' ), you’ll need to change 'term' to 'tag' and/or 'category'.
  • Makes many filters dynamic based on the controller type. If you were using the rest_prepare_term filterFilter Filters are one of the two types of Hooks https://codex.wordpress.org/Plugin_API/Hooks. They provide a way for functions to modify data of other functions. They are the counterpart to Actions. Unlike Actions, filters are meant to work in an isolated manner, and should never have side effects such as affecting global variables and output., you’ll need to change it to rest_prepare_post_tag or rest_prepare_category. If you were using rest_post_query or rest_terms_query, you’ll need update your use to rest_page_query, etc. If you were using rest_post_trashable, rest_insert_post or rest_delete_post, they are now dynamic based on the post type slug.

As always, we have a detailed changelog as well as the full set of changes if you’re interested.

#feature-plugins, #json-api, #rest-api

WP REST API: Version 2.0 Beta 10, with security releases

For the first REST APIREST API The REST API is an acronym for the RESTful Application Program Interface (API) that uses HTTP requests to GET, PUT, POST and DELETE data. It is how the front end of an application (think “phone app” or “website”) can communicate with the data store (think “database” or “file system”) https://developer.wordpress.org/rest-api/. release of 2016, we bring you: 2.0 BetaBeta A pre-release of software that is given out to a large group of users to trial under real conditions. Beta versions have gone through alpha testing in-house and are generally fairly close in look, feel and function to the final product; however, design changes often occur as part of the process. 10 “Chief Wiggum”. Because we’ve got security releases too, Ralphie.

Security Releases

On Friday, we discovered that attachments uploaded to private posts are publicly queryable through the REST API. This is a form of information disclosure because WordPress’ permissions model is such that attachments uploaded to posts should inherit the visibility of their parent post.

All previous versions of the pluginPlugin A plugin is a piece of software containing a group of functions that can be added to a WordPress website. They can extend functionality or add new features to your WordPress websites. WordPress plugins are written in the PHP programming language and integrate seamlessly with WordPress. These can be free in the WordPress.org Plugin Directory https://wordpress.org/plugins/ or can be cost-based plugin from a third-party are affected. All WP REST API users are strongly encouraged to update immediately. Many prior releases has been separately patched. If you’re still using WP-APIAPI An API or Application Programming Interface is a software intermediary that allows programs to interact with each other and share data in limited, clearly defined ways. v1.x, you can update to v1.2.5. If you’re on an older 2.0 Beta for whatever reason, we’ve tagged versions 2.0 Beta 3.1, 4.1, 5.1, 6.1, 7.1, 8.1, and 9.1.

If you believe you have discovered a potential security vulnerability with the WP REST API, please disclose it to us privately by sending an email to security@wordpress.org. Security issues can also be reported via HackerOne.

Version 2.0 Beta 10

Here are some of the highlights of Beta 10:

  • Breaking changes:
    • Removes compatibility repo for WordPress 4.3. WordPress 4.4 is now the minimum supported version.
    • Changes link relation for types and taxonomies. In Beta 9, this link relation was introduced as item, which isn’t correct. The relation has been changed to https://api.w.org/items.
    • Introduces edit context for wp/v2/types and wp/v2/taxonomies. Some fields have moved into this context, which require edit_posts and manage_terms, respectively.
    • Removes post_format as a term _link for Posts. Post formats aren’t a custom taxonomyTaxonomy A taxonomy is a way to group things together. In WordPress, some common taxonomies are category, link, tag, or post format. https://codex.wordpress.org/Taxonomies#Default_Taxonomies. in the eyes of the REST API.
  • Consistently query for a specified set of items. Adds include param to /wp/v2/posts, /wp/v2/users, /wp/v2/<taxonomy> and /wp/v2/comments.
  • Tons of minor improvements and bugbug A bug is an error or unexpected result. Performance improvements, code optimization, and are considered enhancements, not defects. After feature freeze, only bugs are dealt with, with regressions (adverse changes from the previous version) being the highest priority. fixes. You should read the full changelog for all of them.

As always, we have a detailed changelog as well as the full set of changes if you’re interested.

#feature-plugins, #json-api, #rest-api

WP REST API: Version 2.0 Beta 9

For the last REST APIREST API The REST API is an acronym for the RESTful Application Program Interface (API) that uses HTTP requests to GET, PUT, POST and DELETE data. It is how the front end of an application (think “phone app” or “website”) can communicate with the data store (think “database” or “file system”) https://developer.wordpress.org/rest-api/. release of 2015, we bring you: 2.0 BetaBeta A pre-release of software that is given out to a large group of users to trial under real conditions. Beta versions have gone through alpha testing in-house and are generally fairly close in look, feel and function to the final product; however, design changes often occur as part of the process. 9 “You Don’t Win Friends With Salad”. Download it from the plugin repository or from GitHub.

Should I use 2.0 Beta 9 in production?

This is a great question. I (Daniel) will do my best to answer from my perspective — Ryan, Rachel or Joe may have different opinions.

As many of you may already know, the v1.x branchbranch A directory in Subversion. WordPress uses branches to store the latest development code for each major release (3.9, 4.0, etc.). Branches are then updated with code for any minor releases of that branch. Sometimes, a major version of WordPress and its minor versions are collectively referred to as a "branch", such as "the 4.0 branch". is essentially deprecated and only maintained for security and major compatibility issues. Even its latest release, v1.2.4, still includes some annoying bugs. The v2.0 Betas introduce aton of new features, functionality, and general improvements. But, there will never be a formal v2.0 pluginPlugin A plugin is a piece of software containing a group of functions that can be added to a WordPress website. They can extend functionality or add new features to your WordPress websites. WordPress plugins are written in the PHP programming language and integrate seamlessly with WordPress. These can be free in the WordPress.org Plugin Directory https://wordpress.org/plugins/ or can be cost-based plugin from a third-party release — v2.0 will be endpoint inclusion into WordPress coreCore Core is the set of software required to run WordPress. The Core Development Team builds WordPress..

Right now, we’re doing our darned best to get the endpoints into core at the end of January 2016. Between now and then we have at least 74 issues to wade through. Beta 9 includes 32 merged pull requests.

In the interest of feeling confident about the code we’re committing to core, we are and will be making breaking changes in the Betas. Significantly, Beta 10 will remove the core directory, and will be incompatible with WordPress 4.3.

Short answer: you’re welcome to use the Betas in production if you understand the ramifications. When updating, we expect you to read through the changelog and thoroughly test each release with your project. You should probably have test coverage on any custom endpoints you’re writing. And, set aside time to properly debug any issues you uncover and submit pull requests with test coverage.

If you aren’t comfortable with aforementioned ramifications, please refrain from using the v2.0 Betas in production. We do encourage everyone to use them locally, or in staging / test environments, and look forward to your feedback.

Changelog

Here are some highlights:

  • Move tags and categories to top-level endpoints. Tags are now accessible at `/wp/v2/tags`, and categories accessible at `/wp/v2/categories`. Post terms reside at `/wp/v2/posts//tags` and `/wp/v2//categories`.
  • Return object for requests to `/wp/v2/taxonomies`. This is consistent with `/wp/v2/types` and `/wp/v2/statuses`.
  • Remove `rest_get_timezone()`. `json_get_timezone()` was only ever used in v1. This function causes fatals, and shouldn’t be used.
  • Rename `register_api_field()` to `register_rest_field()`. Introduces a `register_api_field()` function for backwards compat, which calls `_doing_it_wrong()`. However, `register_api_field()` won’t ever be committed to WordPress core, so you should update your function calls.
  • Change taxonomies’ `post_type` argument to `type`. It’s consistent with how we’re exposing post types in the APIAPI An API or Application Programming Interface is a software intermediary that allows programs to interact with each other and share data in limited, clearly defined ways..
  • Sync infrastructure with shipped in WordPress 4.4.
    • `wp-includes/rest-api/rest-functions.php` is removed, and its functions moved into `wp-includes/rest-api.php`.
    • Send nocache headers for REST requests.
    • Fix handling of HEAD requests.
    • Mark `WP_REST_Server::get_raw_data()` as static.
    • Unabbreviate error string.
  • Change terms endpoints to use `term_id` not `tt_id`.
  • Standardize declaration of `context` param for `GET` requests across controllers. However, we’re still inconsistent in which controllers expose which params. Follow #1845 for further discussion.
  • Link types / taxonomies to their collections, and vice versa. Collections link to their type / taxonomyTaxonomy A taxonomy is a way to group things together. In WordPress, some common taxonomies are category, link, tag, or post format. https://codex.wordpress.org/Taxonomies#Default_Taxonomies. with the `about` relation; types / taxonomies link to their collection with the `item` relation, which is imperfect and may change in the future.

As always, we have a detailed changelog as well as the full set of changes if you’re interested.

#feature-plugins, #json-api, #rest-api

WP REST API: New Tools & OAuth Updates

Hi everyone! I’m here today with some special news for everyone, rather than a standard release announcement. I have three things to announce instead. 🙂

Discovery Library for PHPPHP The web scripting language in which WordPress is primarily architected. WordPress requires PHP 5.6.20 or higher

A super cool thing that you might not know about with the APIAPI An API or Application Programming Interface is a software intermediary that allows programs to interact with each other and share data in limited, clearly defined ways. is that it’s entirely discoverable. We use a relatively simple process modelled after Atom/RSS feedRSS Feed RSS is an acronym for Real Simple Syndication which is a type of web feed which allows users to access updates to online content in a standardized, computer-readable format. This is the feed. discovery. All you need to do is check a site’s headers for a Link headerHeader The header of your site is typically the first thing people will experience. The masthead or header art located across the top of your page is part of the look and feel of your website. It can influence a visitor’s opinion about your content and you/ your organization’s brand. It may also look different on different screen sizes.:

Link: <http://example.com/wp-json/>; rel="https://api.w.org/"

This allows a tonne of possibilities, including renaming the API base, or even delegating API access to someone else. (For example, WordPress.comWordPress.com An online implementation of WordPress code that lets you immediately access a new WordPress environment to publish your content. WordPress.com is a private company owned by Automattic that hosts the largest multisite in the world. This is arguably the best place to start blogging if you have never touched WordPress before. https://wordpress.com/ could use https://api.wordpress.com/{site_id}/ instead of per-site APIs.)

However, this isn’t always the easiest process to use (even if you have an advanced degree in hypothetical topology). To simplify this, we now have a discovery library for PHP 5.3+.

To use it, add wp-api/discovery to your Composer requirements manually or run composer require wp-api/discovery in your project directory. You can then use the WordPress\Discovery\discover() function to discover the API for a given URLURL A specific web address of a website or web page on the Internet, such as a website’s URL www.wordpress.org. (Oh hey, namespaces!)

The library also includes a demo that you can run using PHP’s built-in server, and we’re working on getting a public version of this up on wp-api.org so you don’t even need to install it.

This should simplify the discovery process for everyone, and I’m hoping some wonderful folks in the community will help port this to other languages as well. (Hint hint.)

New OAuth Server

One of the weakest points of developing with the API right now is getting authentication working. For a long time, our OAuth server pluginPlugin A plugin is a piece of software containing a group of functions that can be added to a WordPress website. They can extend functionality or add new features to your WordPress websites. WordPress plugins are written in the PHP programming language and integrate seamlessly with WordPress. These can be free in the WordPress.org Plugin Directory https://wordpress.org/plugins/ or can be cost-based plugin from a third-party has languished and fallen behind as we push forward with the API. No longer is this the case!

Simply update to the latest master. This will also be available on WordPress.orgWordPress.org The community site where WordPress code is created and shared by the users. This is where you can download the source code for WordPress core, plugins and themes as well as the central location for community conversations and organization. https://wordpress.org/ very soon.

This new version of the OAuth server has a bunch of changes, including:

  • Full adminadmin (and super admin) UIUI User interface, including application management and the ability to revoke tokens
  • Ability to delete applications or regenerate their secrets
  • Callback validation process overhaul, now supporting custom protocols
  • Overhauled internals

In addition to this, I wanted to address one of the biggest problems with the OAuth process: documentation. The documentation for the OAuth server and process has been terrible in the past. Previously, I’d indicated to people that they should just go read the generic OAuth 1.0a documentation on the web and try with that, but as it turns out, there’s no good documentation on this. (Apologies to those of you who’ve struggled in the past.)

Thankfully, this is now fixed, with a guide included and available on Gitbook. This is an initial version of the guide, and I imagine it’ll grow and improve further in the future.

If there’s anything missing you’d like added or improved, file an issue on the plugin repo. (The guide’s source is also included with the plugin.)

Demo API Client

(pause for breath)

Combining all these pieces, there’s now a demo API client in PHP that you can download and run to try all of this out. The demo client uses the discovery library to find your site, then connects with OAuth to display your user details. Again, you can run this locally using PHP’s built-in server, and we’re working on getting a version set up on wp-api.org too.

Internally, this uses the wonderful OAuth 1 client library by The League of Extraordinary Packages. This repo also acts as a provider for that library, allowing you to use the library in your own code to handle OAuth.

(Both the discovery library and the demo client are open sourceOpen Source Open Source denotes software for which the original source code is made freely available and may be redistributed and modified. Open Source **must be** delivered via a licensing model, see GPL. and MIT licensed, allowing you to use them in commercial projects should you so desire.)

Hopefully you find these pieces useful. As always, your feedback on all of this is much appreciated; we’d also love to see discovery libraries and demo clients in other languages, if anyone wants to port them across. Thanks for being great.

#feature-plugins, #json-api, #rest-api

WP REST API: Version 2.0 Beta 8

Just in time for WordCampWordCamp WordCamps are casual, locally-organized conferences covering everything related to WordPress. They're one of the places where the WordPress community comes together to teach one another what they’ve learned throughout the year and share the joy. Learn more. US, we have a new REST APIREST API The REST API is an acronym for the RESTful Application Program Interface (API) that uses HTTP requests to GET, PUT, POST and DELETE data. It is how the front end of an application (think “phone app” or “website”) can communicate with the data store (think “database” or “file system”) https://developer.wordpress.org/rest-api/. for you: 2.0 BetaBeta A pre-release of software that is given out to a large group of users to trial under real conditions. Beta versions have gone through alpha testing in-house and are generally fairly close in look, feel and function to the final product; however, design changes often occur as part of the process. 8 “Monorail!”. Download it from the plugin repository or from GitHub.

Here’s the changelog:

  • Prevent fatals when uploading attachment by including adminadmin (and super admin) utilities. (#1756)
  • Return 201 status code when creating a term. (#1753)
  • Don’t permit requesting terms cross routes. (#1764)
  • Set fields=>id when using WP_User_Query to fix large memory usage. (#1770)
  • Fix Post _link to attached attachments. (#1777)
  • Add support for getting a post with a custom public status. (#1765)
  • Ensure post content doesn’t get double-slashed on update. (#1772)
  • Change ‘int’ to ‘integer’ for WP_REST_Controller::validate_schema_property() (#1759)

Check out the full set of changes if you’re interested.

#feature-plugins, #json-api, #rest-api