Ryan McCue 12:09 on March 30, 2015
Tags: core-restapi

WP-API Lovers, it’s been too long…

Hi everybody, remember us? After a long downtime between actual posts, we figured it was time to clue you in on what’s been happening in the wonderful world of the REST API. Here’s our recap of the goings on.

Version 1.2

The astute among you will have noticed we recently released version 1.2 of the API. If you’re not using it already, you’re missing out on Cross-Origin Resource Sharing (CORS) support, new actions and filters to support hijacking requests (for things like caching), and a tonne of bug fixes. Our thanks go out to all 29 (!!!) contributors to this release, and to Brian Krogsgard for our fantastic new plugin header.

It’s also with a little bit of sadness and a lot of excitement that we announce 1.2 will be the final major release for the 1.x branch. While version 1 has served us well, it’s time to move on to better things and prepare the project for core integration. Version 2 is well underway, and we’re hoping to have a beta out in the next month or so.

Version 1.9?

As @rachelbaker mentioned in the release post for 1.2, there’ll actually be another almost-release on the 1.x branch. From the start of the project, I’ve always pledged compatibility with whatever goes in to core. Our almost-release will be a final-final release on the v1 branch, with no new features or bug fixes, but instead removing the internals of the version 1 code and hooking them up to version 2.

This will allow existing code to work essentially forever into the future, using the version 1 interface around the version 2 implementation. Bug fixes on version 2 should then also be carried down to the version 1 code.

I’ve taken to calling this shim Version 1.9, although it may not end up as that in the end. Whatever the case, this won’t be counted as a full version 1 release, as it will only be a wrapper around version 2. We do, however, plan to have full backwards compatibility as with every other release.

Version 2

Version 2 is under pretty heavy development right now. For those not familiar, this is the non-backwards-compatible edition of the API intended specifically for core integration. Version 2 is unlikely to ever have a full standalone release, however we’re planning on releasing betas on the lead up to core merge.

Note that while version 2 isn’t backwards compatible with version 1, it is an iteration on v1, so the API will be both inwardly and outwardly familiar to anyone using v1. We’re following a policy of not changing things purely for the sake of it, so the eventual version will be easy to adapt to for anyone using it now.

So far, our core focus has been around two key elements: extensibility, and consistency. We’ve refactored and rearchitectured a fair chunk of the core endpoints to make them more easily reusable, as well as ensuring that our core endpoints all follow a similar structure to make them easier to learn. As part of this, we’ve also introduced better support for common tasks like checking permissions, as well as changing the way endpoints interface with the infrastructure. One key change is that endpoints now receive only a single Request object parameter (modeled after PSR-7, for those keeping count). This means that parameter registration has moved out of the function signature and up to the endpoint registration instead.

We’re also working on making requests and responses consistent across the board, including swapping our dodgy filter parameters out for better supported querying. Fields are being renamed across the board (albeit not without careful consideration first) to make it easier to learn and use the API, as well as helping clients be more robust. Internal linking is also changing to match the HAL specification, along with support for “embedding” related requests. This is designed to help mobile clients and similar avoid excessive round-trips, but does come with the cost of larger response bodies, but we’ve made this up to client authors to decide and calculate the tradeoffs.

Meetings

API meetings now take place twice a week on Mondays at 23:00 UTC and Wednesdays at 23:00 UTC in the #core-restapi channel on the WordPress Slack. Our format is similar to the WordPress core meetings, with each meeting lasting up to an hour.

We also occasionally replace these meetings with voice and video meetings on Google Hangouts, depending on availability and agenda. In these cases, we’ll post the hangout link in the channel at the start of the hour. Everyone is welcome to join and listen in or participate, but please appreciate the limited amount of time and energy we have for these meetings.

Danke

Thank you again to all the wonderful people who make this API possible, including but not limited to the amigos (Rachel, Daniel, and Joe), our core team minders (Gary, Dion, and nacin, among others), lovable lurkers (Demitrious), everyone speaking about the API (I don’t know how Jack Lenox gets anything else done), our wonderful ~~publicists~~ journalists (Brian and Sarah), and everyone else. And you, especially you. ❤

