Dynamically generate endpoint handlers based on schema

[kadamwhite]

This is an alternative philosophy than the approach in #144, whereby instead of manually configuring a route, the client auto-discovers all possible endpoints and dynamically generates handlers from the route and schema data. This should be considered heavily WIP, but after discussions with @jmeas and @adamsilverstein I have a hunch that dynamically creating a handler by parsing the route definition strings will be a more future-friendly way to create a dynamic route generation method. This PR iterates on this idea with an eye towards replicating all of the internal path-specific methods (.posts().id( # ) for example) dynamically by consuming and parsing the schema data.

So far, we generate a tree representing all routes grouped under a common resource base (posts, in the selection above). We next need to walk that tree to deduce the setter methods needed to specify each level of the route.

[kadamwhite]

This shows an example of what the route definitions look like—currently, I parse out the named capture groups from the regexes and use them to construct a representation of each "level" of the tree, where a "level" is one segment of a URL between /s.

Here's what the generated tree looks like for the posts routes defined here:

"dynamic" and "level" are inferred while walking the tree; validate methods are generated based on whether a given input matches the regex defined in a named capture group. "names" represents the list of names given to the same capture group in different routes under the same root resource type; the name could (and hopefully will) be used to auto-generate chaining methods to populate that segment of the URL.

[jasonphillips]

This is an excellent idea and something I'm anxiously anticipating. I've lately been building a newer rendition of my falcor-wordpress library (which currently depends on your client) that is meant to keep in sync with the latest releases of WP-API, so I have automated tests that run against the public demo.wp-api.org endpoint. And as you've also discovered, the API's endpoints undergo continuous changes with new releases, one of the most recent being a complete restructuring of all the taxonomy term paths. So building the client's paths directly off the scheme of a specified endpoint is highly desirable.

[kadamwhite]

@jasonphillips This is ready for review. At present there is no functionality exposed to dynamically generate a handler from your own site, but this includes all the plumbing necessary to do so.

[jasonphillips]

That's great, I'll look forward to diving into this. Basically, to answer your prior question, my Falcor router was sitting atop your library as its simpler way into the Wordpress API, but just building out the kind of single-model routing logic needed by Falcor on top of that.

So, a Falcor route (here for taxonomy terms) calls my handler classes (base class expects promises from your library in each overridden case) to fetch from the API and restructure the response for Falcor's world, following deeper nested paths in same flight (ie, fetch a post and descend into its connected terms and their properties as well).

I have been setting this up to use the live demo.wp-api.org (which always has latest dev code) in my automated tests, but I realized recently that keeping pace with the moving paths of the in-development WP-API is a real challenge. I was about to start down the road you have (parsing the list of endpoints offered by a live WP-API) and then noticed that you've already done the work.

From this point I'll probably need to decided whether to keep using your library as a whole to communicate with the API or whether to just take your completed work on parsing the available REST paths / variables and use those directly. This is great though, to have someone push forward in making sense of all the available endpoints so that they can be chained and used logically.

[kadamwhite]

@jasonphillips Thanks for the comment. I haven't used Falcor, so forgive me the confusion: this is a purely JS-side compatibility layer that digests WP API response data and reformulates it into a new structure?

From this point I'll probably need to decided whether to keep using your library as a whole to communicate with the API or whether to just take your completed work on parsing the available REST paths / variables and use those directly.

I am not clear on the issue; I had thought that your code would use my library to get the data from WP, then would transform it in some fashion once responded, but I may be misinterpreting because I'm now wondering whether you mean that you were hoping to point the wordpress-rest-api client at endpoints defined in JS, not in PHP.

Any clarification would be appreciated!

[kadamwhite]

Also it's important to note that given the looming WCEU deadline, the functionality to actually bind a wp rest api client instance to an arbitrary API endpoint with arbitrary first- or third-party routes is a this-week thing, not an another-four-months thing :)

[kadamwhite]

Basic overview of this patch:

• Include the JSON response of the /wp-json in the library
• Rather than manually specifying each endpoint handler (e.g. define a PostsRequest class, then define wp.posts() factory), deduce handlers for all available endpoints from the routes in the /wp-json response object
• Handle application of parameter and filter convenience methods as mixins applied based on endpoint, not base functionality of CollectionsRequest
• Remove CollectionsRequest entirely in favor of WPRequest and mixins

[jasonphillips]

I haven't used Falcor, so forgive me the confusion: this is a purely JS-side compatibility layer that digests WP API response data and reformulates it into a new structure?

My apologies; yes Falcor would typically be run in a node.js process on the server, so that your front-end hits your Falcor instance with data requests and Falcor, in turn, fetches all the data from the third-party service (in this case, from a Wordpress REST API using your client) then restructures and returns it in one batch to front-end client.

The main advantage is the ability to express deep paths and complex sets of items to retrieve in one request, then have all those parsed out, fetched, and packaged into a single response by the node.js backend (which might be making any number of calls to the REST API in the background to fulfill those data needs, or can set a built-in cache timeout for the last time it retrieved a particular item, etc).

So it helps overcome the main drawback of REST for front-end use, which is that one would often need to make 5 or 10 requests to get all the information needed on a single page (taxonomies, recent posts, a particular full post, its children, its related items, etc). With Falcor all that can be expressed as a set of paths on a global model (postsById[15,39,55]['title','id','link'] etc) which is structured as graph data, ie. full of internal links (so recentPosts[2] actually references postsById[39], and recentPosts[2].terms.tags[0] might reference taxonomies.tags.termsBySlug['something'], etcetera). I'm using this stack with React, and I can easily decorate the data needs of components all over a page, but have them all fetched in one flight with no data repetition in the structure.

I am not clear on the issue; I had thought that your code would use my library to get the data from WP, then would transform it in some fashion once responded, but I may be misinterpreting because I'm now wondering whether you mean that you were hoping to point the wordpress-rest-api client at endpoints defined in JS, not in PHP.

Your initial assumption is correct. I was floating the question as to whether I should depend on your library or just step up and format my own completed requests to the REST server using some of the path parsing you've worked out. But I think the former is still where I'm headed. I look forward to finding some time perhaps today to try your latest code out and see where it leads me.