The goal of this prototype is to explore a self-describing and cacheable HTTP API based on GraphQL schemas and queries.
It takes advantage of the Sling GraphQL Core “any resource can be a GraphQL endpoint” feature to offer cacheable server-side queries as well as the usual client-driven queries which are useful at the development stage.
Several GraphQL schemas are available in a number of independent “API planes”, providing multiple ways to look at the Sling Resources in a modular way.
This module might not be useful.
A first approach using a Sling Filter to change the request's extension (for example) to address plane-specific servlets does not work. Those filters are executed after a Servlet is resolved to process the incoming request.
It looks like we'll need to implement API planes in the Sling Servlet Resolver module if we want them.
The simplest thing might to wrap the incoming Request in that resolver, change its extension to something like api-plane-N so that Servlets can be mounted for that extension. And keeping the original request's extension as a selector. Not as clean as a fully native API planes handling but would only require minor changes to the critical Servlet Resolver code, which is good.
For now, for prototyping, mounting servlets on the specific API planes selectors should work.
To start this, build the sibling modules with mvn clean install in the parent folder of this one and then, in this folder, run
mvn clean install exec:java
Then open http://localhost:8080 - which might require logging in at http://localhost:8080/system/console first.
TODO: explain how to access the relevant parts of the prototype, or add a redirect to the right place in the feature file.
The standard MAVEN_OPTS environment variable can be used to setup debugging, as the above does not fork and starts the application with the Maven JVM.
An API Plane exposes a Sling Resource to the API from a specific angle. The concept is similar to a geometrical plane, we're not talking flying metal tubes here.
For example, /mycontent/mydocument.N.json is a GraphQL endpoint for the “N plane” used for navigation. Any Sling Resource can be addressed with “N” as the first URL selector to address that plane, ignoring any other scripts or servlets that might be mounted on the same Resource for other purposes. Those remain active in the other API planes, when the first N selector (or another plane selector) is not used.
The GraphQL schema of such an API plane is simple and isolated from other planes. In this case the N plane schema is about navigating the content tree in terms of folders and document summaries, to discover content and generate navigation UIs. A document summary typically contains the document's title, description, and useful hypertext links, which might be generated by the sibling document-aggregator module in “summary” mode.
For this prototype we might start with:
document-aggregator moduleTo make the “important” GraphQL queries cacheable, once they are defined we save them for server-side execution, driven by URL selectors.
For example, /mycontent/myfolder.N.tree.json executes the N plane GraphQL prepared query named “tree”, using an HTTP GET request for cacheability.
Using selectors avoids having to use special paths for the stored queries, which helps provide a fully resource-oriented view with meaningful hypertext links.