[wp-hackers] GSoC Proposal: JSON REST API

[Ryan McCue]

Hey Mike,

Replies inline.

Mike Schinkel wrote:
> 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:

Hybrid. URL construction can be used if it's easier, but most endpoints
will provide hyperlinks for clients which want to support that. To that
end, an index will also be provided to enable full discovery of the
endpoints.

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

"application/wordpress+json" would be nice, but requires an IANA
registration, which likely means going via an RFC. Given that the format
is for WP interoperability (for the foreseeable future, at least), the
type would either be "application/vnd.wordpress.api+json" or simply
"application/json" for maximum compatibility.

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

Correct.

> 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

I'm a huge fan of mnot's posts (especially given that he's an authority
on REST), and I've looked at this post a fair bit. For this project, all
factors involved would need to be considered, so I have not yet made a
decision on this.

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

Absolutely. While it should be rare that the API URL gets changed,
discovery is an important part of this. This would allow, e.g., custom
domains to delegate the API to a central WP.com API endpoint.

(Also note that "wp-json" isn't a great relation here; non-registered
relations should be URLs. Likely, it'll be rel="alternate" with
type="..." as per above.)

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

There's currently only Basic authentication as that's the bare minimum
that's needed. Anything past this would be handled by plugins (note the
json_check_authentication filter).

I'd like to implement OAuth 1.1 authentication in a plugin, as it's
pretty useful. I've also written code to do basically this before, which
is in production use at the moment:

https://github.com/rmccue/WordPressOAuthProvider

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

As Bryan noted, this will start life in a plugin, so it will be opt-in.
Upon core integration, it will be enabled by default (similar to the
XML-RPC API) with the ability to disable it via a filter (note the
json_enabled filter).

> 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

I have considered it, but IMO it's outside of the scope of the project.

If anyone wants to achieve this functionality, registering a new
endpoint with the rewrite API and pointing it at the API class should
suffice.

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

Thanks! One plus of this project seems to be that quite a few people
want to mentor it, so we'll just have to see how it works out.

In any case, I definitely won't be writing the whole thing in isolation,
and I'll be soliciting feedback regularly.

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

Agreed, the more implementations out there, the better. Once the API
stabilises and an initial client is written, I'll put out the call for
client developers to start playing with the API to ensure it's solidly
built.

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

I've got a bit of experience dealing with security issues from SimplePie
and related projects, but I agree completely. I'd love to hear from Jon
or Mark whether they'd like to co-mentor this project (or act as just a
security-related overseer).

Thanks for the feedback!

-- 
Ryan McCue
<http://ryanmccue.info/>