We’re also opening this comment thread for any thoughts, feedback, feelings, or otherwise that you’d like to post. If there’s something you want to tell us or talk about, here’s the opportunity to do so.

#core-restapi

Ryan McCue 14:41 on May 27, 2014
Tags: 205

Hey everyone! Quick heads up…

Hey everyone! Quick heads up on some of the work that’s been going on this week:

The CLI client is now functional – The readme runs through how to connect WP-CLI to your site and get started. Currently, it only contains user and post reading functionality, however post creation/editing/deletion can be achieved relatively easy! This is more a question of time; building out the remaining functionality should be relatively painless. Volunteers welcome, as always!
Post endpoint testing is getting filled out – @rachelbaker and I have been working on getting these up, with the aim of 100% coverage of the post endpoint code. We’re slowly getting there! Reminder that we can always use help with writing tests, as there’s plenty to tackle here.
JS client is getting filled out – Thanks to Taylor Lovett, Matthew Haines-Young and K. Adam White for a huge push on the JS client recently. This client is significantly better than the version in 1.0 thanks to the tireless effort from these folks; that said, contributors are always welcome.
BuddyPress now has an API plugin – modemlooper has created a plugin that adds API endpoints for BuddyPress. Take a look if you’re interested in using BuddyPress data!
Pods now has an API plugin – Scott Kingsley Clark has created a plugin that adds API endpoints for Pods. Check it out!
I also threw up a quick doc site using Flatdoc with our existing route documentation. This doesn’t include our guides or the rest of our documentation, but is a cool start anyway!

(Worth noting, since I don’t think I did previously: the WooCommerce API was built from a previous version of the API. Also worth taking a look at.)

#205

Ryan McCue 05:08 on May 25, 2014

1.0 is out! Thanks to…

1.0 is out! Thanks to everyone who helped out with this release and made it the best so far.

That said, progress never halts! We’re working on 1.1 now, and there’s already a heap of issues open. We need to start on a huge documentation and testing push, which @rachelbaker has already started on.

We’ll also have the normal office hours this week; hope to see you there!

Ryan McCue 07:44 on May 5, 2014

Changes Coming in 1.0

We’re getting close to release for 1.0, so a quick heads up on some breaking changes that’ll be shipping with this release:

WP_JSON_Posts::prepare_author() is being removed: Use the new WP_JSON_Users::get_user() instead. (Previously a protected method, so only subclasses need worry.)
Basic authentication is being removed: This will now be available via a plugin if needed. This is mostly of use to developers working locally; live applications should begin using OAuth authentication instead.
Nonces will be required for cookie-based authentication: If you’re using WP API from Javascript, you’ll need to ensure you send the nonce with the request if you need authentication. Requests without nonces will be treated as being logged out, so they’re still fine for most GET requests.
Meta data will only be exposed for requests with the edit context: This is a workaround for the issues discussed with @iandunn previously, until we have more powerful permissions tools in core.

We’ve also got some awesome features shipping with this release:

User endpoints are now available: Thanks to the tireless efforts of tobych, the user endpoints are now active and useful! You can also use /users/me to check who you’re logged in as.
Revision endpoints are now available: Thanks to tlovett1, post revisions are now supported at /posts//revisions!
Post types can now use the show_in_json parameter: If you want to have a public post type, but still want to hide it from the API, you can now specify 'show_in_json' => false in your register_post_type call. This is the main resolution to the privacy issues previously discussed, props @iandunn.
Non-pretty permalinks sites are now supported: No need for weird hacks any more; you can now access the API at http://example.com/?json_route=/ instead. The discovery methods (Link headers and RSD) now also reflect this.

Thanks to everyone involved so far, and thanks to @rachelbaker for helping to manage the project! Thanks also to those who’ve been talking about and promoting the API at WordCamps; the evangelism is much appreciated!

We’re not done with this release yet: there’s also post meta on the radar that should make it into 1.0; you’ll be hearing more about that shortly.

I also know there’s people who’d love to get involved with the project. Your best bet is to take a look at the issues scheduled for 1.1. In particular, we’re looking for help in the following areas:

