REST API: Welcome the Infrastructure to Core

Hi from the REST API team! We’re extremely excited to announce the API infrastructure has now been merged into core as of r34928 (plus a couple of fix up commits we won’t mention). Huzzah!

Sincere thanks to every single one of the contributors, we wouldn’t be where we are today without you. It takes time and effort to produce great things, and it’s impossible to make things great without everyone helping. This has been a truly collaborative effort, and I wish I could do more than just give you props.

(Important note: if you have a 2.0 beta already installed, you must upgrade to beta 5.)

What’s included in 4.4?

As mentioned in the merge proposal, the API comes in two parts: infrastructure and endpoints. In 4.4, the infrastructure is now available as part of core, while the endpoints continue to only be available in the plugin.

You can think of the infrastructure as an “API construction kit”. WordPress 4.4 will make it possible for everyone to build RESTful APIs in a much easier fashion, which will benefit people building custom APIs for their site. The infrastructure handles the routing, argument handling, JSON serialisation/deserialisation, status codes, and all that other lovely REST stuff.

For client authors, this doesn’t help you much right now. Hold tight, the team is working as fast as we can on the endpoints to get them ready for a future release. In the meantime, you can make sure sites you want to work with have the plugin installed, which isn’t a change from the current state.

For plugin and theme authors, you can start building new APIs immediately using the infrastructure now in core. This can start replacing your existing custom admin-ajax endpoints or other bespoke code you already have.

To authenticate with the API, only built-in cookie authentication is available out of the box right now. The OAuth 1 plugin will continue to work with WP 4.4 and the API plugin, as will the Basic Auth plugin for local development.

It’s super easy to get started, and there’s even a guide available to kick-off. (Note: the WP_REST_Controller class is not included in WordPress 4.4.) This documentation will be migrated across to soon.

If you want to access any of the built-in data in WordPress without building it out yourself, you’ll need the endpoints as well. These will continue to be packaged in plugin form, and version 2.0 final will be released to accompany 4.4 before the end of this cycle.

What if I’m using the API already?

If you’re on version 2 of the API, you’ll need to update the API to beta 5 or later before updating to the latest version of core. This new version will use the new infrastructure in core if available, or fallback to a compatibility library otherwise.

Important note: Earlier 2.0 betas (1 through 4) are incompatible with WP 4.4. Your site will fatal error if you don’t upgrade to beta 5 or later. You must upgrade to the latest API to run trunk and to run WP 4.4 when it’s released.

If you’re on version 1 of the API, you won’t hit any fatal errors straight away, but endpoints will stop working with 4.4. We’re still planning on releasing a final version 1 release for compatibility, but now would be a great time to consider migrating forward to version 2. Apart from security releases, version 1 has ceased being actively maintained.

Looking forward for the API

Now that the API is past this first hurdle, it’s important to keep looking forward. Our immediate next step is to improve and polish the endpoints for phase two of our merge. There’s a lot of work still to be done here, so we’d love you to join us on GitHub.

The infrastructure of the API will now be maintained via Trac, so new issues and patches should be sent there instead under the “REST API” component. Issues with endpoints should still be filed on GitHub. Don’t worry if you’re not sure; you can file issues on either Trac or GitHub, and they’ll be triaged into the correct place as needed. (It’s more important to make sure the issue is filed in the first place!)

The team wants to keep pressing forward with the API and keep up our rate of progress, if not improve it even further, and we’d love your help. We still need help from content writers on our documentation, designers and developers on our authentication plugins, and developers on the endpoints. If you want to help, we can always use a hand, and we’d love to help get you started. We’re available in the #core-restapi room on Slack, and we’d love to see you at the weekly meeting at Monday 23:00 UTC 2015.

We look forward to continuing to work on the API and getting these endpoints happening. Thanks again to everyone who got us here.

(Then again, maybe a REST API is more of a Shelbyville idea…)

#4-4, #dev-notes, #json-api, #rest-api