[wp-trac] [WordPress Trac] #14618: Proposal: Standardize WP Responses to JS Requests as JSON

[WordPress Trac]

#14618: Proposal: Standardize WP Responses to JS Requests as JSON
-------------------------+--------------------------------------------------
 Reporter:  filosofo     |       Owner:     
     Type:  enhancement  |      Status:  new
 Priority:  normal       |   Milestone:  3.1
Component:  JavaScript   |     Version:  3.0
 Severity:  normal       |    Keywords:     
-------------------------+--------------------------------------------------
 = Summary =
 I propose that we standardize Ajax actions on the
 [http://groups.google.com/group/json-rpc/web/json-rpc-2-0 JSON RPC 2.0
 spec] and provide a JSON-RPC API for querying content.

 = Motivation =

 == Inconsistent Admin Behavior ==
 Currently, when JS in a user's client (browser) makes a request to WP, the
 response can appear in a variety of forms: integers, JSON, XML, or
 sometimes nothing at all.

 Because WP has such a variety of responses, that means in similar
 situations it's using different ways to make requests and handle
 responses.  Doing similar things a bunch of different ways increases the
 maintenance overhead and therefore the likelihood of there being bugs.  It
 also means that future implementations and plugin authors have little
 guidance on best practice.

 == JS Query API ==
 There seems to be interest both in [ticket:14372 querying comments] and
 [http://lists.automattic.com/pipermail/wp-hackers/2010-June/032748.html
 posts] in a data exchange format easily adapted by JavaScript.

 = Proposal: Core JSON RPC =

 == Why any standardization? ==
  * A single way of doing things means for programmers that you don't
 repeat yourself (DRY)
  * A standard way of handling such requests focuses attention on a few
 sections of code, so bugs are noticed sooner and fixed in a wider range
  * Standardization gives guidence to future development, both of core and
 plugins
  * Standardization provides greater possibility of interactivity among
 core, plugins, and other sites and applications.


 == Why JSON? ==
 In transmitting data JSON has at least several advantages:
  * It's lightweight in content, using less bandwidth than for example XML.
  * It's well-supported across a number of languages, most notably
 JavaScript (and PHP 5).
  * It seems to be growing in popularity

 == Why a remote procedure call (RPC)? ==
  * Most of the Ajax in WP is in the form of an RPC.
  * We could appropriate some of the code used already with XML-RPC in WP.
  * It's a common way of doing something we need: standardized ways to
 initiate actions on a remote computer

 == Why JSON RPC in particular? ==
  * JSON RPC allows requests to specify an ID which the response also
 includes.  The ID allows a client to make asynchronous requests yet avoid
 race conditions, by matching request to response.
  * JSON RPC uses some of the same error codes as XML-RPC, and using
 standardized error codes creates consistency and easier localization.

 == Admin Ajax ==
 Admin ajax requests and responses should be converted to use the JSON 2.0
 RPC

 For example, a request to delete a comment could look like the following:

 `{"jsonrpc": "2.0", "method": "wp.deleteComment", "params": [123], "id":
 4567}`

 Note that the `wp.deleteComment` method is already defined for XML-RPC;
 using a common interface would give greater attention to XML-RPC and would
 improve consistency across the board.

 A response to the following might look like this:

 `{"jsonrpc": "2.0", "result": "deleted", "id": 4567}`

 WordPress would provide the JS for making the JSON requests, attaching
 listeners and matching responses to the appropriate callbacks by ID.
 Perhaps like so:

 {{{
 wpMakeJSONQuery('wp.deleteComment', [123], myCallback, myErrorCallback);

 function myCallback( result ) {
         alert('Comment ID #' + result + ' deleted!');
 }

 function myErrorCallback( code, message, data ) {
         data = data || {};
         alert('Error: ' + message );
 }

 }}}

 Your thoughts?

-- 
Ticket URL: <http://core.trac.wordpress.org/ticket/14618>
WordPress Trac <http://core.trac.wordpress.org/>
WordPress blogging software