Tag Archives: json-api

Ryan McCue 5:05 am on April 29, 2015
Tags: json-api,   

WP REST API: Version 2.0 Beta 1

Hi there, we’re 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/ team. You may remember us from such releases as Version 1.1 “Hammock Hut” and Version 1.2 “S-M-R-T”. Today, we’re excited to announce the first 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. release of version 2 of the REST API: 2.0 Beta 1 “Ralph Wiggum”. Go and grab it from GitHub right now, we’ll wait.

Over the past 9 months, we’ve been reworking some of the important internals of the REST API to improve extensibility for site developers, and usability for both 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. developers and client developers. We’ve codified some of our important internal conventions, added plenty of new tools for you to play with and simplify your development, and reworked some of the less fantastic parts of 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.. We think these changes will make the API a whole lot better for everyone, and we’re excited to start getting your feedback on these changes.

One of the things that you’ll notice immediately when using version 2 is just how much hasn’t changed. There’s a lot of things that we’ve changed under the hood, but the fundamentals of the API haven’t changed up too much. Version 2 is a direct continuation of version 1, so most of the API will be instantly familiar to you if you’ve used version 1 before. We have a primer on the important changes since version 1, including a guide on migrating existing endpoints across to version 2.

Here’s some super important notes on version 2, before you get started:

  • No Backwards Compatibility: Version 2 is not backwards compatible with version 1. We have plans to ensure that a version 1 compatibility layer exists, but we’ve leaving that until the API has settled down fully before creating that. However, porting endpoints is easy if you want to give it a go.
  • No Forwards Compatibility: Beta 1 is also not guaranteed to be forwards compatible with future betas. Although this is a beta release, it’s still likely that parts of the REST API will change. However, at this point, the coreCore Core is the set of software required to run WordPress. The Core Development Team builds WordPress. infrastructure of the API is unlikely to change in a breaking manner, so internal plugin APIs are pretty solid. We reserve the right to break these in future though, so keep that in mind when updating.
  • Development Only: Due to the lack of forwards and backwards compatibility, we strongly recommend you do not run the beta in production environments. While it is possible to run it (both security and privacy have solid, thorough handling), any updates will likely break your site.
  • Run Concurrently: You can easily run both version 1 and 2 side-by-side, since the prefixes for all functions and filters have changed. This will require changing the URLURL A specific web address of a website or web page on the Internet, such as a website’s URL www.wordpress.org for version 2 however, which can be done with the following 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.: 
    add_filter( 'rest_url_prefix', function () { return 'wp-rest'; } );

With all this said, we’d love you to test the plugin as soon as possible. We’re looking for feedback on every part of the API, especially the changes since version 1. If there’s anything that has made it easier or harder since version 1, let us know. We’re continuing to improve the API every day, and now is the time to let us know what’s important to you. (P.S. Did I mention we have an issue tracker?)

We’re excited for this new stage of the API, and we hope you are too.

#json-api, #rest-api

Rachel Baker 8:39 pm on April 9, 2015
Tags: json-api,   

WP REST API Critical Security Release

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/ 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. version 1.2.1 is now available as a critical security release. This release fixes a serious information disclosure vulnerability, which allowed for unpublished content and post revisionsRevisions The WordPress revisions system stores a record of each saved draft or published update. The revision system allows you to see what changes were made in each revision by dragging a slider (or using the Next/Previous buttons). The display indicates what has changed in each revision. to be retrieved via the REST API.

All previous versions of the plugin are affected. All WP REST API users are strongly encouraged to update immediately. Update with one click from Dashboard → Updates, get it from the plugin directory (zip), or pull it from GitHub.

This release was coordinated by the REST API team and the WordPress coreCore Core is the set of software required to run WordPress. The Core Development Team builds WordPress. security team. The security team is pushing automatic updates for this plugin. Each 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". was separately patched; there are packages for 1.2.1, 1.1.3, 1.0.2, 0.9.2, and 0.8.2.

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.

If you have a question about the release, you can find the team in #core-restapi on WordPress.org Slack, or you can privately message @rachelbaker, @danielbachhuber, or @joehoyle.

#json-api, #rest-api

Rachel Baker 1:51 pm on March 24, 2015
Tags: json-api,   

WP REST API: Version 1.2

Hello everyone. Remember us? Today, I can finally announce the release of version 1.2 of the WP REST API.

A short nine months after our last release we have support for Cross-Origin Resource Sharing, full request hijacking, JSONJSON JSON, or JavaScript Object Notation, is a minimal, readable format for structuring data. It is used primarily to transmit data between a server and web application, as an alternative to XML. encode/decode errors, and a swarm of 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.

Here are the expanded highlights:

  • Add handling for Cross-Origin Resource Sharing (CORS) OPTIONS requests.

    Preflighted requests (using the OPTIONS method) include the headers Access-Control-Allow-Origin, Access-Control-Allow-Methods, and Access-Control-Allow-Credentials in the response, if the 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. origin is set.

    (props @rmccue, #281)

  • Allow overriding full requests.

    The json_pre_dispatch 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. allows a request to be hijacked before it is dispatched. Hijacked requests can be anything a normal endpoint can return.

    (props @rmccue, #281)

  • Check for JSON encoding/decoding errors.

    Returns the last error (if any) occurred during the last JSON encoding or decoding operation.

    (props @joshkadis, @rmccue, #461)

  • Add filtering to the terms collection endpoint.

    Available filter arguments are based on the get_terms() function. Example: /taxonomies/category/terms?filter[number]=10 would limit the response to 10 categoryCategory The 'category' taxonomy lets you group posts / content together that share a common bond. Categories are pre-defined and broad ranging. terms.

    (props @mauteri, #401, #347)

  • Add handling for the role parameter when creating or updating a user.

    Allow users to be created or updated with a provided role.

    (props @pippinsplugins, #392, #335)

  • Add handling for the post_id parameter when creating media. Allow passing the post_id parameter to associate a new media item with a post.

    (props @pkevan, #294)

  • Handle route matching for - in 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. and terms.

    Previously the regular expression used to match taxonomy and term names did not support names with dashes.

    (props @EdHurtig, @evansobkowicz, #410)

  • Handle JSONP callback matching for . in the function name.

    Previously the regular expression used to match JSONP callback functions did not support names with periods.

    (props @codonnell822, #455)

  • Fix the Content-Type 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. for JSONP requests.

    Previously JSONP requests sent the incorrect application/json Content-Type header with the response. This would result in an error if strict MIME checking was enabled. The Content-Type header was corrected to application/javascript for JSONP responses.

    (props @simonlampen, #380)

  • Add $context parameter to json_prepare_term filter.

    Terms responses can now be modified based on the context parameter of the request.

    (props @traversal, #316)

  • Move the JavaScriptJavaScript JavaScript or JS is an object-oriented computer programming language commonly used to create interactive effects within web browsers. WordPress makes extensive use of JS for a better user experience. While PHP is executed on the server, JS executes within a user’s browser. https://www.javascript.com client library into 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..

    Previously, the wp-api.js file was a separate repository. The JavaScript client has moved back into the plugin to coordinate code changes.

    (props @tlovett1, #730)

  • Always return an object for media sizesThe media sizes value should always be an object even when empty.

    Previously, if a media item did not have any sizes set, an empty array was returned.

    Compatibility warning: Clients should be prepared to accept an empty object as a value for media sizes.

    (props @maxcutler, #300)

  • Give top-level posts a null parent value.

    For date type consistency, post parent property should be null. Previously, parent-less posts returned 0 for parent.

    Compatibility warning: Clients should be prepared to accept null as a value for post parent.

    (props @maxcutler, #391)

  • Move permission checks out of WP_JSON_Posts.

    Introduce json_check_post_permission() function to allow post object capabilitycapability A capability is permission to perform one or more types of task. Checking if a user has a capability is performed by the current_user_can function. Each user of a WordPress site might have some permissions but not others, depending on their role. For example, users who have the Author role usually have permission to edit their own posts (the “edit_posts” capability), but not permission to edit other users’ posts (the “edit_others_posts” capability). checks to be used outside the WP_JSON_Posts class.

    Deprecation warning: Calling WP_JSON_Posts::check_read_permission and WP_JSON_Posts::check_edit_permission is now deprecated.

    (props @rachelbaker, #486, #378)

  • Split comment endpoints into separate class.

    All comment handling has moved to the WP_JSON_Comments class.

    Deprecation warning: Calling WP_JSON_Posts::get_comments, WP_JSON_Posts::get_comment, WP_JSON_Posts::delete_comment, and WP_JSON_Posts::prepare_comment is now deprecated.

    (props @whyisjake, @rmccue, @rachelbaker, #378)

  • Split 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 into separate class.

    All post meta handling has moved to the new WP_JSON_Meta_Posts class.

    Deprecation warning: Calling WP_JSON_Posts::get_all_meta, WP_JSON_Posts::get_meta, WP_JSON_Posts::update_meta, WP_JSON_Posts::add_meta, WP_JSON_Posts::delete_meta, WP_JSON_Posts::prepare_meta, and WP_JSON_Posts::is_valid_meta_data is now deprecated.

    (props @rmccue, @rachelbaker, #358, #474)

  • Rename internal create methods.

    Deprecation warning: Calling WP_JSON_Posts::new_post, WP_JSON_CustomPostType::new_post and WP_JSON_Posts::new_post is now deprecated.

    (props @rachelbaker, @rmccue, #374, #377, #376)

  • Fix discrepancies in edit and create posts documentation examples.

    Corrected the edit and create posts code examples in the Getting Started section. The new post example was updated to include the required content_raw parameter. The new and edit posts examples were updated to use a correct date parameter.

    (props @rachelbaker, #305)

  • Update the cookie authentication documentation examples.

    With 1.1 the localized JavaScript object for wp-api.js changed to WP_API_Settings. This updates the Authentication section documentation nonce example to use the updated object name.

    (props @rachelbaker, #321)

  • Add flexibility and 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 support to unit tests.

    Tests can be run from any WordPress install, and are not limited to only as a plugin installed within a 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/ develop checkout. Unit tests are now run against a multisite installation.

    (props @danielbachhuber, #397)

As always, we’ve got a full list of all the changes and a longer changelog.

Here’s who contributed to this release:

$ git shortlog 1.1.1...1.2 --summary
    1  Chris O'Donnell
    12  Daniel Bachhuber
     1  David Hayes
     4  DrewAPicture
     7  Eddie Hurtig
     2  JDGrimes
     1  Japh
     5  Josh Kadis
     1  Josh Pollock
     1  Justin Sternberg
     2  K.Adam White
     1  Marko Heijnen
     2  Max Cutler
     2  Mike Auteri
     1  Milan Dinić
     1  NikV
     3  Paul Kevan
     2  Pippin Williamson
    86  Rachel Baker
    73  Ryan McCue
     7  Sarah Gooding
     1  Simon Lampen
     2  Taylor Lovett
     1  Travis Hensgen
     1  Wayne K. Walrath
     1  ironpaperweight
     1  kalenjohnson
     1  kellbot
     1  paul de wouters

Release Plan

1.2 will be the last major releasemajor release A release, identified by the first two numbers (3.6), which is the focus of a full release cycle and feature development. WordPress uses decimaling count for major release versions, so 2.8, 2.9, 3.0, and 3.1 are sequential and comparable in scope. on the 1.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". of the plugin. We’ve been working hard over the past four months, with the aim of releasing a 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. for version 2.0 next month.

For existing code written for version 1.x we will issue a final 1.x release as a compatibility shim to seamlessly connect existing code to version 2.

#json-api, #rest-api

Weston Ruter 11:04 am on January 26, 2015
Tags: , , , json-api, ,   

Proposal: Customizer Transactions

Note: This post has been superseded by Customize Changesets (formerly Transactions) Merge Proposal. See also Customize Changesets Technical Design Decisions.

You may be familiar with transactions in a database context. The idea is simple: once you start a transaction, any change made to the database in the current session will not be applied to other database sessions until a transaction COMMIT is done. Changes performed when the transaction is open will be reflected in any SQL SELECT queries made, and if you decide that you do not want to persist the changes in the transaction in the database, you can simply do ROLLBACK and the changes will be discarded. And actually WordPress already uses MySQLMySQL MySQL is a relational database management system. A database is a structured collection of data where content, configuration and other options are stored. https://www.mysql.com transactions, but only in unit tests: a rollback is done after each test is torn down to restore the database state for the next test.

The parallels between database transactions and the WordPress CustomizerCustomizer Tool built into WordPress core that hooks into most modern themes. You can use it to preview and modify many of your site’s appearance settings. are clear. When you open the Customizer you are starting a “settings transaction”. Any changes made to the settings in the Customizer get reflected in the preview only, and they get written (committed) to the database only when the user hits “Save & Publish”.

As good as the Customizer currently is, the way it has been implemented means that there are limitations on what we can do with it.

Current Limitations

The existence of modified settings in the Customizer is restricted to the life of a browser window. When a user changes a control in the Customizer and a setting is modified (with transport=refresh), an Ajax request is made with the changed settings data POSTed to the previewed URLURL A specific web address of a website or web page on the Internet, such as a website’s URL www.wordpress.org. The Customizer then boots up and adds the setting preview filters based on what it sees in $_POST['customized'] so that the changes are reflected when WordPress builds the page. When this Ajax response is received, the Customizer JSJS JavaScript, a web scripting language typically executed in the browser. Often used for advanced user interfaces and behaviors. code then writes the response to the iframe via document.write().

There are a few downsides to this current approach:

One problem is that if the user navigates away from the Customizer, they lose their drafted settings. To get around this, an AYS dialog was added in #25439, but this still doesn’t account for browser crashes or system failures. It would be ideal if the settings could persist in the same way as when drafting a post.

Another downside is that whenever the preview needs to refresh it has to re-send all the modified settings so that the Customizer preview will have them available to add to the filters, since the Customized settings data is not persisted in WordPress in any way. There’s a performance hit to continually send all data with each request, which was partially improved with #28580.

Additional problems stem from the Ajax POST + document.write() approach to refreshing the preview. Since the Customizer iframe starts out at about:blank and the HTMLHTML HyperText Markup Language. The semantic scripting language primarily used for outputting content in web browsers. is written to from the document at customize.php, much of the context for the document in the iframe gets inherited from the parent window. This means that window.location in the preview window is the same as in the parent window: /wp-admin/customize.php. Needless to say, this means that JavaScriptJavaScript JavaScript or JS is an object-oriented computer programming language commonly used to create interactive effects within web browsers. WordPress makes extensive use of JS for a better user experience. While PHP is executed on the server, JS executes within a user’s browser. https://www.javascript.com code running in the Preview will not run as expected (e.g. #23225).

The Customizer preview intercepts all click events and sends the intended URL to the parent window so that the Customizer can initiate the request to refresh the preview. The only way to change the current page in the preview is by clicking a standard links with a URL; any form submissions in the preview are completely disabled, resulting in the search results page not being reachable from within the preview (#20714). Any navigation system that uses JavaScript to change the window’s location also will fail, for instance using a dropdown.

The current unique method for refreshing the preview worked fine when the Customizer was limited to a handful of settings. But now as more and more of WordPress is being added to the Customizer, and now that themes are increasingly leveraging JavaScript, we need a more robust approach to implementing the Customizer which will solve the above challenges and provide new opportunities.

Customizer Transactions

The proposal is that we introduce persisted Customizer settings, in other words “Customizer transactions”. Here’s how it may work:

When opening the Customizer for the first time, a transaction UUID is generated. Whenever a setting changes, an Ajax request sends the updated setting to WordPress to be persisted in a wp_transaction post which has a post_name corresponding to that UUID (or such a transaction post is created on the fly if not existing already). Any changes made in the Customizer then get amended to the same wp_transaction post, which has a key/value JSONJSON JSON, or JavaScript Object Notation, is a minimal, readable format for structuring data. It is used primarily to transmit data between a server and web application, as an alternative to XML. blob as its post_content.

When a user hits the Save & Publish button, the underlying wp_transaction post gets a post status change to publish. When transitioning into this status, each of the settings in the transaction at that point get saved to the database—they get committed.

Instead of using an Ajax POST to send the customized settings to the preview, we then only have to reference the transaction UUID when loading URLs into the Customizer preview. What this means is that we no longer have to use a blank iframe but can load the window with the natural URL for what is being previewed (#30028), but just with the transaction UUID query parameter tacked on.

When this transaction UUID query parameter is present, filters get added to amend all URLs generated in the preview to also include this UUID, so the transaction context is persisted as the user navigates around the site in the preview window. Forms also get this transaction UUID added as another input element, so any form submissions will also keep the preview inside the transaction. Additionally, WP Ajax requests are intercepted to tack on the transaction UUID so that now even Ajax requests can be previewed in the Customizer without any extra work.

Now that the document in the preview window is actually at the URL being previewed (as opposed to about:blank), refreshing the preview is greatly simplified: instead of capturing scroll position, doing Ajax POST, writing the response with document.write(), and restoring the scroll position—now the preview window just has to do a simple location.reload(). JavaScript now runs in the expected context, and full JS applications can be previewed in the Customizer.

As noted above, each time the Customizer is opened and a setting is updated the first time, a wp_transaction post is created with a draft status, and this post gets updated each time a setting is changed during that Customizer session. You also can open the Customizer as a whole (at customize.php) with this transaction UUID supplied and that settings in that existing transaction draft will be loaded. This means you can draft Customizer settings and return to them later, or make some changes and then send it along to another user to finalize (realtime collaboration would be possible as well with some heartbeat integration, or else a locking mechanism would make sense). The capabilitycapability A capability is permission to perform one or more types of task. Checking if a user has a capability is performed by the current_user_can function. Each user of a WordPress site might have some permissions but not others, depending on their role. For example, users who have the Author role usually have permission to edit their own posts (the “edit_posts” capability), but not permission to edit other users’ posts (the “edit_others_posts” capability). to publish wp_transaction posts could be restricted to an administrator role, with other roles being able to save posts with a pending status to submit for review.

Also as noted above, the point at which the settings in a transaction get saved (committed) to the database is when the wp_transaction post transitions to a publish status. This being the case it naturally allows for transaction posts to be scheduled to apply in the future. If you want to make a bunch of changes to your site appear at midnight on Saturday, you could go in on Friday and add/remove widgets, change background images, and do anything else the Customizer allows and then have this transaction be scheduled for the desired time. When it publishes, all of the settings would go live on the site. This resolves #28721.

With each Customizer session resulting in a new transaction post being created, then there is automatically a Customizer revision history (see #31089). Every transaction that has a publish post status is a change that went live on the site.

Another side benefit to reworking the Customizer preview to load via a natural URL with the transaction UUID supplied is that there aren’t any intrinsic capabilitiescapability A capability is permission to perform one or more types of task. Checking if a user has a capability is performed by the current_user_can function. Each user of a WordPress site might have some permissions but not others, depending on their role. For example, users who have the Author role usually have permission to edit their own posts (the “edit_posts” capability), but not permission to edit other users’ posts (the “edit_others_posts” capability). needed to preview a transaction on the site. A setting change gets authorized at the time of the change, and the sanitized setting is then persisted in the transaction post. The preview then just applies the pre-authorized and pre-sanitized settings. The interesting side-effect of this is that it means Customizer previews (frontend URLs with the transaction UUID amended) can be shared with anonymous users to review. You can pop open the URL in the preview iframe into a new window and share it with any user for review, and they don’t need the capability to customize.

Lastly, something else that motivated my investigation into Customizer transactions is thinking about how the Customizer will relate to the upcoming REST API. How can 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/ be improved with the Customizer? Where do they intersect? If the REST API provides a transactions endpoint for doing CRUDCRUD Create, read, update and delete, the four basic functions of storing data. (More on Wikipedia.) operations on Customizer settings, and if the REST API also has global recognition for a customize_transaction_uuid query parameter in all requests, then it becomes possible for the Customizer to be used to preview changes in applications that merely interact with the JSON REST API, as long as they include the transaction UUID in the requests.

Partial Refresh

There’s one drawback I’ve encountered when implementing a patchpatch A special text file that describes changes to code, by identifying the files and lines which are added, removed, and altered. It may also be referred to as a diff. A patch can be applied to a codebase for testing. for what I’ve described above. As noted above, when a setting has a refresh transport, the preview window now does a regular location.reload(). When this happens, there is a momentary “flash of unloaded content” (white screen) which currently doesn’t happen when document.write() is employed to refresh the preview window. I’m not sure why this is, other than maybe document.write() initiates a synchronous DOM operation, whereas doing location.reload() initiates an asynchronous one. I’ve tried doing output buffering as well, to try to make sure the response gets sent all at once. But I haven’t had success. This is the current refresh behavior:

If no solution can be found for the white-screen-flash-during-reload issue, there is an alternative (besides the postMessage transport) which would provide an even better experience than even now with the “seamless” full page refresh: partial refresh (#27355).

When a setting change can’t be previewed purely with JavaScript (via postMessage), or it doesn’t make sense to re-implement all of the PHPPHP The web scripting language in which WordPress is primarily architected. WordPress requires PHP 7.4 or higher logic in JS (which is not DRY), the Customizer currently necessitates a full refresh of the entire page. With the proposed partial refresh transport, however, only the container element(s) in which the setting appears in the preview would get fetched from the server via Ajax and inserted into the DOM. This is much faster than having to refresh the entire page, and it retains the overall document state (e.g. whether the 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. is expanded or not).

There are challenges for implementing partial refresh in a way that it can be enabled by default, however. When implementing partial refresh support for widgets in the WidgetWidget A WordPress Widget is a small block that performs a specific function. You can add these widgets in sidebars also known as widget-ready areas on your web page. WordPress widgets were originally created to provide a simple and easy-to-use way of giving design and structure control of the WordPress theme to the user. Customizer feature-as-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. for 3.9, I found that themes had to explicitly opt-in to partial-refreshed widgets because a widget could be inside a sidebar that has a dynamic layout (e.g. jQuery Masonry) or the widget may have JS-driven functionality that has to be re-initialized when updated partial is injected. So partial refresh for widgets was removed from being included in WordPress 3.9, but the functionality has recently been resurrected in the Customize Partial Refresh plugin. More research is needed into how much partial refresh we can have enabled by default, and where we need explicit opt-in.

Call for Feedback

So there’s a lot of exciting possibilities introduced with Customizer transactions. I’d love to hear what you think. I have an working patch written and it exists in a pull request on GitHub. I welcome comments there on the PR. Naturally, the changes would need to be split up into smaller patches for committing to SVNSVN Subversion, the popular version control system (VCS) by the Apache project, used by WordPress to manage changes to its codebase..

Related tickets:

  • #30937: Add Customizer transactions (main ticketticket Created for both bug reports and feature development on the bug tracker.)
  • #30028: Load Customizer preview iframeiframe iFrame is an acronym for an inline frame. An iFrame is used inside a webpage to load another HTML document and render it. This HTML document may also contain JavaScript and/or CSS which is loaded at the time when iframe tag is parsed by the user’s browser. with natural URL
  • #30936: Dynamically create WP_Customize_Settings for settings created on JS client
  • #27355: Customizer: Add framework for partial preview refreshes
  • #20714: Theme customizer: Impossible to preview a search results page
  • #23225: Customizer is Incompatible with jQuery UIUI User interface Tabs.
  • #28721: Scheduled changes for the customizer
  • #31089: Customizer revisionsRevisions The WordPress revisions system stores a record of each saved draft or published update. The revision system allows you to see what changes were made in each revision by dragging a slider (or using the Next/Previous buttons). The display indicates what has changed in each revision.
  • #31517: Customizer: show a notice after attempting to navigate to external links in live previews

Appendix: Why not just use MySQL transactions?

Something interesting to investigate for the future would if we could take this another (lower) level and actually use MySQL transactions for the Customizer. This would make the Customizer much easier to extend beyond options and theme mods, as the Customizer could just start a MySQL transaction and when a setting is changed, just keep a log of any INSERT/UPDATE/DELETE statement performed during a MySQL transaction. They can then be re-played whenever the preview reloads, and then followed by a COMMIT when the Customizer is saved. These SQL statements can be saved in the wp_transaction post, as opposed to the JSON blob containing the key/value settings data. Or the use of MySQL transactions could go deeper and the SAVEPOINT could be utilized to store the transaction natively in MySQL.

But there are some concerns about using MySQL transactions: first, there’s the question of compatibility and whether MySQL transactions would be available on the wide array of hosting environments where WordPress runs, and what MySQL storage engines are used. Then there’s the question of how conflicts would be resolved when the auto-incremented IDs in the transaction diverge from those outside. And also there’s the concern of storing SQL statements the wp_transaction post’s post_content, and how this might introduce vulnerabilities. Lastly, if we use MySQL transactions as opposed to storing the staged settings in a wp_transaction post, then we’d miss out on being able to inspect the contents of a transaction to see what changes are contained within it.

In any case, using MySQL transactions would be an interesting alternative to the current WP_Customize_Setting abstraction.

#customize, #feature-selective-refresh, #javascript, #json-api, #partial-refresh, #rest-api

Ryan McCue 1:02 pm on July 26, 2014
Tags: json-api,   

JSON REST API: Version 1.1.1 (Security Release)

I’d like to announce the availability of version 1.1.1 of the JSON REST API. This is a security release for a minor security issuesecurity issue A security issue is a type of bug that can affect the security of WordPress installations. Specifically, it is a report of a bug that you have found in the WordPress core code, and that you have determined can be used to gain some level of access to a site running WordPress that you should not have., however we recommend all users running 1.1 upgrade as soon as possible. This release only affects users running 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. on a domain with other (non-WordPress) software running. Using the JSONP support built-in to the API, it is possible to serve up arbitrary Flash SWF files from the API, allowing these Flash files to bypass browser cross-origin domain policies. While WordPress includes built-in CSRF protection, other software running on the same domain may not include similar protections. As a workaround, JSONP support can be disabled on your site with: 

add_filter( 'json_jsonp_enabled', '__return_false' );
Thanks to @iandunn for reporting this issue to the team responsibly. We’d also like to announce that WP-API is now available on HackerOne. We invite security researchers and developers to report any potential security issues to us via HackerOne, allowing us to triagetriage The act of evaluating and sorting bug reports, in order to decide priority, severity, and other factors. and fix issues privately, and also award bounties for valid security reports.

#json-api, #rest-api

Ryan McCue 2:01 am on June 23, 2014
Tags: json-api,   

JSON REST API: Version 1.1

I’m happy to announce the availability of version 1.1 of the JSON REST API.

This release is a bit of a smaller, more focussed release as we work on increasing test coverage and squashing bugs. Here’s the juicy details:

  • Add new routes for taxonomies and terms.

    Taxonomies and terms have now been moved from the /posts/types/<type>
    namespace to global routes: /taxonomies, /taxonomies/<tax>,
    /taxonomies/<tax>/terms and /taxonomies/<tax>/terms/<term>

    Test coverage for 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. endpoints has also been increased to 100%.

    Deprecation warning: The /posts/types/<type>/taxonomies endpoint (and
    sub-endpoints with the same prefix) have been deprecated in favour of the new
    endpoints. These deprecated endpoints will now return a
    X-WP-DeprecatedFunction 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. indicating that the endpoint should not be
    used for new development, but will continue to work in the future.

    (props @kadamwhite, @rachelbaker, @rmccue, #198, #211)

  • Allow customizing 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. resources prefix

    The API base (typically wp-json/) can now be customized to a different
    prefix using the json_url_prefix 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.. Note that rewrites will need to be
    flushed manually after changing this.

    (props @ericandrewlewis, @rmccue, #104, #244, #278)

  • Give null as date for draft posts.

    Draft posts would previously return “0000-00-00 00:00:00” or
    “1970-01-01T00:00:00”, as draft posts are not assigned a publish date. The API
    now returns null where a date is not available.

    Compatibility warning: Clients should be prepared to accept null as a
    value for date/time fields, and treat it as if no value is set.

    (props @rmccue, #229, #230)

  • Fix errors with excerptExcerpt An excerpt is the description of the blog post or page that will by default show on the blog archive page, in search results (SERPs), and on social media. With an SEO plugin, the excerpt may also be in that plugin’s metabox..

    Posts without excerpts could previously return nonsense strings, excerpts from
    other posts, or cause internal PHPPHP The web scripting language in which WordPress is primarily architected. WordPress requires PHP 7.4 or higher errors. Posts without excerpts will now
    always return an excerpt, typically automatically generated from the post
    content.

    The excerpt_raw field was added to the edit context on posts. This field
    contains the raw excerpt data saved for the post, including empty
    string values.

    (props @rmccue, #222, #226)

  • Only expose email for edit context.

    User email addresses are now only exposed for context=edit, which requires
    the edit_users permission (not required for the current user).

    The email address field will now return false instead of a string if the
    field is not exposed.

    (props @pkevan, @rmccue, #290, #296)

  • Correct password-protected post handling.

    Password-protected posts could previously be exposed to all users, however
    could also have broken behaviour with excerpts. Password-protected posts are
    now hidden to unauthenticated users, while content and excerpts are shown
    correctly for the edit context.

    (Note that hiding password-protected posts is intended to be a temporary
    measure, and will likely change in the future.)

    (props @rmccue, #286, #313)

  • Add documentation on authentication methods.

    Full documentation on authentication
    is now available. This documentation explains the difference between the
    various available authentication methods, and notes which should be used.

    (props @rmccue, #242)

  • Include new client JSJS JavaScript, a web scripting language typically executed in the browser. Often used for advanced user interfaces and behaviors. from github.io

    The WP-API JavascriptJavaScript JavaScript or JS is an object-oriented computer programming language commonly used to create interactive effects within web browsers. WordPress makes extensive use of JS for a better user experience. While PHP is executed on the server, JS executes within a user’s browser. https://www.javascript.com library is now loaded dynamically from
    wp-api.github.io to ensure it is always up-to-date.

    (props @tlovett1, #179, #240)

  • Don’t allow setting the modification date on post creation/update.

    As it turns out, WP coreCore Core is the set of software required to run WordPress. The Core Development Team builds WordPress. doesn’t allow us to set this, so this was previously
    a no-op anyway. Discovered during test coverage phase.

    (props @rachelbaker, @rmccue, #285, #288)

  • Check post parent correctly on insertion.

    Posts could previously be added with an invalidinvalid A resolution on the bug tracker (and generally common in software development, sometimes also notabug) that indicates the ticket is not a bug, is a support request, or is generally invalid. parent ID. These IDs are now
    checked to ensure the post exists.

    (props @rmccue, #228, #231)

  • Make sure the type is actually evaluated for json_prepare_${type} filter.

    This value was previously not interpolated correctly, due to the use of the
    single-quoted string type.

    (props @danielbachhuber, #266)

  • Return WP_Error instead of array of empty objects for a revisionsRevisions The WordPress revisions system stores a record of each saved draft or published update. The revision system allows you to see what changes were made in each revision by dragging a slider (or using the Next/Previous buttons). The display indicates what has changed in each revision.
    permissions error.

    Previously, when trying to access post revisions without correct permissions,
    a JSONJSON JSON, or JavaScript Object Notation, is a minimal, readable format for structuring data. It is used primarily to transmit data between a server and web application, as an alternative to XML. list of internal error objects would be returned. This has been
    corrected to return a standard API error instead.

    (props @rachelbaker, @tlovett1, #251, #276)

  • Flip user parameters check for insert/update.

    Previously, you could add a user without specifying username/password/email,
    but couldn’t update a user without those parameters. The logic has been
    inverted here instead.

    (props @rmccue, #221, #289)

  • Add revision endpoints tests

    (props @danielbachhuber, @rachelbaker, @rmccue, #275, #277, #284, #279)

  • Add post endpoint testing

    Now at >54% coverage for the whole class, and >80% for the main methods. This
    figure will continue to rise over the next few releases.

    (props @rachelbaker, @rmccue, #99)

  • Separate helper functions into global namespace.

    WP_JSON_Server::get_timezone(), WP_JSON_Server::get_date_with_gmt(),
    WP_JSON_Server::get_avatar_url() and `WP_JSON_Server::parse_date() have
    all been moved into the global namespace to decouple them from the server
    class.

    Deprecation warning: These methods have been deprecated. The new
    json_get_timezone(), json_get_date_with_gmt(), json_get_avatar_url() and
    json_parse_date() methods should now be used instead.

    (props @rmccue, #185, #298)

As always, we’ve got a full list of all the changes and a longer changelog. Here’s who contributed to this release:

$ git shortlog 1.0...1.1 --summary
     8  Daniel Bachhuber
    12  DrewAPicture
     3  Eric Lewis
     2  JDGrimes
     9  K.Adam White
    54  Rachel Baker
   128  Ryan McCue
     4  Taylor Lovett
     1  jeremyfelt
     1  pkevan

Version 1.2

We’ve already started work on 1.2, and as always, we’re looking for help!

With version 1.2 and onwards, we’ll be tackling a bunch of extra testing for our endpoints, with the aim of eventually reaching >90% coverage. As always, we’ll also be adding new features and fixing bugs.

We’re also working on improving the new documentation site, and expect to see the majority of documentation migrated over there. Thanks to Sarah Gooding for helping out on the documentation side.

Core Integration

In case you missed it, the API is now slated for integration in WordPress 4.1. WP Tavern has a great writeup on the details.

As always, we look forward to seeing you at the team o2 and on GitHub. Now’s also a great time to remind you that you can get support for the plugin on WP.org, or by tweeting at me. Thanks to everyone who made this release great, and thanks to everyone using 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.!

#json-api, #rest-api

Ryan McCue 4:45 am on May 25, 2014
Tags: json-api,   

JSON REST API: Version 1.0

I’m incredibly excited to announce the availability of version 1.0 of the JSON REST API.

This version is a huge release and introduces a bunch of new features, such as user, revision and post 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. It also introduces our long-term backwards compatibility policy, aligning with WordPress coreCore Core is the set of software required to run WordPress. The Core Development Team builds WordPress. backwards compatibility.

Here’s a selection of the new stuff:

  • Add user endpoints.

    Creating, reading, updating and deleting users and their data is now possible
    by using the /users endpoints. /users/me can be used to determine the
    current user, and returns a 401 status for non-logged in users.

    Note that the format of post authors has changed, as it is now an embedded
    User entity. This should not break backwards compatibility.

    Custom post types gain this ability automatically.

    (props @tobych, @rmccue, #20, #146)

  • Add post meta endpoints.

    Creating, reading, updating and deleting post meta is now possible by using
    the /posts/<id>/meta endpoints. Post meta is now correctly embedded into
    Post entities.

    Meta can be updated via the Post entity (e.g. PUT to /posts/<id>) or via
    the entity itself at /posts/<id>/meta/<mid>. Meta deletion must be done via
    a DELETE request to the latter.

    Only non-protected and non-serialized meta can be accessed or manipulated 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.. This is not predicted to change in the future; clients wishing to
    access this data should consider alternative approaches.

    Custom post types do not currently gain this ability automatically.

    (props @attitude, @alisspers, @rachelbaker, @rmccue, @tlovett1, @tobych,
    @zedejose, #68, #168, #189, #207)

  • Add endpoint for deleting a single comment.

    Clients can now send a DELETE request to comment routes to delete
    the comment.

    Custom post types supporting comments will gain this ability automatically.

    (props @tlovett1, @rmccue, #178, #191)

  • Add endpoint for post revisionsRevisions The WordPress revisions system stores a record of each saved draft or published update. The revision system allows you to see what changes were made in each revision by dragging a slider (or using the Next/Previous buttons). The display indicates what has changed in each revision..

    Post revisions are now available at /posts/<id>/revisions, and are linked in
    the meta.links.version-history key of post entities.

    Custom post types supporting revisions will gain this ability automatically.

    (props @tlovett1, #193)

  • Respond to requests without depending on pretty permalink settings.

    For sites without pretty permalinks enabled, the API is now available from
    ?json_route=/. Clients should check for this via the autodiscovery methods
    (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. or RSD).

    (props @rmccue, #69, #138)

  • Add register post type argument.

    Post types can now indicate their availability via the API using the
    show_in_json argument passed to register_post_type. This value defaults to
    the publicly_queryable argument (which itself defaults to the
    public argument).

    (props @iandunn, @rmccue, #145)

  • Remove basic authentication handler.

    This breaks backwards compatibility for clients using Basic
    authentication. Clients are encouraged to switch to using OAuth
    authentication    . The Basic Authentication plugin can be
    installed for backwards compatibility and local development, however should
    not be used in production.

    (props @rmccue, #37, #152)

  • Require nonces for cookie-based authentication.

    This breaks backwards compatibility and requires any clients using cookie
    authentication to also send a nonce with the request. The built-in JavascriptJavaScript JavaScript or JS is an object-oriented computer programming language commonly used to create interactive effects within web browsers. WordPress makes extensive use of JS for a better user experience. While PHP is executed on the server, JS executes within a user’s browser. https://www.javascript.com
    API automatically handles this.

    (props @rmccue, #177, #180)

  • Clean up deprecated methods/functions.

    Functions and methods previously deprecated in 0.8/0.9 have now been removed.
    Future deprecations will take place in the same manner as WordPress core.

    This breaks backwards compatibility, however these were marked as
    deprecated in previous releases.

    (props @rmccue, #187)

  • Only expose meta on ‘edit’ context as a temporary workaround.

    Privacy concerns around exposing meta to all users necessitate this change.

    This breaks backwards compatibility as post meta data is no longer
    available to all users. Clients wishing to access this data should
    authenticate and use the edit context.

    (props @iandunn, @rmccue, #135)

  • Add json_ensure_response function to ensure either a
    WP_JSON_ResponseInterface or a WP_Error object is returned.

    When extending the API, the json_ensure_response function can be used to
    ensure that any raw data returned is wrapped with a WP_JSON_Response object.
    This allows using get_status/get_data easily, however WP_Error must
    still be checked via is_wp_error.

    (props @rmccue, #151, #154)

  • Use version option to check on init if rewrite rules should be flushed.

    Rewrite rules on 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 are now flushed via an init hook, rather than
    switching to each site on activation.

    (props @rachelbaker, #149)

As always, you can view all commits or the longer changelog.

For those interested, here’s the list of contributors to this release:

$ git shortlog --summary 0.9...
     1  Chris Marslender
     1  Eric Lanehart
     2  K.Adam White
     1  Kat Hagan
     2  Matth_eu
    41  Rachel Baker
   139  Ryan McCue
     5  Taylor Lovett
    10  Toby Champion

There’s a few really important things to note with this release.

Authentication Changes

Authentication has changed significantly in 1.0. If you’ve been using Basic authentication previously, you’ll now need to install the Basic authentication plugin. This 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. is designed for local development, as Basic authentication requires sending your plaintext credentials over the wire, which is unsafe for production.

Production users have two choices: built-in cookie authentication, or OAuth authentication. OAuth 1.0a is an authorization protocol that allows you to authorize clients to act on your behalf, and does not require giving your username and password to the client. It does, however, require a significantly more complicated authentication/authorization process, and clients are required to register on the site beforehand. We’re working on long-term solutions to this.

Plugins and themes can also use built-in cookie authentication. This is the normal WordPress login process, however requires a nonce for authentication to the site. This is automatically handled for you when using the built-in Javascript client.

Backwards Compatibility

From this release forwards, backwards compatibility will not be broken. This includes both the internal PHPPHP The web scripting language in which WordPress is primarily architected. WordPress requires PHP 7.4 or higher API, as well as 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/ we expose. New endpoints may be added, as well as new data, but responses will continue to be supersets of the current response.

The exception to this is for security concerns. As we continue development, we may need to change some endpoints for security issues, as we did with post meta for this cycle. These will be announced well before release where possible.

Please note also that this release has removed some previously deprecated methods and changed some internal implementation details. This only affects plugins or themes that extend the API.

Core Integration

We’re pushing hard for integration into 4.0 this cycle, and we need your help. Our core integration plan outlines the motivation behind the project and the specific plan for integrating it into core. We’re currently working on a comparison document for the API compared to the WP.com/Jetpack API and others, and will be publishing that soon.

We need your help to make it into 4.0. Developers, we’d love to know what you’ve built with the API, whether public or internal (even vague details help!), and we’d especially love to see things built with the API. We’re currently in danger of not making it in this cycle, so anything you can do to help us here would be fantastic.

As always, we’re also looking for help. The main API always needs help, and the other related projects do too. Both the WP-CLI client and Javascript client need help here.

You’re always welcome over at the team o2, and our next meeting will be at Tuesday, 00:00 UTC; we’d love to see you there. If not, see you soon for version 1.1!

#json-api, #rest-api

Ryan McCue 7:08 am on April 14, 2014
Tags: json-api,   

JSON REST API: Meeting Time Change

As announced on the team o2, the meeting time for 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 is changing to Tuesday, 0:00 UTC, in #wordpress-dev.

This week we’re discussing OAuth (which, P.S., is now available for testing), 1.0 and custom post typeCustom Post Type WordPress can hold and display many different types of content. A single item of such a content is generally called a post, although post is also a specific post type. Custom Post Types gives your site the ability to have templated posts, to simplify the concept. data privacy.

Hopefully I’ll see you there!

#json-api, #rest-api

Ryan McCue 6:49 am on April 6, 2014
Tags: json-api,   

JSON REST API: Version 0.9

Hi everyone! I’m happy to announce that version 0.9 of the JSONJSON JSON, or JavaScript Object Notation, is a minimal, readable format for structuring data. It is used primarily to transmit data between a server and web application, as an alternative to XML. 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/ is finally available.

Apologies for the extremely long delay here. I would have liked to ship OAuth authentication with 0.9, and the release was delayed due to that. However, it’s still not in a shippable state, and we’re well overdue for a release.

Important note: There are backwards compatibility breaks and deprecations in this release. These are all listed before, but exercise caution in upgrading. Backwards compatibility will be maintained from 1.0 onwards only.

Here’s the big changes:

  • Move from wp-json.php/ to wp-json/

    This breaks backwards compatibility and requires any clients to now use wp-json/, or preferably the new RSD/Link headers.

    (props @rmccue, @matrixik, #46, #96, #106)

  • Move 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. registration out of CPT constructor. CPT subclasses now require you to call $myobject->register_filters(), in order to move global state out of the constructor.

    This breaks backwards compatibility and requires any subclassing to now call $myobject->register_filters()

    (props @rmccue, @thenbrent, #42, #126)

  • Introduce Response/ResponseInterface

    Endpoints that need to set headers or response codes should now return a WP_JSON_Response rather than using the server methods. WP_JSON_ResponseInterface may also be used for more flexible use of the response methods.

    Deprecation warning: Calling WP_JSON_Server::header, WP_JSON_Server::link_header and WP_JSON_Server::query_navigation_headers is now deprecated. This will be removed in 1.0.

    (props @rmccue, #33)

  • Change all semiCamelCase names to underscore_case.

    Deprecation warning: Any calls to semiCamelCase methods require any subclassing to update method references. This will be removed in 1.0.

    (props @osiux, #36, #82)

  • Add 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 compatibility. If 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. is networknetwork (versus site, blog) activated, the plugin is now activated once-per-site, so wp-json/ is always site-local.

    (props @rachelbaker, #48, #49)

  • Add RSD and Link headers for discovery

    (props @rmccue, #40)

  • WP_JSON_Posts->prepare_author() now verifies the $user object is set.

    (props @rachelbaker, #51, #54)

  • Added unit testing framework. Currently only a smaller number of tests, but we plan to increase this significantly as soon as possible.

    (props @tierra, @osiux, #65, #76, #84)

As always, you can view all changes on GitHub as well as view all closed tickets.

For those interested, here’s the list of contributors to this release:

$ git shortlog 0.8... --summary
     1  Aaron Jorbin
     1  Anders Lisspers
     6  Bryan Petty
     1  Dobrosław Żybort
     7  Eduardo Reveles
     1  K.Adam White
    10  Rachel Baker
    41  Ryan McCue
     2  Taylor Lovett

I’m still desperately seeking feedback on our OAuth implementation. This is a hugely important part of 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 we need to get this nailed down as soon as possible.

General comments and posts are always welcome on our team o2.

#json-api, #rest-api

Ryan McCue 7:00 am on December 2, 2013
Tags: json-api,   

JSON REST API: Version 0.7

Apologies for the delay on this one, but it’s here now: version 0.7 of the JSONJSON JSON, or JavaScript Object Notation, is a minimal, readable format for structuring data. It is used primarily to transmit data between a server and web application, as an alternative to XML. 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/! Go download it now. This is mainly a bugfix release to catch up on all the unreleased items:

  • The response handler object is now passed into the endpoint objects via the constructor, allowing you to avoid excess global state where possible. It’s recommended to use this where possible rather than the global object.

    (props @rmccue, #2)

  • Fix undefined variables and indices
    (props @pippinsplugins, #5)
  • Correct call to deactivation hook
    (props @ericpedia, #9)
  • Check metadata access correctly rather than always hiding for users without
    the edit_post_meta capabilitycapability A capability is permission to perform one or more types of task. Checking if a user has a capability is performed by the current_user_can function. Each user of a WordPress site might have some permissions but not others, depending on their role. For example, users who have the Author role usually have permission to edit their own posts (the “edit_posts” capability), but not permission to edit other users’ posts (the “edit_others_posts” capability).
    (props @kokarn, #10)
  • Return all term metadata, rather than just the last one
    (props @afurculita, #13)
  • Access post metadata from cache where possible – Note, this is a backwards compatibility break, as the format of the metadata has changed. This may change again in the near future, so don’t rely on it until 1.0.
    (props @afurculita, #14)
  • Add term_link to prepare_term
    (props @afurculita, #15)
  • Fix hardcoded /pages references in WP_JSON_CustomPostType
    (props @thenbrent, #26)
  • Sanitize headers for newlines
    (props @kokarn, #7)
  • Register rewrite rules during 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. activation
    (props @pippinsplugins, #17)

(As you can see, we had 6 separate contributors to this release, with 3 team members also reviewing and merging code. Thanks to everyone who was involved with this release!)

We’ve also got some future plans, which I’d like to share with you guys now if you haven’t seen them previously (you’re always welcome over at the team o2). This slightly delayed release is a catch-up release, and we’re planning on hitting 0.8 this week, then 0.9 on December 11th and 1.0 on December 18th. We’ll then be taking a short break over Christmas, and letting the code settle for a bit.

The 1.0 release will freeze our (internal PHPPHP The web scripting language in which WordPress is primarily architected. WordPress requires PHP 7.4 or higher and external JSON) coreCore Core is the set of software required to run WordPress. The Core Development Team builds WordPress. 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., with any future changes to be completely backwards compatible. This should coincide with the 3.9-early stage, and we’ll be able to get underway on core integration discussions with this backwards compatibility policy.

The big feature we’re working on now is authentication. After much discussion, we’ve decided that OAuth 1.0a is really the only way to go here. While Basic authentication is nice and simple, it doesn’t give us any sort of CSRF protection, which is a blockerblocker A bug which is so severe that it blocks a release.. Luckily for us, WooCommerce has recently added a JSON REST API (based on this project; giant props to Max Rice for his effort and feedback here) and implemented OAuth, so I’m working on porting this back upstream. This should hopefully land in 0.8 (this week) or 0.9 (next week).

As always, if you want to get involved, head on over to our team o2. Now that we’re established, comments have been opened to all, and you’re welcome to suggest new topics via the form too!

#json-api, #rest-api