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 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 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.

    (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 revisions.

    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 header 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 Javascript
    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 multisite 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 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.

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 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.

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!