[wp-hackers] GSoC Proposal: JSON REST API

[Mike Schinkel]

On Apr 11, 2013, at 11:56 PM, Ryan McCue <lists at rotorised.com> wrote:
> By ensuring a consistent API here, it means that e.g. a WooCommerce
> endpoint could simply wrap around the existing method:
> 
> 	function getProduct($id) {
> 		$data = WP_JSON_Server::getPost($id);
> 		$data->price = get_post_meta('_price', $id, true);
> 		return $data;
> 	}

Seeing this I have another concern and that is of implementing the getPost() method as static instead of as the instance method given the difficulty of correctly unit testing static methods[1].

On Apr 12, 2013, at 12:14 AM, Ryan McCue <lists at rotorised.com> wrote:
> One important part to keep in mind is that this API needs to balance the
> theoretically "best" way to do things with pragmatic concerns. For
> example, the Range header would be a great way to specify how many posts
> you want back from a collection (list of posts, e.g.). However, this is
> problematic due to problems with misbehaving proxies in addition to
> being harder in Javascript.

I'm not very concerned about pragmatic choices being taken with full understanding of the issues but instead for abritrary choices made because they "seemed like the right way to do it at the time."

On Apr 12, 2013, at 12:14 AM, Ryan McCue <lists at rotorised.com> wrote:
> These types of concerns will certainly be taken into consideration and
> I'll endeavour to discuss any large architectural decisions to ensure
> that we come up with something that everyone is satisfied with.

I was presuming that, like me, you are not perfect in your understanding of these issues nor, like me, that you have not had the same level of experience in these issues as the collective experience of those who frequent the equivalent list to this for web service issues.

On Apr 12, 2013, at 12:21 AM, Ryan McCue <lists at rotorised.com> wrote:
> I agree, but we also need to balance other concerns (such as browser support for +json).



Can you give an example (where a browser would support "application/json" and thus using "application/vnd.wordpress+json" would be a problem?)  I can't think of a specific one at the moment.

> Whereby "I have not yet made a decision" means "I haven't considered the
> differing opinions in enough depth, nor have I considered views in the
> WP community enough to make a consensus". This isn't a dictatorship, but
> design by committee is a serious problem that needs to be considered.

"Design by committee" is indeed a concern, but a bigger concern is "delivering an architecture in 2 months that needs longer to get right."  This is not a UI feature, this is an interoperability architecture.

A perfect example of schedule affecting architecture is the Menu system.  The core team focused on a delivery date for it instead of allowing it's architecture to be fully fleshed out before it was "baked in" to core, and many developers including myself have lamented the issues that the rushed design has caused.  Fortunately at least the menu system only affects WordPress core and its plugins and themes, not a potentially untold number of apps that might integrate with WordPress.

Frankly I'm starting to be very concerned that the timeframe allowed for a GSOC project would trump the calendar time required for discussions to achieve the best compromises in architecture.  I think this addition probably really needs to be a blessed Trac ticket where all that have interest are free to input and provide patches.  I fear if this is a GSOC project it will may result in an plugin that by nature will be blessed by the community but that will result in many unfortunate timeframe compromises that will only be recognized at problematic several years after the plugin's functionality gets incorporated into core.

Based on these discussions, and while it pains me I must reverse my earlier endorsement. I think it would be a mistake for WordPress and it's community if this were project were accepted for GSOC.  There are too many decisions that should be considered by more than a small number of eyes to allow a 2 month window to "bake in" it's architecture. 

A JSON API that can affect 70 million websites needs more time than 2 month to get right.

-Mike
P.S. Ryan: Please do not feel that I am attacking you in any way.  I have great respect for you. I'm instead focusing on what I think will be in the best interest of the WordPress community and WordPress as a platform. Clearly you should be heavily involved in this project, but I think it should be managed on Trac, not via GSOC. 

[1] http://stackoverflow.com/a/5961347/102699