API discovery ala RSD #40

merged 1 commit into from Feb 17, 2014

3 participants


As a developer of API clients, I'd really love a proper API discovery mechanism for WP-API. The XML-RPC API uses RSD, which allows clients to do an algorithm like:
1. Ask user for their blog URL
2. GET that URL and find the <link rel="EditURI" .../> tag.
3. Extract the href from that <link> and GET it.
4. Parse the RSD file to determine which endpoints are supported and preferred.

Of course, sometimes overzealous theme authors will strip this default <link> tag and we have to fallback to blindly checking /xmlrpc.php?rsd, but fortunately that's not too common.

My recommendation is that WP-API do (at least) one of the following:
1. Add itself to the existing RSD file. This makes it easy for existing XML-RPC clients to "upgrade" to the JSON API when available, though it still means dealing with XML which is a pain.
2. Add a new <link> tag to the blog <head> that clients can look for.
3. Send a new HTTP header on WP page responses with the path to the API
4. ???

Blindly searching for /wp-json.php or some rewrite-rule variant should really be avoided if at all possible.


Another motivation is to avoid issues like WP#18731, where you can't rename xmlrpc.php file without breaking compatibility with the world. If WP-API ships in core with a robust discovery mechanism then that allows for more flexibility for atypical deployment patterns or pretty URLs or whatever.

WordPress REST API Team member


I'd like to do this two-fold:

  1. Add it to the RSD, as noted
  2. Send via a Link header on all pages (including frontend and backend)

The latter should be the preferred option, since it's then a single HEAD request to find the API.


why not JSON-LD ? It's pretty new granted, but if you go down the JSON path, why not go the whole way?
or Swagger ? https://github.com/wordnik/swagger-core/wiki ... For me the more important question in today's web is what can an API do for me... Swagger displays that beautifully

I look at wordpress more and more as an application development platform, IMHO it should go along with the times... Using XML to describe JSON is illogical ...

WordPress REST API Team member

Using XML to describe JSON is illogical ...

In this case, it's because RSD is a known quantity and it already has parsers. Creating our own standard is more illogical, really.

That said, this is just for discovering the API, nothing else. We use JSON Schema to describe the output of the API already.

@rmccue rmccue merged commit ff7fa5a into master Feb 17, 2014
@rmccue rmccue deleted the discovery branch Feb 17, 2014
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment