WordPress.org

Make WordPress Core

Tagged: json-api Toggle Comment Threads | Keyboard Shortcuts

  • Ryan McCue 4:05 am on October 8, 2016 Permalink |
    Tags: , json-api, merge-proposals,   

    REST API Merge Proposal, Part 2: Content API 

    Hi everyone, it’s your friendly REST API team here with our second merge proposal for WordPress core. (WordPress 4.4 included the REST API Infrastructure, if you’d like to check out our previous merge proposal.) Even if you’re familiar with the REST API right now, we’ve made some changes to how the project is organised, so it’s worth reading everything here.

    (If you haven’t done so already, now would be a great time to install the REST API and OAuth plugins from WordPress.org.)

    A brief history of the REST API

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

    This infrastructure is the core of the REST API, and provides the external interface to send and receive RESTful HTTP requests. Since shipping in 4.4, the infrastructure is now used by WordPress Core for oEmbed responses, and by plugins like WooCommerce and Jetpack, enabling anyone to create their own REST API endpoints.

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

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

    Proposals for Merge

    Content Endpoints

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

    • Content:
      • Posts: Read and write access to all post data, for all types of post-based data, including pages and media.
      • Comments: Read and write access to all comment data. This includes pingbacks and trackbacks.
      • Terms: Read and write access to all term data.
      • Users: Read and write access to all user data. This includes public access to some data for post authors.
      • Meta: Read and write access to metadata for posts, comments, terms, and users, on an opt-in basis from plugins.
    • Management:
      • Settings: Read and write access to settings, on an opt-in basis from plugins and core. This enables API management of key site content values that are technically stored in options, such as site title and byline.

    This merge proposal represents a complete and functional Content API, providing the necessary endpoints for mobile apps and frontends, and lays the groundwork for future releases focused on providing a Management API interface for full site administration.

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

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

    This Content API is targeted at a few primary use cases, including enhancing themes with interactivity, creating powerful plugin interfaces, building mobile and desktop applications, and providing alternative authoring experiences. We’ve been working on first-party examples of these, including a mobile app using React Native and a liveblogging web app, as well as getting feedback from others, including WIRED, the New York Times, and The Times of London. Based on experience building on the API, we’ve polished the endpoints and expanded to support settings endpoints, which are included as the first part of the Management API.

    Authentication

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

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

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

    We’ve chosen OAuth 1 over the newer OAuth 2 protocol because OAuth 1 includes a complex system for request signing to ensure credentials remain secure even over unsecured HTTP, while OAuth 2 requires HTTPS with a modern version of TLS. While it is strongly encouraged for sites to use HTTPS whenever possible (Let’s Encrypt makes it easier than ever to do so), WordPress itself does not require HTTPS and we do not believe WordPress should make HTTPS a requirement for using the API. The additional complexity that OAuth 1 adds can be easily supported by a library, and many such libraries already exist in most programming languages. OAuth 1 remains supported around the web, including for the Twitter API, and we also provide extensive documentation on using it.

    Authentication Beyond 4.7

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

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

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

    After Merge

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

    During the remaining parts of this release cycle and through into the 4.8 cycle, additional work will go into other parts of the API. This includes further work and refinement on the broker authentication system, including work on WordPress.org infrastructure. Additionally, we plan to continue working on the Management API endpoints, including theme and appearance endpoints to support the Customiser team. Both of these components will be maintained as separate feature projects on GitHub until they’re ready for merge into core.

    The team remains committed to supporting the API in core, and the Content API will switch from GitHub to Trac for project management and contributions. This same process occurred for the API Infrastructure in WordPress 4.4.

    Reviews and Feedback

    With this merge proposal, we’re looking for feedback and review of the project. In particular, we’re focussing on feedback on the security of the API and OAuth projects, and are also reaching out to specific people for reviews. (We take the security of the API seriously, and bug reports are welcomed on HackerOne at any time.) Design and accessibility reviews for the OAuth authorisation UI are also welcomed to ensure we maintain the high standards of WordPress core.

    Both the REST API plugin and the OAuth plugin are available on WordPress.org, and issues can be reported to the GitHub tracker for the API and the OAuth plugin respectively. We have released a final beta (Beta 15 “International Drainage Commission”) which includes the meta and settings endpoints.

    With Love from Us

    As always, this is a merge proposal, and is not final until 4.7 is released. We’re eager to hear your thoughts and feedback; the comments below are a perfect place for that, or you can pop along to one of our regular meetings. We’re also always available in the #core-restapi room on Slack.

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

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

    With love, The REST API Team

     
    • George Stephanis 12:17 pm on October 8, 2016 Permalink | Log in to Reply

      Regarding Authentication, as nice as OAuth 1.0a may be in some respects, I feel that we’re missing some rather obvious problems here.

      We’re expressing such concern about securing the REST API endpoints to work on HTTP — that we’re missing the fact that for sites that don’t support HTTP, normal wp-login requests or cookies could just as easily be sniffed.

      It just feels to me like we’re spending a lot of time reinforcing the back door against attackers, when the front door isn’t even locked.

      The concept of a third-party broker feels very antithetical to WordPress Core. To have to ping the third-party server for every login to check for invalidations of their applications, let alone the initial confirmation of an application … for me, it doesn’t pass the gut check.

      I’d much rather see something akin to the Application Password system we’ve devised. It has unique per-application passwords, with 142 bits of entropy, usage logging (date and ip last used), and trivial invalidation, as well as a proposed simple flow for applications to request passwords and get the generated passwords passed back.. And, as an added bonus, it works with the legacy XML-RPC API.

      Compared to that, making someone hoping to do something for API access to a single site register for a cloud broker, and then reauth with the individual site .. the UX doesn’t pass muster for me. :\

      Authentication is probably the most important key to getting the REST API correct, and it’s necessary (imho) to ship. We need to get it right.

      • marsjaninzmarsa 7:25 am on October 9, 2016 Permalink | Log in to Reply

        To have to ping the third-party server for every login to check for invalidations of their applications, let alone the initial confirmation of an application … for me, it doesn’t pass the gut check.

        Nope, you’re missing the point, third party will be pinged only on first use of new app on particular site, and next every few hours or so for invalidation (same as with checking for security updates).

      • Dion Hulse 10:40 am on October 9, 2016 Permalink | Log in to Reply

        Core. To have to ping the third-party server for every login to check for invalidations of their applications, let alone the initial confirmation of an application … for me, it doesn’t pass the gut check.

        I tend to agree here.

        I’d much rather see something akin to the Application Password system we’ve devised

        However, I feel that Application Passwords are actually a far worse solution to the problem than the various oAuth options out there, to the point that I think Application Passwords are an anti-pattern which core should never directly support. The user experience of Application Passwords are not user friendly at all, they’re a hacky solution to avoid using a proper modern application authentication mechanism.

        I could ramble for quite some time on the UX of these, but at the end of the day moving towards oAuth is going to provide a far better developer and user experience for API clients.
        Unfortunately though with all options here there’s the downside that Applications need to be registered/known/considered safe and also be able to invalidate their credentials in the event the applications key store is leaked (For example, Plugin X which relies upon a service has it’s keystore hacked, the application would have no way of informing those sites to distrust it’s previous authenticated sessions).

        In an ideal world, a central provider wouldn’t be needed, but we don’t have a decentralised platform for WordPress yet, so there’s no other mechanism for WordPresses out there to be told the sort of information they need to know.

      • Ryan McCue 8:40 pm on October 9, 2016 Permalink | Log in to Reply

        At its core, OAuth is just a standardised system for issuing app tokens. The primary things that it builds on top of this are specifically for security over HTTP, so I would be extremely reluctant to move backwards from those to a more simple token-based system.

        Regular WordPress logins are protected by two main factors: nonces and session tokens. While it is possible to sniff a raw username/password over the initial login, subsequent requests are protected, which means automated attacks are much harder. The nature of an external API means neither WP nonces nor session tokens (which are both intentionally server-only secrets) can be used to protect authentication, so we need a replacement system.

        OAuth incorporates a combination of nonce and timestamp to replace these in a similar manner, which are then combined with the secret, which we need since it’s no longer server-only. (WP nonces and session tokens have an internal secret with NONCE_SALT, the only difference is that we share them with the client for OAuth.)

        The broker system exists specifically because dynamic registration (either with OAuth or your plugin) has a number of key problems, primarily that it makes revocation useless. If the app is revoked, it can simply register again, which subverts both the site admin and W.org team if it were intentionally revoked. We looked at dynamic registration and rejected it specifically because of the issues with it.

        While the system might seem conceptually complex, it’s pretty simple to actually implement, because the broker is just regular OAuth under the hood. The entirety of the flow can be written in 200 lines of JavaScript. From the app’s perspective, it primarily Just Works, with most of the complexity hidden inside the broker implementation instead.

        The OAuth 1.0a specification is rigorously tested by security researchers and in production on huge web apps. The broker system builds on top of this, but avoids reimplementing the wheel, and instead just uses OAuth for some of the heavy lifting. Application Passwords is at its core HTTP Basic Authentication, which in its own specification 17 years ago recommended against actually using it.

        OAuth 1 isn’t perfect, but every thing in it is there for a reason. Is it perfect? No. But it provides a lot of benefit over Basic Auth for a relatively low cost.

    • Jon Brown 1:09 pm on October 8, 2016 Permalink | Log in to Reply

      Much love back at you all. This looks fabulously well thought out and complete.

    • Josh Pollock 2:42 pm on October 8, 2016 Permalink | Log in to Reply

      5 Stars!

    • fgilio 3:09 pm on October 8, 2016 Permalink | Log in to Reply

      Thanks to all of you!

    • Ahmad Awais 4:07 pm on October 8, 2016 Permalink | Log in to Reply

      I’m all in. Let’s do it this time. BTW great read Ryan.

    • Omaar Osmaan 5:55 pm on October 8, 2016 Permalink | Log in to Reply

      Thanks so much for all the hard work from the team- eager to see it get merged on core!

    • Noel Tock 7:56 pm on October 8, 2016 Permalink | Log in to Reply

      :+1:

    • Sergio Santos 1:45 pm on October 9, 2016 Permalink | Log in to Reply

      Thanks to all the team behind this outstanding work!

    • Matthew Eppelsheimer 9:43 pm on October 9, 2016 Permalink | Log in to Reply

      Thumbs up!

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

      Additionally, we plan to continue working on the Management API endpoints, including theme and appearance endpoints to support the Customiser team. Both of these components will be maintained as separate feature projects on GitHub until they’re ready for merge into core.

      I’d like to note that customizer changesets (#30937, formerly “transactions”) allows for REST API responses to have customizations applied when the request includes a customize_changeset_uuid query param which identifies a customize_changeset post. This allows the customizer to be used with headless sites and mobile apps.

      A feature plugin needs to be started shortly that allows for these changeset posts to be CRUD’ed via the REST API as well, allowing for new customizer administrative applications to be built on top of the REST API without any need to go to customize.php.

    • Tammie Lister 8:08 pm on October 10, 2016 Permalink | Log in to Reply

      As requested in the design Slack channel, here is a design review. I took the OAuth plugin for a spin today and only focused on the design elements.

      I first of all had discoverability issues, but that was mainly due to not using this. I sort of imagine if someone is going to use this they will be doing so knowing more than I did – so that’s ok.

      The first screen is minimal but as expected when empty. It seemed to all fit the existing WP patterns. Thanks for taking the time and doing that. Should there be select all boxes though – I don’t see any actions for all.

      On the ‘add’ screen, I tried adding nothing in the fields. I was surprised when got a green message. I would expect this should be red over the success green.

      https://cldup.com/JMW8wRzxx4.png

      The term ‘Add Application’ but then the action button being ‘Save Consumer’, this threw me. Perhaps this is my lack of knowledge over terminology, but shouldn’t they both be the same?

      The page gets cluttered fast, I sort of want a break here visually, just a simple line would do:

      https://cldup.com/3BZcACH2u9.png

      Regenerating the secret success message I felt should be by the secret. It was odd as the message appeared above my eye view. I click to regenerate lower and then this message pops up the top, feels like it should be close to add context.

      https://cldup.com/BF3C3iuVeF.png

      This may be a bug but when I searched for applications it tried to search users and I got the following:

      https://cldup.com/UjY8mgctGd.gif

    • Matt Mullenweg 8:26 pm on October 10, 2016 Permalink | Log in to Reply

      1. Given the hurdles of authentication I don’t think that bringing this into core provides benefits for WP beyond what the community gets from the plugin. I don’t believe in its current state the benefit outweighs the cost, and we should err on the side of simplicity.

      2. I am not interested in hosting the centralized brokered authentication server on WordPress.org in the 4.8 timeframe, and hesitant about the implications it has for WP more broadly. I do appreciate the thought that has been put into solving this tricky problem.

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

        @matt, thanks for the comment. Can you clarify whether with (1) you mean the authentication solution, or the merge proposal for the content endpoints more broadly? There was discussion today in slack where we weren’t sure which way to interpret this point.

    • Dominik Schilling (ocean90) 10:01 pm on October 10, 2016 Permalink | Log in to Reply

      I gave the OAuth 1 plugin a try and here’s some feedback:

      • https://github.com/WP-API/OAuth1/issues/161 makes me wonder how we can integrate something with may not work on “a lot of sites”.
      • Adding Applications as a sub menu of Users doesn’t feel right to me. I just can’t imagine that 80% of our users really need this there. Twitter and Facebook have it both in the settings.
      • The UI: https://cloudup.com/c1emHXcHP4g Reusing existing elements is fine, but that looks a bit to simple and not fully developed. I’m sure that this can made better and doesn’t require a table. See Twitter/Facebook.
      • The plugin is using closures so it’s not compatible with the minimum requirements of WordPress.
      • I got a “500 Internal Server Error” error when the callback URL was invalid.
      • A few DocBlocks don’t follow the documentation standards.

      For some reasons I can’t get a successful `oauth1/access` request, I’ll try this again tomorrow…

    • Aaron D. Campbell 7:30 pm on October 11, 2016 Permalink | Log in to Reply

      The API endpoints themselves seem to be in a really good place, but I’m not sure the oAuth plugin is. Would it be reasonable to separate these into different proposals?

    • Mark Howells-Mead 2:32 pm on October 12, 2016 Permalink | Log in to Reply

      Issues aside, I’m strongly in favour of the REST API becoming a core feature as soon as it is stable.

    • Chris Smith 3:13 pm on October 12, 2016 Permalink | Log in to Reply

      +1 here as well and thanks to the team for their hard and thoughtful work.

      Based on the comments here, it does seem like it would make sense to split the proposal into the Content API and oAuth pieces for 4.7 so they can be dealt with/commented on independently as needed.

      @kadamwhite, what were the team’s thoughts on that in yesterday’s discussion?

    • Nilambar Sharma 5:32 pm on October 12, 2016 Permalink | Log in to Reply

      Really waiting for this. Lets make WordPress more awesome. It would be a great step merging new endpoints to core.

    • brad989 5:33 pm on October 12, 2016 Permalink | Log in to Reply

      Been looking forward to this for a long time. The content endpoints are an essential addition to WordPress core.

    • Chuck Reynolds 6:52 am on October 14, 2016 Permalink | Log in to Reply

      full api integration into core needs to happen eventually… API endpoints are at/near a good place. re: oath tho… meh..
      needs full support of CPT’s, which theoretically it would but… lots to test there.

    • forbze 7:16 am on October 14, 2016 Permalink | Log in to Reply

      I really want this! I’ve had to use hacky solutions in the past to repurpose content for mobile apps (I didn’t want to use web views / Mobile ui plugins).

      WordPress’s admin interface would make it really simple for me to give clients content control for their app content – rather than me having to build a custom editor UI on top of Parse / Firebase.

      I think oauth is the right solution for auth.

    • pwaring 9:23 am on October 14, 2016 Permalink | Log in to Reply

      I’m only in favour of this if the API can be disabled (ideally by default). I don’t need or want this functionality and it sounds like another remote attack vector.

      “we do not believe WordPress should make HTTPS a requirement for using the API”

      I *strongly* disagree with this. TLS uptake is increasing all the time and some browsers (e.g. Chrome) are starting to show stronger warnings for plain HTTP. Plus, if a popular application like WordPress requires HTTPS for its API, that will act as a significant nudge to hosting providers to provide HTTPS by default (a bit like moving from PHP 4 to 5).

      • Ryan McCue 9:18 pm on October 14, 2016 Permalink | Log in to Reply

        It’s super easy to disable the REST API via the `rest_enabled` filter (just return false), and there’s already a plugin for it. 🙂

        • pwaring 8:10 am on October 15, 2016 Permalink | Log in to Reply

          Whilst I’m capable of changing the code to add a filter, I don’t think that counts as ‘super easy’. It really should be a tick box somewhere in the admin settings.

          Installing a plugin to disable optional behaviour in core also seems unnecessarily complicated, plus it introduces another dependency and there’s no guarantee that the plugin author will keep it up to date.

          • Dave McHale 1:59 pm on October 18, 2016 Permalink | Log in to Reply

            I understand your concern, pwaring, but we already don’t have the ability to disable XML-RPC in core (ever since they enabled it by default in 3.5) – and since the REST API is “the same but different” I believe that’s why the new feature is following the same model. “Decisions, not options” and all that 🙂

            It’s also why I’m the author of the plugin Ryan linked to above. I think the REST API is great, and can’t wait to start using it myself *and* also see what other people build with it. But it’s not going to be for everyone, and I thought that people may want the easy ability to turn it off if they had a reason to.

            Since the plugin uses the root-level filters provided by the REST API there should very, VERY little need for actual plugin updates moving forward into the future (though I do keep an eye on the project, in case an update is needed). The only time I’ve needed to make a real functional change was when the filters themselves changed from version 1.x to 2.x of the API, before it was even merged into core. New features like the content endpoints won’t change the use of the plugin, because the REST API is still entirely disabled if you’re using the filters.

  • Joe Hoyle 5:33 pm on October 1, 2016 Permalink |
    Tags: , json-api,   

    WordPress REST API – 2.0 Beta 14 

    Hey folks! I’m excited to announce the release of Beta 14 of the REST API. It’s been a while since our last release, beta 14 is jam packed with general improvements, bug fixes and general refinement to polish the feature plugin before core merge.

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

    • Add support for password protected posts. There is now a protected attribute in the content and excerpt fields in post response. To view password protected posts via the API, use the password query parameter to provide the post’s password.
    • Allow returning an error from field update callbacks.
      Simply have your update_callback return a WP_Error.
    • Add relevance orderby to posts endpoint
    • Ability to order by slug, email and url on the users endpoints.
    • Add sticky parameter to the posts endpoint.
    • Update the wp-api.js client from the client-js repo.
    • Many many more

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

    We’ll be kicking Beta 15 which will be focused on meta support for posts, terms, comments and users as well as a brand new settings endpoint. These are currently in review awaiting feedback, check out the meta pull request and the settings pull request and let us know what you think.

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

     
  • Ryan McCue 4:39 am on April 4, 2016 Permalink
    Tags: json-api,   

    WP REST API: 2.0 Beta 13 & Roadmap 

    Hi folks! I’m here with another exciting update from the API team.

    Beta 13

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

    • BREAKING CHANGE: Fix Content-Disposition header parsing. This technically breaks backwards compatibility to correctly match the header specification. (#2239)

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

    • Updated JS client to the latest version. (#2403)

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

    Roadmap

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

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

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

    Moving forward, version 2.0 of the WP REST API will follow a normal project release cycle. We will have minor releases in the 2.x series as new features are added, and bugfix releases in the 2.0.x series.

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

    In addition to attracting more developers within our community, we are also looking to get more contributors involved with the project. As noted in previous discussions, the four of us on the API team can’t keep pace with WordPress itself without help. We’re looking to get WordPress core component maintainers involved in their relevant components, as well as new developers from outside the project. Moving forward, the API team sees our role as advisory over the API itself, with the API treated as an integral part of the component rather than maintained by a separate team. We’re also going to continue to work on our feature plugins (metadata, site/multisite, menus/widgets, and authentication) in parallel, and are looking for help on these as well. (There’s also more news regarding authentication coming very soon.)

    If you’d like to get involved with the API, please let us know. You can comment here, ping us on Slack in the #core-restapi room, or via GitHub issues. We’re looking at spending significant time onboarding new users, so if you’d like to get involved, now’s the time! Our weekly meeting is at Monday 23:00 UTC

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

    With love,

    Ryan, Rachel, Daniel, and Joe

     
    • adamf321 4:19 pm on April 4, 2016 Permalink | Log in to Reply

      Hey guys,
      Firstly thanks for all the great work you’ve been producing on the API! I’m the CTO of a digital agency and we’re working on a new infrastructure which relies heavily on it. I would like for us to be involved in some part in the ongoing development of the API – so please keep me up to date with the onboarding process and I will ask who in our team is interested. We have dev and design resources. To give you an early heads-up, this month is pretty hectic, but from next month I think we can make some time to get started.

      Cheers,
      Adam

    • Mike Nelson 4:40 pm on April 4, 2016 Permalink | Log in to Reply

      +1 to 2.0 stable. If we really really really want to make breaking changes in the future it can always be on a 3.0 version. For now it’s nice having something stable.

      And I’m at least interested in helping out with the basic auth plugin

    • nathangraham 10:25 pm on April 14, 2016 Permalink | Log in to Reply

      We rely heavily on the REST API as well so thanks for all of your work. I’m happy to contribute as well.

  • Daniel Bachhuber 4:50 pm on February 9, 2016 Permalink
    Tags: , json-api,   

    WP REST API: Version 2.0 Beta 12 

    Happy Tuesday 🙂 The WP REST API team is proud to bring you: 2.0 Beta 12 “Canyonero”. Download it from the plugin repository or from GitHub.

    Here are some highlightsbreaking changes from the changelog:

    • Removes meta endpoints from primary plugin. If your project depends on post meta endpoints, please install WP REST API Meta Endpoints. For the gory history of meta, read #1425 and linked issues. At this time, we recommend using register_rest_field() to expose meta (docs).
    • Returns original resource when deleting PTCU. Now that all resources require the force param, we don’t need to wrap delete responses with the trash state.
    • Uses roles rather than role in the Users controller. Building the REST API gives us the opportunity to standardize on roles, instead of having both roles and role.
    • Moves to consistent use of context throughout controllers. Contexts limit the data present in the response. Here’s how to think of them: embed correlates with sidebar representation, view represents the primary public view, and edit is the data expected for an editor.
    • Removes post_* query param support for GET /wp/v2/comments. The proper pattern is to use GET /wp/v2/posts to fetch the post IDs to limit the request to.
    • Introduces rest_validate_request_arg()/rest_sanitize_request_arg(). Dedicated functions means we can use them for validating / sanitizing query args too. Removes WP_REST_Controller::validate_schema_property() and WP_REST_Controller::sanitize_schema_property().

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

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

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

     
    • Joshua David Nelson 7:38 pm on February 9, 2016 Permalink | Log in to Reply

      I feel compelled to end debate of the chicken and egg. The answer is egg. The egg came first, from which a chicken would be born as a mutated version of the chicken’s previous ancestor. That’s how evolution works. Speaking of which, it’s great to be tracking the evolution of the REST API – thanks for the update and hard work!

  • Daniel Bachhuber 11:17 pm on February 3, 2016 Permalink
    Tags: , json-api,   

    Thar be a WP REST API meeting tomorrow 

    Curious as to when the WP REST API endpoints will land in WordPress core? Me too!

    We’re meeting to discuss the State of the REST API just under 24 hours from now in #core-restapi on Slack: Thursday, February 4 at 23:00 UTC

    The primary points of discussion are:

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

    See you there!

     
  • Daniel Bachhuber 12:00 am on January 26, 2016 Permalink
    Tags: , json-api,   

    WP REST API: Version 2.0 Beta 11 

    Just days before the first conference dedicated to the REST API, we bring you: 2.0 Beta 11 “Give me a white wine spritzer!”. Download it from the plugin repository or from GitHub.

    Here are some highlightsbreaking changes from the changelog:

    • Moves Post->Term relations to the Post Resource. Previously, a client would fetch a Post’s Tags with GET /wp/v2/posts/<id>/tags. In Beta 11, an array of term ids is included on the Post resource. The collection of terms for a Post can be fetched with GET /wp/v2/tags?post=<id>. The WP_REST_Posts_Terms_Controller class no longer exists.
    • Changes featured_image attribute on Posts to featured_media. While featuring other attachment types isn’t yet officially supported, this makes it easier for us to introduce the possibility in the future.
    • Uses discrete schema title for categories and tags. If you’ve used register_rest_field( 'term' ), you’ll need to change 'term' to 'tag' and/or 'category'.
    • Makes many filters dynamic based on the controller type. If you were using the rest_prepare_term filter, you’ll need to change it to rest_prepare_post_tag or rest_prepare_category. If you were using rest_post_query or rest_terms_query, you’ll need update your use to rest_page_query, etc. If you were using rest_post_trashable, rest_insert_post or rest_delete_post, they are now dynamic based on the post type slug.

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

     
  • Daniel Bachhuber 5:21 pm on January 11, 2016 Permalink
    Tags: , json-api,   

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

    For the first REST API release of 2016, we bring you: 2.0 Beta 10 “Chief Wiggum”. Because we’ve got security releases too, Ralphie.

    Security Releases

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

    All previous versions of the plugin are affected. All WP REST API users are strongly encouraged to update immediately. Many prior releases has been separately patched. If you’re still using WP-API v1.x, you can update to v1.2.5. If you’re on an older 2.0 Beta for whatever reason, we’ve tagged versions 2.0 Beta 3.1, 4.1, 5.1, 6.1, 7.1, 8.1, and 9.1.

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

    Version 2.0 Beta 10

    Here are some of the highlights of Beta 10:

    • Breaking changes:
      • Removes compatibility repo for WordPress 4.3. WordPress 4.4 is now the minimum supported version.
      • Changes link relation for types and taxonomies. In Beta 9, this link relation was introduced as item, which isn’t correct. The relation has been changed to https://api.w.org/items.
      • Introduces edit context for wp/v2/types and wp/v2/taxonomies. Some fields have moved into this context, which require edit_posts and manage_terms, respectively.
      • Removes post_format as a term _link for Posts. Post formats aren’t a custom taxonomy in the eyes of the REST API.
    • Consistently query for a specified set of items. Adds include param to /wp/v2/posts, /wp/v2/users, /wp/v2/<taxonomy> and /wp/v2/comments.
    • Tons of minor improvements and bug fixes. You should read the full changelog for all of them.

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

     
  • Daniel Bachhuber 7:00 pm on December 11, 2015 Permalink
    Tags: , json-api,   

    WP REST API: Version 2.0 Beta 9 

    For the last REST API release of 2015, we bring you: 2.0 Beta 9 “You Don’t Win Friends With Salad”. Download it from the plugin repository or from GitHub.

    Should I use 2.0 Beta 9 in production?

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

    As many of you may already know, the v1.x branch is essentially deprecated and only maintained for security and major compatibility issues. Even its latest release, v1.2.4, still includes some annoying bugs. The v2.0 Betas introduce aton of new features, functionality, and general improvements. But, there will never be a formal v2.0 plugin release — v2.0 will be endpoint inclusion into WordPress core.

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

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

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

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

    Changelog

    Here are some highlights:

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

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

     
  • Ryan McCue 9:52 am on December 7, 2015 Permalink
    Tags: , json-api,   

    WP REST API: New Tools & OAuth Updates 

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

    Discovery Library for PHP

    A super cool thing that you might not know about with the API is that it’s entirely discoverable. We use a relatively simple process modelled after Atom/RSS feed discovery. All you need to do is check a site’s headers for a Link header:

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

    This allows a tonne of possibilities, including renaming the API base, or even delegating API access to someone else. (For example, WordPress.com could use https://api.wordpress.com/{site_id}/ instead of per-site APIs.)

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

    To use it, add wp-api/discovery to your Composer requirements manually or run composer require wp-api/discovery in your project directory. You can then use the WordPress\Discovery\discover() function to discover the API for a given URL. (Oh hey, namespaces!)

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

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

    New OAuth Server

    One of the weakest points of developing with the API right now is getting authentication working. For a long time, our OAuth server plugin has languished and fallen behind as we push forward with the API. No longer is this the case!

    Simply update to the latest master. This will also be available on WordPress.org very soon.

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

    • Full admin UI, including application management and the ability to revoke tokens
    • Ability to delete applications or regenerate their secrets
    • Callback validation process overhaul, now supporting custom protocols
    • Overhauled internals

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

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

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

    Demo API Client

    (pause for breath)

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

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

    (Both the discovery library and the demo client are open source and MIT licensed, allowing you to use them in commercial projects should you so desire.)

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

     
    • jeffikus 10:41 am on December 7, 2015 Permalink | Log in to Reply

      This is awesome, the last piece I’ve been hoping would come out soon 🙂 Major kudos for this, quick question though, I see the demo API client is in PHP, any plans for a JS demo?

      • jeffikus 10:42 am on December 7, 2015 Permalink | Log in to Reply

        Oh gosh, I just re-read the last paragraph, ignore me 🙂 i’ll try get a JS version together and post it here 🙂

    • Justin Greer 1:37 pm on December 7, 2015 Permalink | Log in to Reply

      Super excited! I am looking forward to extensions like OpenID Connect and Discovery.

    • Ahmad Awais 2:19 pm on December 7, 2015 Permalink | Log in to Reply

      Awesome sauce! Shit, I wish I could take a holiday and read the source, oh wait, I can! Goes to read the source.

    • Collizo4sky 3:12 pm on December 7, 2015 Permalink | Log in to Reply

      Great job guys. Excited to see some PHP league package get some love in the WordPress community.
      Why reinvent the wheel when it isn’t broken 😀

      Keep up the good job Ryan.

    • Joseph Scott 3:17 pm on December 7, 2015 Permalink | Log in to Reply

      it’s entirely discoverable … including renaming the API base, or even delegating API access to someone else

      Historically this hasn’t worked out that well. I’d recommend shouting this super loud in every code example and article that deals with this API if you want to overcome the lazy momentum of clients assuming the URL will always be DOMAIN/wp-json/

      • Mike Nelson 5:52 pm on December 7, 2015 Permalink | Log in to Reply

        +1 to Joseph’s comment, especially if someone wants to run v1 of the API alongside v2, in which case they would need to have one of the APIs running on a different API base.

        And +1 to these advancements in general!

        • Ryan McCue 11:59 pm on December 7, 2015 Permalink | Log in to Reply

          Fingers crossed we’ll eventually have a 1.9 that has v1 endpoints on v2 infrastructure. 🙂

          • Mike Nelson 6:50 pm on December 8, 2015 Permalink | Log in to Reply

            huh ya that could be nice. I suppose it depends on how well folks start to adopt using v2. If lots of people stay on v1 then it might be nice

      • Ryan McCue 11:58 pm on December 7, 2015 Permalink | Log in to Reply

        > Historically this hasn’t worked out that well

        Agreed, though it has worked well for feed autodiscovery, so I’m optimistic. 🙂

  • Daniel Bachhuber 12:29 am on December 2, 2015 Permalink
    Tags: , json-api,   

    WP REST API: Version 2.0 Beta 8 

    Just in time for WordCamp US, we have a new REST API for you: 2.0 Beta 8 “Monorail!”. Download it from the plugin repository or from GitHub.

    Here’s the changelog:

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

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

     
c
compose new post
j
next post/next comment
k
previous post/previous comment
r
reply
e
edit
o
show/hide comments
t
go to top
l
go to login
h
show/hide help
shift + esc
cancel
Skip to toolbar