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