Quick comparison – XML-RPC vs. JSON WordPress APIs

This weekend at WordCamp San Francisco, there has been much discussion and advertising for the nascent JSON API. I noticed some confusion among the audience and some unclear answers from speakers, so here’s a quick comparison of the new JSON API versus the existing XML-RPC API.

Scope

XML-RPC – Editing

The XML-RPC API was created to power desktop clients and other forms of integrations with WordPress for the sake of managing content and moderating comments. All of the methods are restricted to users with caps like edit_posts or moderate_comments or upload_files, which are only available to users with at least author-level privileges. This makes the API mostly useful for desktop or mobile clients that assist with managing content.

JSON API – Anonymous read, editing, management

The JSON API has a more ambitious scope to cover everything WordPress can do. In addition to managing content, a primary goal for the JSON API is to provide anonymous read access to data for use by themes or other apps. The team also wants to expose administrative functionality, from plugin installation and theme activation to settings changes.

Protocol

RPC – “Remote Procedure Calls”

RPC APIs allow external code to invoke procedures (also called “functions” or “methods”) by name with a set of arguments. The entire API consists of a list of published procedure names, and clients invoke them by name like “wp.getPosts” or “wp.uploadFile“. Clients must be aware of each method, their expected arguments, and return values, which can lead to complexity in the client for common flows like retrieve-then-update a post.

REST – “REpresentational State Transfer”

REST APIs are modeled after HTTP and the web, leveraging HTTP verbs, status codes, content types, and more. Clients have knowledge of the content or resource types (e.g., “post”, “user”), and navigate the API primarily by following links or using URI templating.

Serialization Format

XML

XML-RPC API uses XML format for data transfer. XML is a widely used markup language and data interchange format, with support in almost all programming language standard libraries. Serialization or deserialization of XML can be somewhat cumbersome in some languages, though many libraries exist to make it easier.

JSON

The JSON API uses JSON format for data transfer. JSON is a lightweight object serialization format that is easy to use in most programming languages and has limited syntax. Because the format was derived from JavaScript’s object literal syntax, it is extremely easy to consume from JavaScript which makes it attractive for interactive web applications.

Authentication

XML-RPC

WordPress’s XML-RPC API passes user credentials as part of each request. This means that users must give the app their WordPress account password. The password is not encrypted, so XML-RPC is only secure when used over HTTPS so that network peers cannot sniff your credentials or sensitive data.

JSON API

The JSON API plugin currently supports multiple authentication mechanisms, including OAuth 1.0a and HTTP Basic authentication. The former prevents the app from seeing the user’s WordPress password and is therefore safer over non-HTTPS connections, while the latter requires HTTPS to prevent network sniffing of credentials.

Current usage scenarios

XML-RPC

The primary consumers of XML-RPC today are the official WordPress mobile apps and several desktop blog clients like MarsEdit and Windows Live Writer. Many companies use XML-RPC for communication between WordPress and other software/services that they operate.

JSON API

To date most of the usage of the JSON API plugin has been for frontend apps. There are plans in motion to migrate the official mobile apps to use the new API, and also to start using the API to power parts of the WordPress admin interface.

Recap

The XML-RPC was created back in WordPress 1.5.0, and overhauled in WordPress 3.4 and 3.5 to support all of the latest WordPress functionality. For managing or syncing content across any WordPress site in existence today, the XML-RPC API is a great option. The cumbersome XML format scares many people away, but there are libraries in most languages that can take care of this complexity for you (e.g., my Python library).

The JSON API will open the door to many new scenarios, especially for site front-ends where anonymous read access is required. The administrative functionality will be used to great effect for the WP admin and remote management services. The REST format allows use of many existing REST client libraries, and the JSON syntax makes for easy consumption in JavaScript.

If you are comfortable installing plugins and writing your own API clients, go ahead and install JSON API plugin and build awesome new experiences. For the rest of the world, we hope to finish the remaining work and get this into WordPress core sometime in 2015.

Leave a Reply