[wp-hackers] GSoC Proposal: JSON REST API

[Mike Schinkel]

On Apr 11, 2013, at 1:57 AM, Bryan Petty <bryan at ibaku.net> wrote:
>> 1.) Are you envisioning a true REST API or more or an JSON-over-HTTP API? In other words:
> 
> This is a loaded question. There isn't a "REST API Standard" (and
> never will be from my understanding). The W3C doesn't publish anything
> along these lines. Nothing is a "true" REST API, because there isn't
> one. You can expect whatever features are deemed appropriate for
> WordPress specifically.

Yes, I know it was loaded, but not for the reasons you imply.  I wanted to determine if Ryan and others understood the objective meaning of REST or if it was understood from conventional wisdom. But I only wanted to enable discussion on the topic if the understanding wasn't clear.

That said I was not by any means trolling I am truly interested in being supportive of the effort.

So, you are correct there is no "standard" because REST is not a specification, but there is an objective definition for REST as an architecture. Roy Fielding coined the term "REST" and thus he is accepted as the one who gets to define what REST is and what it is not[1].  And there is no debate from the active members on rest-discuss or api-craft over this fact.

To be truly RESTful then an API must (among other things) "use hypermedia as the engine of application state."[1] It also requires a specific content type[2].

Note[3] I was not a "RESTifarian" in 2006 nor am I one today although I do understand REST much better today than in 2006. Said more directly, I don't think hypermedia should be a requirement but I do think that if hypermedia is not a requirement then the API proposed is explicitly not RESTful[1].

> It would, without a doubt, be the typical "application/json" content type, 

I think that would be result in huge opportunity missed.  

There is lot of benefit to a specific media type which Fielding recognizes[2] not the least of which is that a WordPress API client can know unequivocally that it is accessing a known JSON type with WordPress-specific semantics and that will allow for WordPress API browsers to be developed as client libraries (but we'd want only one media type, not a bunch of them.) 

Compare HTML to XML; when a browser requests and receives an HTML file it know about and knows how to handle elements like <img> and <table> whereas when it gets XML it can only know the syntax but not what it can do with it.  

Since WordPress has more than 17% of the web we have the potential to define and implement a highly influential and very useful new media type. If however only "application/json" is served then the result will be no consolidation around a "known" media type and much less related innovation, especially related to how WordPress could interact with media types.

This is a concern with or without merge to core because of the traction that it will likely see over time. If "application/json" is chosen, that decision will pretty much be "baked" in.

> Considering the tradition within WP to only maintain one version
> number, it would likely just expose something to check against the WP
> version itself. 

The idea of changing the API when a user upgrades a site is VERY troubling. I'm glad you said it was something to discuss further.

The tradition of maintaining only one version of WordPress is in my opinion a very good one, but an API has very different considerations than WordPress itself. Consider if WordPress releases a new version then sites owners can either upgrade or not.  For some site owners this is very annoying but overall it is best for everyone.

However envision that this new API could result in hundreds of mobile apps that use the API.  Then the next version of WordPress changes the API and now all those mobile apps break for ever site that has been updated to the most recent version.  It's like how a country can dictate laws for their own citizens but cannot force their laws on citizens of other countries who do not choose to travel to their country simply because they've published on the Internet; you wouldn't want Iran's or Russia's laws to apply to you when you post to your blog, would you?  Why is it appropriate that we force every Android and iPhone app developer to upgrade every one of their apps on WordPress' schedule?

So we can dictate versions upgrades to the WordPress community but it's not good form to attempt to dictate the need to upgrade their app. How will the app even know the behavior of an API for a site it is connecting to? This would be as bad for developers as IE6 was! Just like browser sniffed apps would have to do API sniffing. Ugh-ly! 

And if we do it will create a nasty black eye for WordPress the first time a major app that uses the WordPress API breaks because of such intransigence. The trade press will have a field day and those of us who believe in WordPress will be put on the defensive.

However, even if people don't agree today's solution is very simple; just begin the API's URLs with /v1/. If backward compatibility is always maintained we'll never need to change it.  But if we do decide we need us having added that will give us the flexibility to add a /v2/ in the future is we realize we need to. This is not "user facing" so it really does not to follow API best practices.

Same concern here as with media type for not merging into core because traction will "bake" this decision into future core implementations.

> 4.) Will you provide a method to discover the JSON API's root URL? 
>> Also applies as an "extra".

That is a trivial implementation and doing so will enable mobile and other apps to access sites without difficulty for users; not doing so would sadden me for the opportunity lost cost.

I'm assuming a merged into core.  If not, it's not (yet) a big concern.

> I agree that OAuth 2.0 would be great,... but I still don't think this falls within GSoC project scope.

I concur if not yet merged into core.

> WP.com does support OAuth 2.0, but doesn't even include request rate
> limits itself yet either.

One thing about WP.com is they use HTTPS[4] which is not very common on most sites. Reading this rant[5] from the OAuth spec author which was effectively about authentication schemes that don't use SSL was very sobering.

A lot of what I'm bringing up here I've learned from both experience and by following lists like rest-discuss and api-craft. If this GSOC project gets greenlit I would really hope that Ryan and his mentor(s) would join the api-craft list at least and run architecture decisions by them. Collectively the people on that list have learned many lessoned about web API architecture and it would be a shame for the WordPress community to be saddled with the issues associated with learning web API best practices via trial and error when there's so much about web API architecture that is already known. To be clear, I count myself as still having a lot I can learn from them too which is why I monitor the API Craft list daily.

-Mike

[1] http://roy.gbiv.com/untangled/2008/rest-apis-must-be-hypertext-driven
[2] http://roy.gbiv.com/untangled/2008/rest-apis-must-be-hypertext-driven#comment-753
[3] http://mikeschinkel.com/blog/whatisarestafarian/
[4] http://developer.wordpress.com/docs/oauth2/
[5] http://hueniverse.com/2010/09/oauth-bearer-tokens-are-a-terrible-idea/