[wp-hackers] GSoC Proposal: JSON REST API

[Bryan Petty]

Let me just prefix this entire reply to point out that this is just
the birth of a REST API to begin with, and it wouldn't be in core
immediately in 3.7 (and probably not even 3.8). As such, you can
expect a very stripped down, simplified REST API only covering the
basics. The goal for something deliverable by the GSoC deadline needs
to stay reasonable and achievable with only 2 months of work.

On Wed, Apr 10, 2013 at 10:33 PM, Mike Schinkel <mike at newclarity.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.

> 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?

This is one of those "extras" that isn't necessary for a first draft,
and shouldn't be any kind of goal even for whatever might be finally
merged into WP core, well past this GSoC project proposal.

> 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?"

It would, without a doubt, be the typical "application/json" content
type, but worth noting that there's not much stopping it from also
including "application/xml" if clients prefer XML instead of JSON.

> 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?

Considering the tradition within WP to only maintain one version
number, it would likely just expose something to check against the WP
version itself. I've seen quite a bit of resistance from even
suggesting that the plugin API maintain it's own version, so I highly
doubt this would qualify for it's own either.

However, you do have a good question here, and it would be something
to discuss if this project was accepted.

> 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.

Also applies as an "extra".

> 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 agree that OAuth 2.0 would be great, and maybe even a requirement
for merge into core (I can envision *tons* of clients/consumers that
would require this), but I still don't think this falls within GSoC
project scope.

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

It goes to a plugin first, and we would consider this upon merging to
core, but I would imagine that based on the decision to enable XML-RPC
by default in 3.5, this would likely do the same.

> It would probably also be a really good idea to get someone really strong in security to co-mentor.

Yes, this would be good, but we haven't even discussed whether this
API would include authenticated API endpoints yet within the GSoC
project timeline.

Along these lines, I'm not sure yet if we should be looking at request
rate limitations yet either. At least this would be distributed, but
I'm certain we would end up taking a ton of hints from the WP.com REST
API: http://developer.wordpress.com/docs/api/

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

Regards,
Bryan Petty