Javascript and theme developers: We have a JS library currently included with the API, but it’s in danger of not making it into the final version unless we put some serious work into it. Help is needed here; contributions always welcome!
WP-CLI developers: As a reference client for the API, Daniel Bachhuber is planning on working on a WP-CLI client. Help will definitely be wanted in this area, as there’s a lot of the API to use here.
Other developers: Help is always wanted on the API itself, but of special interest is the OAuth server code, which needs more testing. We also need more reference clients. If you can code in any language, we’d love your help creating clients in other languages.
Designers: The OAuth server currently contains a thrown-together UI, which certainly doesn’t match the slickness of WP.com’s UI. We could use help here.

Thanks again!

Ryan McCue 14:08 on March 5, 2014

Thanks to everyone who’s been…

Thanks to everyone who’s been helping out with 0.9, we’re down to just OAuth (and a smaller issue that needs a patch that does the opposite of the current one). Huge thanks to @ibaku for his work on the testing framework, and @rachelbaker for her help merging and triaging along with everything else.

I’d like to get more eyes and testing on the OAuth code before calling it final though. This has been sitting on my computer for a while, but still needs serious testing and more eyes before we can call it ready. I’d also love to hear thoughts on the approach in general too.

Aiming for 0.9 release this Friday. More posts to come during the week as we reach that, and scope for 1.0.

Ryan McCue 22:38 on December 2, 2013

Meeting notes from today, for…

Meeting notes from today, for those who missed it (see also the IRC logs):

Response Objects (#33)
Response objects are on their way. Discussed how we handle WP_Error and whether we should implement a WP_JSON_Error. I’m in favour of the former, since it’s an existing paradigm in WP core, but WP_JSON_Error being a Response object would be nice. We’re going to loop back to this after the response object is merged.

User Endpoints (#20)
We’re going with read-only access for now, since the code is basically already written (for post authors). Write access will be established later, but this is a pretty low priority for now unless anyone wants to tackle it specifically.

Endpoints vs Routes vs ?
@mikeschinkel pointed out that the terminology here is a little confusing, since the permalink system has a concept of endpoints too. As it relates to the API though:

endpoint = code which supplies a response, route = map from HTTP to endpoint

We’ll probably want to revisit this for core merge and clarify it, but this matches the wider API community terminology.

Unit Testing (#6)
Strong consensus here that we need help setting up the infrastructure for unit testing. @ibaku might be able to help us out with this, otherwise I’m sending out the Batsignal to scribu and wonderboymusic to see if they can give us some pointers (as they both have familiarity with testing).

Theme Developers and Outreach
@rachelbaker pointed out that I didn’t really say how theme developers can help out, so I clarified:

Right, so WP API has a built-in JS API. I’d love for theme devs to take a look at that and see what it’s like using it in the wild
I know Tareq Hasan has written a proof-of-concept one: http://tareq.wedevs.com/2013/09/backbone-js-powered-proof-of-concept-wordpress-theme/
I want to make sure wp-api.js is useful, and flesh it out with more methods as needed

@mzaweb noted we should see if the o2 team has any thoughts on this side of things, so hopefully @justin can help us with talking to them? Also noted that we should talk to the mobile team and get feedback from them, as well as the security team (in particular, mdawaffe) for feedback about authentication.

In short, lots of things to think about. This week’s release is all about OAuth (#32) and I’ll be pushing code up today for that, so we can start testing it. The OAuth stuff will be far from final, so feedback appreciated there too. Basic auth isn’t going anywhere just yet (#37 is scheduled for 1.0), so you can keep testing with that for now.

Ryan McCue 02:51 on November 25, 2013

Now, some meta notes: I’d…

Now, some meta notes: I’d like to welcome @rachelbaker and Aaron D. Campbell to the team!

I’d also like to announce that the team membership process is changing to an invitation process, based on contributions to the project. To coincide with this, it’s time to move to the next phase of this o2: open posting. As I noted in my original thoughts post, the discussion here was closed temporarily while we got familiar with the system. I think we’re all fairly well acquainted with the system now, so it’s time to open this up.

Comments are now open, but unfortunately, we can’t currently open posting up to everyone as from what I’ve been told, as WP.com doesn’t support automatically granting everyone contributor status. I’m working out what to do here, but suggestions are welcome if you have ideas. (The aim with this is to act similar to a mailing list, rather than an announcement blog.)