Support Auto-Discovery from top-level API root endpoint response

[kadamwhite]

One major point of discussion at WCNYC surrounding the API is how to handle discoverability, as it was recommended to consider templated URLs (which are common with SAAS-provided APIs) to be an anti-pattern when the WP ReST API can be considered to be more of an API builder for individual sites than an API in and of itself. In a polymorphic world of individually-configured and customized WordPress installs, having non-templated paths that are all discovered from a root endpoint is the solution deemed most flexible and least likely to paint us into a corner.

Significant drawbacks to this approach:

• A first request is always needed: There is no way to query for a resource without first interrogating the root endpoint for location information. You can safely assume you know how things are set up in most cases, but there's no way around this added request overhead if you're requesting content from a third-party site for the first time.
• To avoid having to make a first request for all subsequent requests, the information from that request (an object defining available endpoints, from which all following requests will be derived) must be cached somehow. This is of minor concern in server-side applications, which can cache in-memory within the process, in session storage, or persistently in a database; but for client applications this data would need to be persisted in local storage or a similar client-side cache in order to avoid needing to be requested on every page load.

I find this concept appealing from the standpoint of conceptual flexibility, and in the way it forces you to confront resources very specifically as members of collections, but I still can't but think it would be extremely frustrating and limiting in implementation. I want to study more APIs and figure out if there's anything out there operating in the fashion described by @maxcutler, to evaluate the best way to work around these limitations and alleviate my concerns.

[kadamwhite]

We can take inspiration from how @adamsilverstein has handled this in WP-API/client-js

[adamsilverstein]

Wanted to note that with https://github.com/WP-API/client-js I originally built in an initial request for the Schema as part of the load process, I then store the schema model into sessionStorage to avoid repeated requests.

@westonruter added a nice enhancement (see WP-API/client-js#68) by localizing the schema data, which is pretty simple in WordPress: we grab the schema using the same endpoint (our endpoints work in PHP too!) and pass it to wp_localize_script so its available to the JavaScript. I'm working on an enhancement where the schema only gets enqueued once per client (see https://github.com/WP-API/client-js/compare/features/only-localize-schma-once)

[kadamwhite]

@adamsilverstein The approach I'm taking with this lib is that either of the following should be valid:

• Provide a set of "defaults," so that the lib can be used OOTB providing that the consumer specifies the API root endpoint (http://your-site.com/wp-json, e.g.). If the user's customized their routes this approach necessarily may generate invalid URLs; additionally the lib consumer would need to manually specify custom endpoints they have added. See Add initial support for querying custom API endpoints #144 for how this might work.
• Allow the user to provide a configuration object, or a URL to query against in order to auto-discover the API root configuration object, and derive chaining endpoint handlers for all specified routes. See Dynamically generate endpoint handlers based on schema #145 for the WIP here.

In the second case, it would be trivial to write a JS lib which consumes wordpress-rest-api and injects the schema through localization, so as to avoid the need for the ajax endpoint; however this library is explicitly designed to function in both browser and server-side environments, so any localization capabilities (or even the sort of localize-schema-once changes you describe) are out of scope for this lib.

[adamsilverstein]

@kadamwhite - Sounds good. I am moving in a similar direction with the Backbone client. I started with the assumption of a WordPress environment; now i've removed that dependency, you can load the script from anywhere.

I'm still experimenting with the best way to set up the schema when loaded remotely. Lacking localized or preset data options, probably going to require an init call with these passed thru.