[sling-whiteboard] branch master updated: API planes prototype, just the spec for now

[bd...@apache.org]

This is an automated email from the ASF dual-hosted git repository.

bdelacretaz pushed a commit to branch master
in repository https://gitbox.apache.org/repos/asf/sling-whiteboard.git


The following commit(s) were added to refs/heads/master by this push:
     new 1827ed8  API planes prototype, just the spec for now
1827ed8 is described below

commit 1827ed8773a613ef203f68e67848d5cd77e2766d
Author: Bertrand Delacretaz <bd...@apache.org>
AuthorDate: Thu Jun 3 15:31:37 2021 +0200

    API planes prototype, just the spec for now
---
 remote-content-api/api-planes-prototype/README.md | 45 +++++++++++++++++++++++
 1 file changed, 45 insertions(+)

diff --git a/remote-content-api/api-planes-prototype/README.md b/remote-content-api/api-planes-prototype/README.md
new file mode 100644
index 0000000..afdbd06
--- /dev/null
+++ b/remote-content-api/api-planes-prototype/README.md
@@ -0,0 +1,45 @@
+API Planes prototype
+---
+
+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.
+
+## API Planes
+
+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:
+ * The N plane to navigate in folder and document summaries
+ * The D plane for document details, generated using the sibling `document-aggregator` module
+ * Maybe a C plane for commands, similar to the "repoinit" command example from the sibling [sample GraphQL API](../sample-graphql-api/) module.
+
+## Selector-driven prepared queries
+
+To 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.
\ No newline at end of file