Extending WordPress Web Services

Abstract
WordPress Web Services allow you to modify your blog remotely. WordPress supports XMLRPC And Atom protocols. Most of the clients use XMLRPC methods including WordPress mobile clients. However the current XMLRPC implementation have some limitation. The goal of this project to extend XMLRPC functionalities of WordPress.

Benefits for WordPress and clients
Additional features for clients.
Reduce server load.
Increased response time and reduced bandwidth usage for clients.
Reduces redundant calls.
All the features are backward compatible

Project Goals

User Management
There is no methods to manage users via XMLRPC. Managing users using clients would be a very useful feature. There would be new user tab in my wp-android app . The proposed methods will allow only current user to manage user with a capability check. New users can’t register themselves because it will allow spammers to create mass accounts.
Also its better if we have a method to get capabilities of the user when connecting at the first instance so we can validate capabilities at the client end. This will reduce redundant calls to the server.
This is very important feature we need.

Improved Search API
This has been addressed on tickets #6850and #16316. The current search methods imposed unnecessary burden to the server, A more generalized search API for all getters (posts, users, comments etc) will increase the performance of both client and server. The changes will only modify the getters to accept more argurements to be passed to the next method. So the amount of work here is very small
Post/Pages – WP_Query class accepts a lot of parameters for querying post/pages. Modify the getRecentPosts methods to accept these parameters and pass it to the WP_Query. This includes retrieving posts by category,tag,date etc.
Users – WP_User_Query class can be used to query users. These parameters will be passed through the new wp.getusers method. This includes retrieving users by roles etc
Comments – Again WP_Comment_Query class can be used. wp.getComments will pass more paremeters such as author _email etc.
There is also another option of separately querying using global $wpdb similar to getPageList.

Custom Post Types Management
WordPress 3.0 gives you the capability to add your own custom post types and to use them in different ways.A generic API for managing posts would be beneficial include post, pages, nav_menu_items as well as user defined custom post types.
Custom post type are not stored persistently. Managing custom post types want be desirable and many developers feel that way. So I’m dropping managing custom post types via xmlrpc. What would be desirable is that editing posts with already registered types. Abstracting the metaweblog API to support custom post types is useful.
Same approach can be done for taxonomy management as well.

Custom Taxonomy Management
WordPress 3 gives us fully hierarchical custom taxonomies. Managing custom taxonomies would using clients be awesome. Again custom taxonomies also not stored persistently. So I,m not supporting new taxonomies via xmlrpc. Same as custom post type a generic API for editing taxonomies is good as it includes categories, tags, post formats, nav_menus as well as user defined taxonomies.

Managing Blog Options
There is only a few options that can be changed via xmlrpc. Its good to extend it to support more options. These options can be grouped as public and private. Some options must be exposed all registered users where as some must be exposed only who has the capability ‘Manage options.
Considering backward compatibility we can introduced completely new methods which can acts as a gateway to get_options, update_options in the functions.php. Using these two methods any of the blog settings can be changed.

Proposed New API

User Management
wp.newUser
wp.editUser
wp.deleteUser
wp.getUser
wp.getUsers

Custom Post Types Management
wp.getPostType
wp.getPostTypes

Custom Taxonomy Management
wp.getTaxonomy
wp.getTaxonomies
wp.newTerm
wp.editTerm
wp.deleteTerm
wp.getTerm
wp.getTerms
wp.setTerm

Managing Blog Options
wp.getSettings
wp.updateSettings

Changes to the existing API

User Management
blogger.getUserInfo

Custom Post Types
metaWeblog.mewPost
metaWeblog.editPost
metaWeblog.deletePost
metaWeblog.getPost
metaWeblog.getRecentPosts

Search API
metaWeblog.getRecentPosts
blogger.getRecentPosts
mt.getRecentPostTitles
wp.getComments

Security Checklist for methods
Login Checks
Capability checks
valid id checks

Scope of the project

The projects consist of 5 sections to be completed by midterm. The time line explains the schedule. At first glance the project may seem overly ambitious. Let me explain this with the first section of the project. The first section is to provide user management through XMLRPC.it has 6 functions to be completed within a week.
I implemented the first function wp.newUser

http://code.google.com/p/wp-xmlrpc-server/source/browse/trunk/wp-xmlrpc-server.php

please note the coding approach. Like most the existing XMLRPC functions it uses a lot existing code. wp.newUser accpets relevant arguments do some checks and formatting and pass it to wp_insert_user in user.php.
Most of the errors checking and formatting are done there and the results are caught and send back to the client. Querying directly from $wpdb is omitted whenever possible.
It took me around 2-3 hours to implement the first function at the first go. I,m confident I can implement all 6 functions in one week which will take around 15-20 hours. Also with the learning curve the time may reduce. Same thing applies to the rest of the sections.
After each attribute/function I test it with a client with possible use cases.Here is the client I use

http://code.google.com/p/wp-xmlrpc-server/source/browse/trunk/Client/WPClient.java

Possilbe test cases are listed here

http://code.google.com/p/wp-xmlrpc-server/source/browse/trunk/#trunk%2FTests

The project will be finished by midterm and I have 3 weeks for testing and 2 weeks for documentation. Though the suggested coding period begins on May 23rd most probably i will start coding before that.
Considering these 5 sections i’m not convinced the scope of the project is too high and i’m confident that I can finish the project according to the schedule.

Coding Approach
Most of the new API will take advantage of the existing WordPress API. Methods will act as gateway for accessing the existing API. This way repetition is code is omttted. Querying from the global $wpdb will be avoided as possible. The natural behaviour of WordPress core will be adopted.

Testing and Documentation

The following tools will be used for testing each methods
Java Client built on Apache XML-RPC libraries
Apache JMeter
Apache TCPMon

First I checkout the trunk and a local installation will be made. Open the trunk with the IDE.
After every method I will add test cases in the Java client and see whether I,m getting the correct response. TCPMon will be used to intercept the communication to see the request and response xml. In some case the request xml will be ok but the request will not be processed by the IXR Client accordingly(See this ticket #16980).
JMeter will be used to loadtest the xmlrpc server to benchmark performance. If there are two options for implementing a particular method JMeter will used to record response time, accuracy etc and the results will be compared to take a decision.I,m familiar with all the tools mentioned above.
All the methods will be completely documented and the existing methods also will be documented at the end of the project.

What have you done so far with this idea
I have analyzed the WordPress codebase and identified the workflows for each methods. A very few methods lacks support from core API. I will add patch for that. I have shared the idea in wp-xmlrpc list. I got the following ideas from the list and added to the project
Reduce redundant calls
Omit methods for creating custom post/taxonomies since there are not stored persistently
Method for event notification
Merge mw_post and mw_newMediaObject

Plugin theme or core
First I intend to create it as a plugin and later integrated to the core.

Anticipated challenges
I have already completed my research part and identified the workflow of each methods. So no time will be spent on learning. Some of the challenges I see is abstracting metaWeblog methods to support custom post types. From my experience I know it want go well at first. But I consider it as a minor issue.

potential mentors
Eric Mann has agreed to mentor me in this project. I have sent the draft proposal to him and got feedback on that. Eric mentioned to abstract the methods to support custom posts and taxonomies.

Thorsten Ott also agreed to co-mentor this project

Schedule of Deliverables

Milestones and deliverables schedule

Community Bonding Period
Apr 25 – May 22
Finalize the API. Develope Common functions to be used in the plugin. Plan the coding approach and abstraction of functions

User Management
May 23 – May 29

wp.newUser
wp.editUser
wp.deleteUser
wp.getUser
wp.getUsers
blogger.getUserInfo

Custom Post Type
May 30 – June 12

wp.getPostType
wp.getPostTypes
metaWeblog.newPost
metaWeblog.editPost
metaWeblog.deletePost
metaWeblog.getPost
metaWeblog.getRecentPosts

Custom Taxonomies
June 13 – June 26

wp.getTaxonomy
wp.getTaxonomies
wp.newTerm
wp.editTerm
wp.deleteTerm
wp.getTerm
wp.getTerms
wp.setTerm

Search API
June 27 – July 3

metaWeblog.getRecentPosts
blogger.getRecentPosts
mt.getRecentPostTitles
wp.getComments

Blog Options
July 5 – July 8

wp.getSettings
wp.updateSettings

July 9 – July 10
Release Alpha Version

MID TERM EVALAUTIONS

July 12 – July 25
Testing with various use cases. Identify bugs and rework the code. Release beta version

July 26 – Aug 3
Get feedback from the community and developers. Improve the code with possible additions

Aug 4 – Aug 15
Documentation and final stable release

Deliverables
First I intend to develop it as a plugin then integrate it into the core. This would be a series of patches for every methods mentioned above. I will upload it the trac and assist the progress. I,m expecting it would be in version 3.3 core.