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 <[email protected]>
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
