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 meta endpoints. It also introduces our long-term backwards compatibility policy, aligning with WordPress core 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/mecan 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.
Add post meta endpoints.
Creating, reading, updating and deleting post meta is now possible by using
/posts/<id>/metaendpoints. Post meta is now correctly embedded into
Meta can be updated via the Post entity (e.g.
/posts/<id>) or via
the entity itself at
/posts/<id>/meta/<mid>. Meta deletion must be done via
DELETErequest to the latter.
Only non-protected and non-serialized meta can be accessed or manipulated via
the API. 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.
Add endpoint for deleting a single comment.
Clients can now send a
DELETErequest to comment routes to delete
Custom post types supporting comments will gain this ability automatically.
Add endpoint for post revisions.
Post revisions are now available at
/posts/<id>/revisions, and are linked in
meta.links.version-historykey of post entities.
Custom post types supporting revisions will gain this ability automatically.
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 header or RSD).
Add register post type argument.
Post types can now indicate their availability via the API using the
show_in_jsonargument passed to
register_post_type. This value defaults to
publicly_queryableargument (which itself defaults to the
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.
Require nonces for cookie-based authentication.
This breaks backwards compatibility and requires any clients using cookie
API automatically handles this.
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.
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
json_ensure_responsefunction to ensure either a
WP_Errorobject is returned.
When extending the API, the
json_ensure_responsefunction can be used to
ensure that any raw data returned is wrapped with a
This allows using
still be checked via
Use version option to check on init if rewrite rules should be flushed.
Rewrite rules on multisite are now flushed via an init hook, rather than
switching to each site on activation.
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 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 plugin 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.
From this release forwards, backwards compatibility will not be broken. This includes both the internal PHP API, as well as the 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.
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.