[wp-hackers] GSoC Proposal: JSON REST API

[Mike Schinkel]

Hi Ryan,

This sounds like a really great project, especially if it can make it's way into core. I've wanted WordPress to support a RESTful JSON interface for years now so if it can become a reality that will be great.

On Apr 10, 2013, at 5:19 AM, Ryan McCue <lists at rotorised.com> wrote:
> I'd love for comments and questions on this.


Looking at the code it's rather impressive but do have several questions:

1.) Are you envisioning a true REST API or more or an JSON-over-HTTP API? In other words:

a.) Will clients using be it be required to be 100% hypermedia driven, will clients use URL construction, or will you allow the clients to decide which approach they choose to use?  For a simple discussion of this:

http://www.emergentone.com/blog/the-future-is-hypermedia/

b.) Will you implement a WordPress-specific media type, something like "application/wordpress+json" or just use native "application/json" or use a hybrid like either "application/vnd.siren+json" or "application/hal+json?"

2.) Do I understand correctly that you're proposing a URL structure such as this (this example retrieves a post)?

http://example.com/wp-json.php/posts/{$post_id}

3.) Have you considered adding a version number to the API to allow the API to change in the future in case it is needed? See: 

http://www.mnot.net/blog/2011/10/25/web_api_versioning_smackdown

4.) Will you provide a method to discover the JSON API's root URL?  Offering this will allow API clients to automatically find the API even if the API URL has been changed is a hook. For example, a <link> header, something like this:

	<link rel="wp-json" href="http://example.com/..." />

5.) It appears you are implemented basic HTTP auth against a user account, correct?  Do you envision a class of API user that cannot be used to login to the website but can use the API?  What about API keys, or better yet both two-legged and three-legged OAuth 2.0 support?  

I ask these because basic auth is known to be insecure without SSL and could result in people gaining access to sites and a JSON API can't depend on nonces for security if it's going to be useful for anything besides AJAX. I know most sites logins are insecure but an API used for ongoing automation will present a much larger window of opportunity than an occasional user login.

6.) Will the JSON api be disabled by default and require the admin to enable it?

7.) Have you considered an additional form of API that would support JSON endpoints for the regular APIs on the site, like how this works:

http://teamtreehouse.com/tobypowell78
http://teamtreehouse.com/tobypowell78.json

BTW, I'm not suggesting you should make it hypermedia although those on the rest-discuss[1] and many on the api-craft[2] lists most certainly feel otherwise. But I do think it would be good to use a specific media type such as a single 
 "application/wordpress+json" media type for all JSON returned by this API.

Regarding mentors it seems you have some mentors lined up but in case you can have multiple mentors I'd be very willing to offer to be a mentor on this project. Working is APIs is one of the main things we do at NewClarity and I've personally had a keen interest in APIs since literally 1997,  been studying REST since 2006, wrote about it related to WordPress in 2008[3] (I was brand new to WordPress plugin development in those days) and have been working with APIs for clients for the past several years.

We also have a GitHub project called RESTian designed to allow mapping of specific API to enable creation of classes to access the specifics of the API that don't require the user to understand low level HTTP, for example[4]. It would be great to be able to release a RESTian-based API client for this API when the API itself is released.  We also recently wrote a JSON server[5] although it was not generic in order to meet to client's short timeline[6].

