Make WordPress Core

Updates from K.Adam White Toggle Comment Threads | Keyboard Shortcuts

  • K.Adam White 1:55 am on October 24, 2016 Permalink |
    Tags: , ,   

    REST API: Agenda for October 24 Meeting 

    Here’s the agenda for Monday’s weekly meeting for the REST API project, at 2016-10-24 14:00 UTC in the #core-restapi channel in slack. The meeting will run for one hour.

    • Discuss post-merge Process Changes & the future of the WP-API GitHub Repository
    • Review Trac tickets: what hasn’t been migrated from GitHub?
    • Clarify priorities & responsibilities leading up to Beta 1
    • Open floor.

    Meetings are every Monday at 1400 UTC. See you there!

  • K.Adam White 12:28 am on October 18, 2016 Permalink |
    Tags: , ,   

    REST API Team Meeting Notes, 2016-10-17 

    As a reminder, in just 30 minutes there is a meeting in #core to decide whether the REST API Content Endpoints will be merged as a part of WordPress 4.7! See the ongoing discussion of this proposal here. Note that the OAuth server is no longer proposed for merge at this time, but authentication options will be a primary focus area for the API project during the 4.8 development cycle.

    The REST API Content Endpoints provide a new foundation upon which the WordPress developer community can build themes, plugins, and core feature. They represent a common standard and consistent interface across WordPress’s core content data types, and provide robust support for custom post types and meta values. These endpoints lay the foundation upon which future releases will add remote authentication options, even deeper querying abilities, and broader endpoint coverage for site management. This iterative approach fits WordPress’s development model and philosophy, advancing the project’s long-term goal of opening WordPress up to a wider developer audience and helping to ensure continued work on the REST API in the release cycles and years to come.

    Meeting Notes

    At today’s weekly API team meeting in core-restapi (agenda here) the team resolved all outstanding decisions milestoned for the REST API 2.0 / WordPress 4.7 merge candidate:

    • The ?filter query parameter will be removed from the REST API plugin prior to core merge, a breaking change that improves the consistency of querying the API and eliminates a set of parameters that could introduce backwards compatibility issues were they to be committed to WordPress core. A separate plugin will be published to reinstate the `filter` parameter on a strictly opt-in basis.
    • Comments on password-protected posts are being deferred as a future enhancement until a robust solution is proposed that permits the API to adequately mirror existing functionality.
    • The unfiltered_html capability should be respected by the API, and a patch will be submitted to bring the API’s behavior in line with core’s.

    There are 29 tickets left in the 2.0 milestone, several of which have open pull requests already. These issues represent a mix of outstanding bugs, documentation needs and improvements that will be moved to trac should the merge proposal be accepted.

    The REST API team leads would like to recognize that the content endpoints plugin now has 95 contributors: thank you and welcome to all of the new participants who have joined the project in the past week!

  • K.Adam White 10:26 pm on October 14, 2016 Permalink |  

    REST API: Agenda for Oct 17, 2016 Meeting 

    The meeting to decide whether to merge the REST API Content Endpoints in WordPress 4.7 will occur at 2016-10-18 01:00 UTC in #core!

    Please comment on this feedback post with your arguments for or against.

    In preparation for that meeting, we will be holding bonus weekend office hours at 2016-10-15 17:00 UTC and 2016-10-16 17:00 UTC in #core-restapi.

    Our usual team meeting is also happening, on Monday at 2016-10-17 14:00 UTC. The agenda for this meeting:

  • K.Adam White 11:15 pm on October 13, 2016 Permalink |
    Tags: ,   

    Merge Proposal Discussion: REST API Content Endpoints 

    There are discussion meetings and office hours in #core-restapi at 2016-10-14 14:00UTC and 2016-10-14 19:00UTC on Friday the 14th. Our next team meeting is on 2016-10-17 14:00UTC. Please attend some of all of these, because

    We are meeting at 2016-10-18 01:00 UTC to make a decision on this merge proposal!

    To that end, the below discussion points will be updated regularly, please leave comments on this post or join the conversation in #core-restapi.

    Yesterday at the dev chat the API Team proposed the Content API Endpoints for merge in WordPress 4.7. There was popular support for this feature but as @jorbin and @helen noted that the lack of dissent suggested additional review is needed, so the API Team is continuing to seek thorough review & constructive criticism of the content endpoints, including the open questions previously shared on the week 7 and week 8 API team updates.

    The merge proposal also engendered follow-up discussion in the #core-restapi channel about the benefit content endpoints bring to core, whether having such endpoints built in is quantifiably more beneficial than having them as a plugin, whether moving development from a plugin to core would slow development, and whether the endpoints as-proposed have been sufficiently reviewed for security and performance. We attempt to capture those questions & concerns (and the perspectives on them) below.


    Have the content API endpoints been thoroughly reviewed for security?

    • The REST API plugin has been on HackerOne for over a year with paid bounties for bugs
    • @barry has begun a security review


    How does the API measure up against alternatives? Are there concerns about how the API could impact the servers to which it is deployed?

    • DeliciousBrains did a performance comparison with Admin AJAX and found the REST API to have a performance improvement (These tests have not yet been independently verified)
    • @mikeschroder notes in the comments that using the REST API in place of Admin-Ajax will also bring speed benefits by permitting many previously-uncacheable requests to be cached.

    User Feedback

    Are the content endpoints sufficiently well-tested & vetted by the community?

    • @matt questions whether feedback is coming too late in development for concerns to be acted upon
      • @rmccue notes that the v2 endpoints were created based on user feedback; REST API endpoints are being deployed by plugins and running on VIP, and the content endpoints have been in wide use across a variety of sites, leading to 90+ code contributors and far more developers’ support & feedback on the endpoints
    • @rmccue has also reached out to Phil Sturgeon for feedback and will follow up

    Do Content Endpoints Benefit Core Development?

    Will having these endpoints in core improve future core development, or solve any immediate problems?

    • @bradyvercher suggested that the content API endpoints would remove the need to write a variety of one-off ajax callbacks when developing future WordPress Core AJAX functionality
    • @westonruter notes that the customizer could dynamically create settings for posts and other kinds of content without having to wire up new admin-ajax handlers

    Will Merging Negatively Impact API Development?

    Will having to work through trac instead of GitHub cause development to atrophy?

    • @jjj argues that merging will slow development, because GitHub-hosted plugins are not bound to WordPress release cycles and have less overhead for features to be developed and deployed for testing. @jjj requested a plan for how the REST API will be developed going forward after the merge of these endpoints that would account for the added friction.
    • @krogsgard countered that core increases the visibility of a project like the content endpoints
      • The number of new contributors in this Slack discussion suggests that this merge proposal is bringing in new voices; whether this supports Brian’s point or not, the team is grateful for the breadth of perspectives being shared -Ed.
    • @rachelbaker suggested that the API endpoints are sufficiently inter-dependent with core WordPress code that maintaining the plugin separately amounts to maintaining a fork, and that such separated development is untenable long-term.
    • @matt hopes that a merge of these endpoints would slow release speed, but not development speed; @rmccue feels that development speed will stay the same or increase, and that tying releases to WordPress Core increases the stability and predictability of the API endpoints.
    • The versioning of the API endpoints supports forward compatibility

    Do Content Endpoints Belong on Every WordPress Site?

    What are the pros and cons to having every WordPress site have content API endpoints?

    • @rmccue suggests the API has network effects that can only be realized with a large install base. @krogsgard draws a comparison to RSS, the widespread availability of which enables everything from podcasting from WP to the use of apps like Feedly.
    • @matt suggests that the Atom API is a better analogue than RSS, which is an independent and pre-existing standard, and that network effects could be tested through inclusion in Jetpack
    • @joostdevalk notes that many plugins, like Yoast, have data tied to existing content such as posts and pages; either they expose the content through their own endpoints, or core does. If Core exposes content types through the API then plugins may build on top of that shared foundation, not independently reinvent the wheel. “if this doesn’t end up in core, we’ll start rolling our own API for stuff. Others will too. Interoperability won’t be there, for even the most basic stuff. I think this isn’t like RSS, I think this is much more like all of us using the same table space in MySQL.”
      • @shelob9 and @masonjames agree that merging the endpoints would create a consistent and reliable open “standard” that WordPress developers can use instead of continually reinventing how to read and edit post data over HTTP.
      • In response to the question “what prevents you from building on the endpoints in their plugin form,” @joostdevalk went on to note that plugin dependencies would make that a viable option, but that burden currently lies on the user. Plugin installation is not frictionless.
    • Can these endpoints be bundled? short takeaway: no
      • Woo bundled the API infrastructure before it was merged; doing so for content endpoints would require bundling prohibitively large amounts of endpoint code.
      • @nerrad worries that if plugins bundle different versions of the endpoints plugin, then those plugins may conflict if all bundled copies are not kept in sync.
        • @nerrad clarifies in the comments below that these worries also encompass the additional risk of conflicts when plugin authors each build their own versions of these content endpoints, instead of leveraging a shared standard: if two plugins each expose their own REST collection for posts, a developer working on a site with multiple such endpoints will need to decide which to extend, and will then have their extension tied to that specific plugin rather than to a core API.
    • @schrapel and @jorbin discussed that these content endpoints make it much easier to crawl a site, which also brings some potential performance concerns: no new content is exposed, but the process of aggregating it is easier and more easily automated.
    • In the  comments below @foliovision believes that merging the endpoints will be the best way to assert the level of back-compatibility that mid-size agencies need in order to confidently utilize the endpoints.

    Please leave thoughts, questions, concerns, comments & experience in the comments below. Thank you!

    Edited 2016-10-16 to include the below comments into the body of the post

    • FolioVision 11:27 pm on October 13, 2016 Permalink | Log in to Reply

      Great discussion summary Adam. As the leader of a mid-size development agency, the sooner these endpoints are in core, the sooner we can start to use the REST API. For smaller to medium size clients, trying to play pin the tail on a donkey on a moving train (i.e. different versions of the REST API plugin, different versions of core) is simply not economically or technologically viable.

      As long as the REST API team can commit to retaining some backward compatibility if the API endpoints must change significantly in a couple of major releases, I can’t see any benefit to keeping REST API separate from core. So much great work has gone into creating the additional REST potential, it would be a shame to see it remain bottled up and a niche product only for huge agencies and hosts like VIP.wordpress.com or WordPress.com.

    • Josh Pollock 11:39 pm on October 13, 2016 Permalink | Log in to Reply

      One thing I wanted to add to this is that the REST API adds standards. I and many others have written tons of custom systems for alternative ways to read and edit post data using admin-ajax, or using custom rewrite rules.

      The constant reinventing of the wheal is counter to the spirit of open-source. By agreeing to a standard, with tons of eyes on it, we can all do better with greater efficiency and security. This after all is why we use WordPress and other open-source tools, instead of making our own CMSes.

      • masonjames 12:53 pm on October 14, 2016 Permalink | Log in to Reply

        I want to affirm this point as well. Our agency looks to WordPress (core) to provide an opinion. We value the decisions and respect them (even when we disagree).

        Web development is an incredibly competitive space with pressures in open source and otherwise. Having content end points in core ensures consistency and reliability across the WP community.

    • rag-guay 7:00 am on October 14, 2016 Permalink | Log in to Reply

      I would like to be able to edit widgets from the desktop app. So slow over the net from Thailand!

      • K.Adam White 12:58 pm on October 14, 2016 Permalink | Log in to Reply

        That’s a good point and I agree we need a solution for it. On behalf of the API Team, support for editing widgets is on the roadmap but is not part of what’s being proposed for merge this cycle. It is definitely a common request, and is one of our priorities for 4.8 as we expand the site management capabilities of the API!

        You can see some early experiments from earlier this year towards this usage here: https://github.com/WP-API/wp-api-menus-widgets-endpoints

    • Darren Ethier (nerrad) 10:46 am on October 14, 2016 Permalink | Log in to Reply

      Great summary! A lot of great back and forth in that discussion thread that isn’t always easy to capture 🙂

      Just wanted to clarify that the comments I made were not only in regards to the possibility of conflicts if plugin authors bundled the plugin version of the REST API with their own plugins, but also, with the presence of the infrastructure already in WordPress core, there is the possibility of conflicts should plugin authors roll their own different versions of the content endpoints to support what they are doing.

      Imagine plugin author A has used to api infrastructure in WP core to build custom endpoints for his plugin and his users are asking if he can add some endpoints for their posts, pages and users as well, so he goes ahead and does that. In the meantime, plugin author B has users asking her to build custom endpoints for users that support her needs as well so she adds them. Then along comes User Sally who installs and activates both plugins. She contracts mobile app developer Jimmy to build an app for her that interacts with both plugins and her website. Jimmy starts running into conflicts between what “user” endpoint to use but he manages to get it working. Then Sally tells Jimmy that she wants to distribute this app for anybody using plugin A or plugin B and Jimmy starts thinking about building a custom user endpoint in a plugin that site owners will need to install to use the app to save having to worry in the mobile app about what user endpoint to utilize.

      There are definitely different technical solutions to the above example story, but the reality is, things would be MUCH simpler for all the actors in the story above if there was an accepted standard in WordPress core for the content endpoints. It prevents a lot of problems from occurring.

    • K.Adam White 1:00 pm on October 14, 2016 Permalink | Log in to Reply

      If I may make a request of the developer community: Share this with your colleagues and friends outside of WordPress. See what they like, and what they find rough; let us know what they think! We’ve been gathering outside input on this but for more is always better.

    • Mike Schroder 6:03 pm on October 14, 2016 Permalink | Log in to Reply

      I noted this in the #core chat this week, but from my perspective at a host, we’re excited that landing the REST API will have performance benefits — in particular, because it will mean that we can cache requests that could only go through `admin-ajax` previously (and were thus forced to be dynamic).

      This will help with scaling even if it’s found that performance for the actual time in PHP/MySQL is exactly the same.

      Gradually moving those requests (whether they be core related, or added with plugins) out of `admin-ajax` will also help SysEng/Support more easily spot which requests are problematic.

      • Matt Mullenweg 1:15 am on October 18, 2016 Permalink | Log in to Reply

        It probably won’t have any real-world performance benefit — the admin-ajax benchmark was kind of flawed, and you won’t be able to do HTTP-level caching unless you also support some quite-fancy invalidation.

    • Luke Cavanagh 9:49 pm on October 14, 2016 Permalink | Log in to Reply

      I only see this as positive thing to be in WP core.

    • Brian Richards 2:21 pm on October 17, 2016 Permalink | Log in to Reply

      I’m late to the party but I want to officially register my voice in favor of merging the content endpoints into core.

      As @joostdevalk mentioned in Slack (and others have discussed elsewhere), there are a lot of opportunities to include API-based interactions within a plugin that are stifled presently because of the dependency on the REST API as a plugin. While it does seem like a small thing to inform end-users “This plugin requires the WP REST API plugin” it’s still a burden they needn’t bear. Further, by relegating the REST API to a plugin it stifles the ability for API-based interactions across many sites. For instance, a plugin that creates a widget that shows the most recent comments across a number of sites that you don’t control (e.g. getting the latest comments from a variety make/core inside a personal dashboard … and having the ability to bookmark certain comments or posts into a “read later” list for later consumption).

      As @getsource mentions above there are some fantastic wins by moving these interactions that currently depend on admin-ajax.php into standard, cacheable API calls.

      The most convincing dissenting opinion that gave me reason to pause was @JJJ‘s post that merging would hinder development. I do believe that is true. However, I also believe @rachelbaker is correct in that maintaining parity within the plugin as a long-term stand-alone is implausible. Given the choice between a REST API that can adapt and change quickly at the expense of dying slowly from a thousand cuts and a REST API that changes slowly but maintains perfect core parity I will pick the latter, every time.

      TL;DR: I really want to see the REST API land in core because I want to build some fantastic utilities (for myself and others) that can communicate with many sites without necessarily requiring administrative access (the ability to install the REST API plugin) within those sites.

    • K.Adam White 2:30 pm on October 17, 2016 Permalink | Log in to Reply

      I don’t think we’ve noted yet that the endpoints here don’t just encompass the built-in types, but also the endpoints that extend them — `WP_REST_Controller` provides a strong base for implementing new endpoints, and a custom post type with `show_in_rest => true` will automatically pick up behavior extending that class without any further action from the developer than a single line in `register_post_type`.

      Aside from the benefits of augmenting a shared resource like the posts collection @joostdevalk mentions above, having a sharable code foundation for new custom classes has the potential to reduce a lot of endpoint class duplication and fragmentation across the plugin ecosystem.

  • K.Adam White 6:36 pm on October 12, 2016 Permalink |
    Tags: ,   

    REST API Team Update, 4.7 Week 8 

    Summary: Beta 15 has been released, there are open questions that would benefit from your feedback, and the Content API Endpoints and OAuth Server are being proposed for merge as distinct, separate enhancements to the existing WordPress REST API infrastructure.

    REST API v2 Beta 15 released

    The 15th beta release of the REST API content endpoints plugin was released on October 7. This release builds on top of the recent Beta 14 to…

    • Add support for Post Meta, Term Meta, User Meta and Comment Meta within their parent endpoints
    • Introduce a settings endpoint to allow key site setting values to be retrieved & modified using the API
    • Introduce query parameters to query for posts that are NOT IN one or many terms of specific taxonomies
    • Resolve bugs, including bad comparison logic when updating comments.

    Please try it out and report any outstanding issues; the REST API project gained its 90th code contributor this week and the team is deeply grateful for the energy and support of the broader WordPress community in testing out this merge-candidate plugin!

    New Questions & Discussion Items

    Items which have arisen through final ticket triage & review on which the team seeks feedback:

    1. Should the `filter` shim should be removed prior to merge? It is the majority position of the API team that `filter` be deprecated to dramatically improve the simplicity and consistency of API query functionality
    2. How should comments be handled for password-protected posts? Should the password be passed as a query parameter with the PUT/POST request, or is there a better option?
    3. Should the API match core’s logic when users with the `unfiltered_html` capability are creating or updating Posts or Comments?

    Meeting Notes

    At the weekly team meeting on October 10 the group reviewed open issues in the 2.0 milestone, which represents the candidate for our merge proposal shared last week.

    Meeting attendees agreed to review open issues and pull requests individually, and to reconvene on Tuesday at 1500UTC to ensure all priority tickets had an owner.

    At that meeting on October 11, the team reviewed the incoming feedback around the OAuth plugin (linked above). While the API team feels that having a built-in authentication solution provides a much-needed service, particularly to developers building mobile and desktop applications, the design and usability feedback we have received does indicate that the plugin needs more work.

    OAuth’s place in the Merge Proposal

    The API Team believes that the identified issues are resolvable, that the OAuth plugin is on track and that it should still be considered for merge in 4.7. However, after discussion within the team, input from @matt, and advice from @aaroncampbell and other core committers, we have edited our merge proposal to submit the Content API Endpoints and OAuth server as separate merge candidates. The API Team proposes both components for merge, but we submit the content endpoints for consideration independently of the OAuth1 server.

    Content Endpoints Without OAuth

    The Content API endpoints are stable, well-tested, and in wide production use across a variety of applications. Theme and plugin developers will benefit from having canonical, well-tested API endpoints in core, which may be used to query WordPress both from PHP code and from JavaScript applications running on the front-end or admin of WordPress. Sharing the endpoints for core data types enables increased consistency of what data is exposed and how it is persisted across different plugins, improving consistency and shortening development time by using . These themes and plugins have full read and write access to the API using the existing cookie & nonce authentication.

    Mobile and desktop applications can leverage these same endpoints in a read-only capacity to create a variety of powerful reader-oriented applications and tools that expand the capability of what WordPress can do today, such as a unified reader for Make WordPress blogs and other experiments hypothesized by @jorbin.

    Should OAuth 1 not be accepted for 4.7, secure write access for these external applications would still be only a plugin install away; and while having an OAuth server in core will provide a canonical approach for authenticating from remote applications, depending on the needs of a specific site or specific client application other authentication schemes may actually be preferable. Plugins exist for JWT Authentication and of course OAuth 2, and should OAuth 1 not be accepted for 4.7 these plugins may still be installed to enable an external application to opt-in to secure write access to your WordPress site.

    In Summary

    The API team submits for 4.7 merge consideration two enhancements to the REST API infrastructure: the Content API Endpoints for core WordPress datatypes, and an OAuth server which will reduce the setup time needed to securely interact with those endpoints from outside of WordPress. We believe these enhancements are each individually sufficiently tested and mature to meet the quality and security standards of WordPress Core, and each individually provides wide-reaching benefit to WordPress developers, and through them to the authors, readers & publishers of the web.

  • K.Adam White 9:57 pm on October 6, 2016 Permalink |
    Tags: ,   

    REST API Team Update (4.7 week 7) 

    Our two (pt1) part (pt2) (split due to team travel) weekly meeting is now complete, and we have some new updates from the API team!

    Team review & commentary is requested on “Open Questions on Settings” and “Open Questions on Meta”, below.


    This Pull Request for adding Settings support to the API, resolving one of the few remaining major content gaps in the API, is almost ready to be merged into the rest-api feature plugin. Settings are exposed as keys on the resource `/wp/v2/settings`, e.g.:

        title: 'WordPress Develop',
        description: 'Just another WordPress site',
        url: 'http://src.wordpress-develop.dev',
        email: 'admin@local.dev',
        timezone: '',
        date_format: 'F j, Y',
        time_format: 'g:i a',
        start_of_week: 1,
        language: 'en_US',
        use_smilies: true,
        default_category: 1,
        default_post_format: '0',
        posts_per_page: 10

    This resource is only accessible or modifiable if you are authenticated as a user with the `manage_options` capability.

    Open Questions on Settings

    Team feedback is requested on the below, and on the settings proposal in general.

    1. What do we do if a setting value in the database does not match the type used in `register_setting`?
      • This becomes a problem when there is serialized data in the `option` value. Right now we are forcing this to be a `null` value in the rest api responses. The problem with this approach is that sending that response data back to the settings endpoint will cause the deletion of that option value (as `null` in this case is essentially a delete operation).
    2. Having support for `object` recursion and `array` types in the Schema would be very nice, allowing settings that are either objects or arrays.
      • We propose that does not need to be resolved prior to merge, and may be added in a subsequent cycle.
    3. Currently, reading all options at `/wp/v2/settings` is behind a `manage_options` cap check: we need to work out if we want to publicly expose option values for some settings.
      • If we do this, we’d need a way in `register_setting` (or via some kind of `read_setting` meta cap) to work out which settings should be exposed publicly (or at specific permissions checks).
      • Site title and description are still available on the root `/wp-json/` resource index; several other settings here can be inferred from other responses or site content. We propose that this resource be left as requiring `manage_options` caps, and move establishing a mechanism in core to register a setting as public be handled in a subsequent development cycle.

    Setting Registration

    For your settings to be exposed in the REST API, you need to register them. WordPress includes a register_setting function which is not usually required to get/set options, but is required for API support.

    To register your field, simply call register_setting and set the show_in_rest flag to true.

    register_setting( 'group', 'option_name', array(
        'show_in_rest' => true,

    register_setting Arguments

    register_setting is part of WordPress core, but isn’t heavily used in most parts of core, so you may not have seen it before. Here are the options relevant to the REST API:

    • show_in_rest – Should the setting be exposed in the API? true for default behaviour, or an array of options to override defaults (see below).
    • type – This is the type of data the setting is. Can be `string`, `number`, or `boolean` (so far).
    • description – Human-readable description of what the field is for. The API exposes this in the schema.
    • sanitize_callback – Callback to sanitize the value before it’s stored in the database. See the "sanitize_{$object_type}_meta_{$meta_key}" filter.

    REST API-Specific Arguments

    The show_in_rest parameter defaults to false, but can be set to true to enable API support. Out of the box, the API makes some assumptions about your setting, but you can override these by setting show_in_rest to an options array instead:

    register_setting( 'group', 'option_name', array(
        'show_in_rest' => array(
            'name' => 'fieldname'

    The options you can set are:

    • name – The key exposed via the REST API. For example, if your setting starts with an underscore, you may want to remove this for the API.
    • default – The default value for the setting via the REST API if it’s not set in the database.
    • schema – The JSON Schema options for the field. Exposed via OPTIONS requests to the post. This is generated automatically based on other parameters, but can be specified manually if you’d like to override it.

    Settings Defaults

    We’d also love feedback on ticket #38176, this adds the ability to specify a default value for an option via `register_setting()`. As you can see from the above, we are currently defining the `default` value within
    the `show_in_rest` options, as there’s no way to do this in the Settings API. We’d like for there to be a way to do this in core, so `get_option()` could default to the value set in `register_setting( … [ default => ‘myvalue’ ])`
    when no default is specific in `get_option`.


    Meta is also ready to be merged into the plugin, and also could use review from the broader WordPress team. Similar to custom post types and taxonomies, and as discussed previously, only meta that opts-in to API support is available through the REST API.

    Open Questions on Meta

    1. Right now, all meta registered through the mechanism below is assumed to be visible wherever its parent object appears. Meta values registered to a public post will be visible on that post without authentication.
      • Is it acceptable to expose registered meta fields on objects in this way, where the meta visibility will match the visibility of the parent object?
    2. As described in this comment, when you have multiple of the same value stored in a meta key, it will delete all matching values. For example, if you had a meta value [ 11, 13, 13, 13, 13 ] and attempted to remove one 13, it would result in the value [ 11 ].
      • Should multiple instances of the same value be able to be stored in a `single => false` meta field?

    Meta Registration

    For your meta fields to be exposed in the REST API, you need to register them. WordPress includes a register_meta function which is not usually required to get/set fields, but is required for API support.

    To register your field, simply call register_meta and set the show_in_rest flag to true.

    register_meta( 'post', 'field_name', array(
        'show_in_rest' => true,

    Note: register_meta must be called separately for each meta key.

    register_meta Arguments

    register_meta is part of WordPress core, but isn’t heavily used in most parts of core, so you may not have seen it before. Here are the options relevant to the REST API:

    • show_in_rest – Should the field be exposed in the API? true for default behaviour, or an array of options to override defaults (see below).
    • description – Human-readable description of what the field is for. The API exposes this in the schema.
    • single – Is this field singular? WordPress allows multiple values per key on a single object, but the API needs to know whether you use this functionality.
    • sanitize_callback – Callback to sanitize the value before it’s stored in the database. See the "sanitize_{$object_type}_meta_{$meta_key}" filter.
    • auth_callback – Callback to determine whether the user can write to the field. See the "auth_post_{$post_type}_meta_{$meta_key}" filter.

    REST API-Specific Arguments

    The show_in_rest parameter defaults to false, but can be set to true to enable API support. Out of the box, the API makes some assumptions about your meta field, but you can override these by setting show_in_rest to an options array instead:

    register_meta( 'post', 'field_name', array(
        'show_in_rest' => array(
            'name' => 'fieldname'

    The options you can set are:

    • name – The key exposed via the REST API. For example, if your meta key starts with an underscore, you may want to remove this for the API.
    • schema – The JSON Schema options for the field. Exposed via OPTIONS requests to the post. This is generated automatically based on other parameters, but can be specified manually if you’d like to override it.

    Using Meta over the API

    Meta is added to existing resources as a new meta field. For example, to get the meta for a single post, fetch the post at /wp/v2/posts/{id}, then look in the meta field. This is a key-value map for the registered fields.

    To update a field, simply send back a new value for it.

    Setting a field to null will cause the value to be removed from the database. If a field has a default value set, this essentially “resets” the value to the default (although no default will be stored in the database).

    For meta fields which can hold multiple values, this field will be a JSON list. Adding or removing items from the list will create or remove the corresponding values in the database.

    Other Updates

    • Add a {taxonomy}_exclude query parameter to query for resources NOT IN a particular taxonomy term_id
    • Decide against supporting full tax_query functionality via filter[tax_query]
    • Defer supporting auto-draft to a future cycle, as it did not have the expected benefits and the applicability of that state to the API is not generally understood
    • Weston Ruter 12:29 am on October 7, 2016 Permalink | Log in to Reply

      @kadamwhite in regards to the /wp/v2/settings endpoint, has there been a discussion as to whether it should be called /wp/v2/options instead? I say this because a “setting” is a somewhat overloaded term in WordPress. In the customizer it is a model that represents any data type in WordPress, be it an option, theme mod, nav menu, post, etc. Likewise, it’s conceivable that register_setting() could potentially go the same route to also be used for registering non-option settings. Since it is only options and options alone that are being returned by this endpoint, should it not be just called “options”?

    • K.Adam White 7:08 pm on October 7, 2016 Permalink | Log in to Reply

      @westonruter There was indeed discussion around this; “setting” is definitely overloaded, but since the resources that are being exposed are registered as “settings” we felt that settings was the most consistent word available. Options are a subset of settings, and the opposite is not necessarily the case; having a settings endpoint is more flexible long-term as additional settings become supported.

    • sba7elfol 12:12 am on October 10, 2016 Permalink | Log in to Reply

      network settings (for multisite) will be exposed too?

    • Mikko Virenius 9:30 am on October 11, 2016 Permalink | Log in to Reply

      If full tax_query won’t be supported, how tax query relations will be handled?

      • K.Adam White 2:30 pm on October 11, 2016 Permalink | Log in to Reply

        For every API-registered taxonomy, such as categories, two query parameters are added: a `?categories[]=` parameter to provide category terms to match with an OR relation (equivalent to tax_query with `{ taxonomy: ‘category’, field: ‘term_id’, terms: [ id1, id2 ] }`; and a `?categories_exclude[]=` parameter that provides an array of term IDs with operator NOT IN. Any taxonomy registered to the API can be used in this way, the query parameters will be derived from its “rest_base” property. So what we have now gets us almost all the way there; while no AND relation is supported at present, which is definitely an inconvenience, that last piece is something we’re continuing to discuss and I’d love to get your input on how to provide AND support as a first-party query option.

  • K.Adam White 9:31 pm on September 30, 2016 Permalink |
    Tags: ,   

    REST API Meeting Agenda for Oct 3 2016 

    REST API: Meeting Agenda for Oct 3, 2016

    The weekly meeting for the API team will be on Monday at 2016-10-03 14:00 UTC in #core-restapi. On the agenda:

    • Update on Settings from @joehoyle
    • Update on Meta from @rmccue
    • 4.7 Merge Plan TODOs

      • Decision on supported authentication methods
      • Progress on outside review
      • Timeboxed open floor
    • Review open PRs
    • Find owner for open tickets, e.g. some OAuth/Cookie conflicts
  • K.Adam White 5:30 pm on September 27, 2016 Permalink |
    Tags: , ,   

    API Team Update 

    API Team Update Sept. 27 2016

    The API team met yesterday on slack for our weekly update, which this week was predominately focused on follow-up from last Thursday’s comprehensive GitHub issues scrub.

    Since the previous API team update the group has been making steady progress through the gameplan outlined in that post. To give a quick update on a few key “quirky” issues that had been identified:

    Password-Protected Posts

    As noted in last week’s dev chat, password-protected posts will be included in collections with their content set to '', and the content can be viewed by passing ?password=XXXXX as a query or GET parameter when querying for a specific post. Query parameters are not an ideal solution: Authorization headers are out because you can’t have multiple authorization schemes in one request; cookies don’t afford enough control to browser clients, and custom headers aren’t respected by caches. See GH issue #2701 for more background, and check out the open pull request to review the specifics of the implementation.

    Sticky Posts

    After much debate there is now a path forward for handling sticky posts as well. Following this open pull request, sticky posts are included in the /wp/v2/posts collection, but are not given special treatment in terms of ordering—a sticky post will, by default, be displayed ordered by date or whatever orderby has been set for the request. The parameter ?sticky=true may be passed to return only sticky posts; ?sticky=false may be passed to exclude sticky posts from the response.

    There is ongoing discussion around how the API could surface posts in the “normal loop order,” with stickies on top, followed by non-sticky posts. @jorbin will propose a follow-up enhancement that could be added in to the API in a later cycle. See GH issue #2210 and associated slack discussion for more commentary.

    Meta Support

    A pull request is open on the API meta endpoints repository to add support for registering meta with the API using the main register_meta function. This PR includes a comprehensive readme explaining how meta handling works. Once merged & reviewed, this functionality will be PR’d against the primary REST API plugin repository.

    Site Settings (Options) Support

    A pull request has merged into the API site endpoints repository which adds support for accessing and manipulating site settings through the API. These endpoints will be PR’d against the core REST API plugin repository this week.

    Discussion items for 9/28 dev chat

    This project is not quite done yet, and in tomorrow’s dev chat the API team will be looking to the broader WordPress team for input on three priority issues that need a decision:

    Upcoming Meetings

    Please join us in #core-restapi on chat.wordpress.org for our next two group meetings:

  • K.Adam White 7:58 pm on November 13, 2013 Permalink
    Tags: , , JSHint   

    Finding and Fixing JavaScript errors with JSHint 

    The JavaScript Coding Standards have been updated, so it’s time to move on to tackling our JSHint errors!

    JSHint is a tool to check for errors in JavaScript code. As was discussed last week, we’re kicking off a small effort to work through our core JavaScript files. To get through the errors revealed by JSHint as quickly as possible, we’re following the model established by the Inline Docs team and posting a list of files with issues so that people can “claim” the files they’d like to fix!

    At the bottom is a list of every file in core that is displaying JSHint errors. Files with a checkmark have been patched and should now be passing lint. Files marked with (@username #xxxxx) are already claimed, and being worked on.

    Please read and understand the process we’ll be following to address these issues! Many thanks to @azaozz, @nacin and @jorbin for helping identify the safest way to approach fixing these errors, and to @rzen for posting the Inline Docs article on which we based this guide.

    How to contribute:

    1. Leave a comment on this post with the file* you’re about to edit (check the list first to make sure it hasn’t already been claimed).
    2. Update your local WordPress SVN to the latest version of WordPress trunk (currently 3.8-alpha).
    3. Create a new ticket on Trac for the file.
      JSHint-related trac ticket settings

      • Format the title as “jshint shouldn’t throw errors – path/to/file.js”.
      • Assign the ticket to the “Build Tools” component.
      • Make sure your email is stored in Trac’s preferences

      If you are logged in, you can click this link to automatically open a ticket with the right settings.

    4. Edit the file, and make a patch. Please make sure you create the patch from the root directory of your WordPress SVN checkout. If you are working on a large file, consider making multiple patches for each type of change.
    5. Upload your patch to the Trac ticket you created, and add the keyword “has-patch”.

    *Note: We strongly encourage you to work on one file at a time. These shouldn’t take very long, but if you call a bunch at once and get tied up, we won’t be able to get through these as quickly as possible. To quote @rzen from the inline docs effort, “your edits should be made and patched swiftly so that they aren’t invalidated by (or don’t invalidate) another patch.”

    Keeping Discussions Focused:

    Any discussion about the specifics of a patch itself should happen on Trac. Discussion about the overall effort should take place during our standing weekly meeting, on Wednesdays at 1900 UTC in #wordpress-dev*.

    Files needing patches:

    Checked files are now passing JSHint

    See all open tickets in the Build Tools component

    For tips on dealing with global variables, inlined third-party code within first-party scripts, etc, see the JSHint tips in the JavaScript Coding Standards

    For the curious, this list was created with a jazzy little command @nacin came up with to pipe Grunt output through ack:

    grunt jshint --force | ack '^Linting src/' | ack -o 'wp-.*.js' | sort | uniq -c | sort

    What we’re NOT doing

    The two JSHint options called out in the earlier post, “curly” and “eqeqeq,” would ordinarily make up the vast majority of the errors JSHint reports in our files. We’ve currently set Grunt and JSHint to ignore these two types of errors when JSHint is run against core. While these are best practices, we’ll come back to them once we address the more significant code smell issues like undefined variables.

    Also note that we’re not tackling whitespace or non-JSHint-related refactoring during this effort. We’ll get there, but we have to mitigate the risk to core as much as possible so we don’t interrupt the 3.8 cycle. Keep your changes focused on passing JSHint this go-around.

  • K.Adam White 9:48 pm on November 5, 2013 Permalink
    Tags: ,   

    JavaScript Coding Standards 

    The PHP files in WordPress core become cleaner and easier to read with every release, thanks in part to our standards for PHP code style. Our JavaScript, on the other hand, hasn’t gotten nearly enough love. This post is intended to open up the recent discussion around JavaScript style to the greater community so we can make up for lost time.

    Don’t we already have a style guide for JavaScript?

    Back in March, @tommcfarlin added a set of coding standards for JavaScript to the developer handbook. These WordPress JS coding standards are a great work-in-progress, but weren’t fully comprehensive (leading to some comment threads clarifying various areas). More importantly, without any clear implementation plan the style guide failed to gain traction.

    At WordCamp Boston’s core contributor day I revisited this style guide with @mattwiebe and Corey Frang (@gnarf37). It is important to identify *and implement* conventions for JS style ASAP because syntax issues in the JS within WordPress may hide latent bugs, and inconsistent code discourages contribution. Focusing on implementation lead us to look for an existing, proven JS style guide with a .jshintrc file (a set of configuration options for the JSHint code quality tool) which we could adopt largely as-is: Getting JSHint in place lets us see the biggest issues in our JS, so we can begin tackling them incrementally (perhaps in the same manner as the inline docs effort).

    After looking at Idiomatic.js and several other widely-adopted JS style guides, we feel the jQuery Foundation’s jQuery Core JavaScript Style Guide guide is the closest match for what we need in WordPress.

    Adopting the jQuery Core JavaScript Style Guide

    jQuery’s guide shared WordPress core’s love of white space—the same “when in doubt, space it out” mantra from the existing JS style page. Moreover, jQuery’s code conventions have been referenced in trac tickets as an example of how we should be writing our code. Adopting their guide wholesale capitalizes on our stylistic similarities, and will let us adopt their .jshintrc and any future code quality tools they write with minimal changes.
    (More …)

    • Pbearne 9:55 pm on November 5, 2013 Permalink | Log in to Reply

      I will be happy do a bit of this.

    • deltafactory 9:57 pm on November 5, 2013 Permalink | Log in to Reply

      I’ve been thinking about threequals and curly-braces since Boston. It’s hard to break the habit.

      I’d like to help with the cleanup effort. It would benefit me to familiarize myself with more of the JS bits of WordPress.

    • Mike Bijon 9:58 pm on November 5, 2013 Permalink | Log in to Reply

      After reading the summary in email, my only concern was jQuery’s use of double-quotes vs. ours … seeing the longer article, that’s handled and I can’t think of any reasons to object.

      On the + side, adopting jQuery’s standards wholesale should reduce maintenance & debate. Plus, getting started sooner than later to *any* standard should help speed JS work & maybe help a few overly-debated JS tickets in Trac.

      Looking forward to seeing the sprint schedules

    • adamsilverstein 10:27 pm on November 5, 2013 Permalink | Log in to Reply

      Great post, thanks! I will try to make the meeting tomorrow and assist in the cleanup effort.

    • Matt Wiebe 10:46 pm on November 5, 2013 Permalink | Log in to Reply

      I have another (virtual) meeting at the same time, but I should be able to chime in.

      Thanks for pushing this forwards @kadamwhite 🙂

    • ericsherred 10:59 pm on November 5, 2013 Permalink | Log in to Reply

      Sounds like fun to me.

    • Dion Hulse 12:07 am on November 6, 2013 Permalink | Log in to Reply

      Wouldn’t it be better for us to standardise on for ( var i = 0; i < 100; i++ ) { instead of including var outside of the iterator? IIRC, including it outside was for some rather old browsers that we no longer (and probably haven’t for a long time) supported.

      • Andrew Ozz 1:12 am on November 6, 2013 Permalink | Log in to Reply

        As far as I remember defining all vars at the beginning of the scope mimics the actual way the script is parsed. Don’t think defining vars in the middle or end was a problem in any browser.

        • Dion Hulse 1:19 am on November 6, 2013 Permalink | Log in to Reply

          I thought I’d heard a rumour of an early IE bug.. but you’re probably right, defining it earlier is most likely only a parsing optimization, something we probably don’t need to worry about.

        • Tom McFarlin 1:52 am on November 6, 2013 Permalink | Log in to Reply

          +1 to this.

          Including all var declarations at the beginning of the function is how the script is parsed, and for those who are fans of JSLint, you’ll notice that combining all var declarations together is preferred[0].


        • K.Adam White 2:14 am on November 6, 2013 Permalink | Log in to Reply

          As Tom notes, Andrew is correct—Variable declarations are “hoisted” to the top of the function’s scope, so declaring all your variables first is a best practice (it unifies the code’s visual structure with how it is parsed by the JS engine). There’s actually a “onevar” parameter in JSHint to enforce this style.

      • WraithKenny 2:10 am on November 6, 2013 Permalink | Log in to Reply

        I think it’s better, considering `for ( i = 0; i < 100; i++ ) { … } … var i = 2; alert( i );` would be confusing ('100') because of hoisting.

    • Andrew Ozz 1:47 am on November 6, 2013 Permalink | Log in to Reply

      Re-reading jQuery Core JavaScript Style Guide again: apart from the single/double quotes, other differences are the lack of indentation for `case` in `switch` and the hard limit to 100 characters per line (counting tabs as 4 chars). All of the rest more or less match our PHP and current JS coding standards. We also (used to?) have few more, like the strong discouragement of using nested ternary operators.

      So the question is: should we adopt the jQuery standard “wholesale” and depart from our PHP coding standard or should we continue to keep our PHP and JS coding standards as close as possible?

      • Tom McFarlin 1:58 am on November 6, 2013 Permalink | Log in to Reply

        I’m for the adoption of jQuery standards as much as possible; however, I do err on the side of keeping the JavaScript closely-related to our PHP coding standards (which is what I tried to do with the first draft of the standards).

        The reason being is that I don’t think we, as developers, should have to maintain two different set of standards.

        When working on client-side code, I often find myself thinking What’s the server-side standard for this, again? and then I try to apply that.

        Because I – and I’m sure most of us – are so familiar with the PHP standards, perhaps we should implement a “when it doubt, default to PHP standards.”

      • K.Adam White 2:26 am on November 6, 2013 Permalink | Log in to Reply

        I’m of a case-by-case mind on this. For example, I’ve encountered very few situations where >100 characters in a line were truly needed (and not just a symptom of hard-to-read or overly-nested code), so I’d be inclined to keep that. On the flip side, I’m all for keeping indentation rules consistent with PHP.

        Thanks for raising these questions, this is exactly what we need! Both here and during tomorrow’s chat I hope to identify any other differences between our PHP style and the proposed guide, and make decisions about which way to go. We’ve already identified a few areas in which we want to go a different way than jQuery. It’s a useful set of default behaviors, but what style guide we adopt isn’t what’s important—what is important is that consistency.

        • Andrew Ozz 2:47 am on November 6, 2013 Permalink | Log in to Reply

          Yes, the “around 80, max 100 chars” limit might eventually surface when something has many levels of indentation (5 – 6 tabs). This is not so hard to hit with longer jQuery chains which should probably be broken on multiple lines. Thinking it may be nice to have it as a rule in the PHP coding standard too, just not sure if it needs to be enforced.

    • Tom McFarlin 2:02 am on November 6, 2013 Permalink | Log in to Reply

      I’m going to try to make it to the meeting – what server and channel will the meeting take place?

      • K.Adam White 2:12 am on November 6, 2013 Permalink | Log in to Reply

        Good point, that’s something people need to know: Freenode, right in #wordpress-dev. (Note: That time was selected because I was not aware of any conflicting meetings; If anybody has a meeting in #wordpress-dev scheduled at that time, please let us know and we’ll get another room!)

    • Paul Clark 4:09 am on November 6, 2013 Permalink | Log in to Reply

      Count me in for a JSHint sprint!

    • Gary Jones 9:22 am on November 6, 2013 Permalink | Log in to Reply

      Not sure I can make it tonight, so I’m leaving my thoughts here that hopefully someone can take into consideration during the meeting.

      General adoption of the jQuery standards: +1
      Two exceptions to those standards: +1

      Would like to see a push towards named rather than anonymous functions = more self-documenting code, fewer nested levels -> avoid hitting line limits, reduce complexity.

      Consider use of ‘es3’ option in .jshintrc, since WP still needs to support IE8-9, and that will catch use of reserved words being used as properties with dot notation etc.

      I’m up for helping out with some JS tidying.

    • K.Adam White 1:00 am on November 10, 2013 Permalink | Log in to Reply

      Just a heads-up for everybody waiting for an update on this: Hang tight for a day or two, I’m working with @kpdesign to get the JS Standards handbook page updated and up to our standards.

    • Lance Willett 3:36 am on November 12, 2013 Permalink | Log in to Reply

      Thanks for your work on this—more vigorous standards and cleaner code FTW.

compose new post
next post/next comment
previous post/previous comment
show/hide comments
go to top
go to login
show/hide help
shift + esc
Skip to toolbar