It would probably also be a really good idea to get someone really strong in security to co-mentor. I think it takes a special mind for security and this project could indeed create a big security problem if not carefully reviewed for security. (Not me, I'm not a security expert but maybe Jon Cave or Mark Jaquith.)

In summary, would love to see this get a green light, would love to hear the answers to the questions above, and am available to help as a mentor in whatever capacity is needed or desired.

-Mike

[1] http://tech.groups.yahoo.com/group/rest-discuss/
[2] http://groups.google.com/group/api-craft
[3] http://mikeschinkel.com/blog/restful-web-services-in-wordpress-plugin/
[4] https://github.com/newclarity/restian
[5] http://plugins.svn.wordpress.org/lexity-live-for-wp-e-commerce/trunk/classes/class-api-client.php
[6] http://plugins.svn.wordpress.org/lexity-live-for-wp-e-commerce/trunk/classes/class-api-server.php

P.S. If you'd not see it Apigee has a great ebox on videos on designing web APIs:

- http://info.apigee.com/Portals/62317/docs/web%20api.pdf
- https://blog.apigee.com/detail/api_design_third_edition_video_slides


On Apr 10, 2013, at 5:19 AM, Ryan McCue <lists at rotorised.com> wrote:

> Hi hackers,
> 
> There's at least a few of you out there who know me, but for those who don't: I'm Ryan McCue, a second year student at the University of Queensland, Australia. I'm currently studying Bachelors of Engineering (Electrical) and Science (Mathematics). Most of you will know me already via SimplePie, the feed parsing library included in WordPress, or my contributions to core.
> 
> For this year's GSoC, I'd like to propose a JSON API for WordPress. I've mentioned this project previously and have already outlaid part of the code to do this: https://gist.github.com/rmccue/5022591d312952d1245a
> 
> The scope of this project under GSoC would be the following:
> 
> 1. Develop the critical infrastructure to power a JSON-based REST API
> 
>   This is the most basic pieces of the REST API. This includes routing
>   URLs to methods, handling JSON serialisation/unserialisation,
>   ensuring compatibility with various servers/proxies, etc
> 
> 2. Create a REST interface for generic post types
> 
>   This involves creating a generic infrastructure to turn an internal
>   representation of a post into exportable data (including
>   normalisation) and vice versa.
> 
> 3. Building off the generic interface, create more specific interfaces
>   for built-in types
> 
>   For example, posts should expose their comments in a nicer way,
>   attachments should expose metadata relevant to their content, etc
> 
> 4. Ensuring that the API works well with clients
> 
>   Unless the API can work well with clients, it isn't of much use to
>   anyone. This part of the project would involve creating new clients
>   (for example, a Backbone-powered interface) as well as working with
>   the mobile teams to gain support for the new API.
> 
> An important part of the project would be ensuring that a) all WP APIs can be expected to behave in a similar manner; and b) plugins can easily extend the API and create their own more specific APIs. To this extent, the project would also involve creating a proof-of-concept extension of the API for a specific plugin.
> 
> Why a REST API? At the moment, the only real API to access WP content is the XML-RPC API. This requires a full suite of parsing tools and is less than optimal for most users. In the past, XML parsing (usually with libxml) has caused problems on mobile platforms, which are the main consumers of the API. A JSON REST API removes much of this complexity by using a simpler serialisation format (JSON) with a protocol usable by most of the web via standard HTTP verbs.
> 
> Why am I qualified? I'm the lead developer of SimplePie, which is roughly 10% of the WP codebase, and is a fairly complex piece of software to maintain. I have previous experience with working with nuances of HTTP clients and servers, via my Requests project (a PHP HTTP client, similar to WP_Http). I've also already made a start on this due to personal interest, and although it has taken a back seat, I've already been able to create clients that use the primitive start I've created. I also have a fairly intimate knowledge of WordPress and have contributed many patches in the past.
> 
> I'd love for comments and questions on this.
> 
> Note on mentors: Marko has indicated previously that he'd like to work on such a project, and has also applied to be a mentor. While GSoC requires that students create most of the code, the project could be structured in such a way that we can work on separate parts of the API together. Brian Petty and Eric Mann have also indicated they'd like to mentor such a project, and both would be great choices as well.
> 
> Thanks,
> 
> -- 
> Ryan McCue
> <http://ryanmccue.info/>
> 
> _______________________________________________
> wp-hackers mailing list
> wp-hackers at lists.automattic.com
> http://lists.automattic.com/mailman/listinfo/wp-hackers