You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@sling.apache.org by bd...@apache.org on 2020/09/09 08:00:02 UTC
[sling-org-apache-sling-graphql-core] branch master updated: Moving
caching section to the end
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-org-apache-sling-graphql-core.git
The following commit(s) were added to refs/heads/master by this push:
new 6b73eb1 Moving caching section to the end
6b73eb1 is described below
commit 6b73eb1ea66622a8ce44043b823f7e269a45e15a
Author: Bertrand Delacretaz <bd...@apache.org>
AuthorDate: Wed Sep 9 09:59:53 2020 +0200
Moving caching section to the end
---
README.md | 190 ++++++++++++++++++++++++++++++++------------------------------
1 file changed, 98 insertions(+), 92 deletions(-)
diff --git a/README.md b/README.md
index 6a7587b..f2cad73 100644
--- a/README.md
+++ b/README.md
@@ -37,12 +37,106 @@ This module enables the following GraphQL "styles"
The GraphQL requests hit a Sling resource in all cases, there's no need for path-mounted servlets which are [not desirable](https://sling.apache.org/documentation/the-sling-engine/servlets.html#caveats-when-binding-servlets-by-path-1).
-### Persisted queries API
+See also the _caching_ section later in this file.
+
+## Resource-specific GraphQL schemas
+
+Schemas are provided by `SchemaProvider` services:
+
+ public interface SchemaProvider {
+
+ /** Get a GraphQL Schema definition for the given resource and optional selectors
+ *
+ * @param r The Resource to which the schema applies
+ * @param selectors Optional set of Request Selectors that can influence the schema selection
+ * @return a GraphQL schema that can be annotated to define the data fetchers to use, see
+ * this module's documentation. Can return null if a schema cannot be provided, in which
+ * case a different provider should be used.
+ */
+ @Nullable
+ String getSchema(@NotNull Resource r, @Nullable String [] selectors) throws IOException;
+ }
+
+The default provider makes an internal Sling request with for the current Resource with a `.GQLschema` extension.
+
+This allows the Sling script/servlet resolution mechanism and its script engines to be used to generate
+schemas dynamically, taking request selectors into account.
+
+Unless you have specific needs not covered by this mechanism, there's no need to implement your
+own `SchemaProvider` services.
+
+## SlingDataFetcher selection with Schema Directives
+
+The GraphQL schemas used by this module can be enhanced using
+[schema directives](http://spec.graphql.org/June2018/#sec-Language.Directives)
+(see also the [Apollo docs](https://www.apollographql.com/docs/graphql-tools/schema-directives/) for how those work)
+that select specific `SlingDataFetcher` services to return the appropriate data.
+
+A default data fetcher is used for types and fields which have no such directive.
+
+Here's a simple example, the test code has more:
+
+ # This directive maps fields to our Sling data fetchers
+ directive @fetcher(
+ name : String,
+ options : String = "",
+ source : String = ""
+ ) on FIELD_DEFINITION
+
+ type Query {
+ withTestingSelector : TestData @fetcher(name:"test/pipe")
+ }
+
+ type TestData {
+ farenheit: Int @fetcher(name:"test/pipe" options:"farenheit")
+ }
+
+The names of those `SlingDataFetcher` services are in the form
+
+ <namespace>/<name>
+
+The `sling/` namespace is reserved for `SlingDataFetcher` services
+which hava Java package names that start with `org.apache.sling`.
+
+The `<options>` and `<source>` arguments of the directive can be used by the
+`SlingDataFetcher` services to influence their behavior.
+
+### Scripted SlingDataFetchers
+
+Besides Java, `SlingDataFetcher` scripts can be written in any scripting language that supported by the Sling instance's configuration.
+
+Here's an example from the test code.
+
+The schema contains the following statement:
+
+ scriptedFetcher (testing : String) : Test @fetcher(name:"scripted/example")
+
+And here's the data fetcher code:
+
+ var result = {
+ boolValue: true,
+ resourcePath: "From the test script: " + resource.path,
+ testingArgument: environment.getArgument("testing"),
+ anotherValue: 450 + 1
+ };
+
+ result;
+
+The data fetcher provider then looks for a script that handles the `graphql/fetchers/scripted/example` resource type with a `fetcher`script name. `graphql/fetchers`is a prefix (hardcoded for now) and `scripted/example` comes from the above schema's `@fetcher` directive.
+
+In that test, the `/graphql/fetchers/scripted/example/fetcher.js` shown above resolves with those requirements, it is executed to retrieve the requested data. That execution happens with a context consisting of the current `SlingDataFetcherEnvironment` under the `environment` key, and the current Sling Resource under the `resource` key, both used in this test script.
+
+## Caching: Persisted queries API
+
No matter how you decide to create your Sling GraphQL endpoints, you have the option to allow GraphQL clients to use persisted queries.
-Since most user agents have a character limit for GET requests and POST requests are not cacheable, a persisted query allows the best of
-both worlds.
-#### How does it work?
+After preparing a query with a POST request, it can be executed with a GET request that can be cached by HTTP caches or a CDN.
+
+This is required as POST queries are usually not cached, and if using GET with the query as a parameter there's a concrete risk of
+the parameter becoming too large for HTTP services and intermediates.
+
+### How to use persisted queries?
+
1. An instance of the GraphQL servlet has to be configured; by default, the servlet will enable the persisted queries API on the
`/persisted` request suffix; the value is configurable, via the `persistedQueries.suffix` parameter of the factory configuration.
2. A client prepares a persisted query in advance by `POST`ing the query text to the endpoint where the GraphQL servlet is bound, plus the
@@ -129,92 +223,4 @@ curl -v http://localhost:8080/graphql.json/persisted/e1ce2e205e1dfb3969627c6f417
}
}
```
-
-
-## Resource-specific GraphQL schemas
-
-Schemas are provided by `SchemaProvider` services:
-
- public interface SchemaProvider {
-
- /** Get a GraphQL Schema definition for the given resource and optional selectors
- *
- * @param r The Resource to which the schema applies
- * @param selectors Optional set of Request Selectors that can influence the schema selection
- * @return a GraphQL schema that can be annotated to define the data fetchers to use, see
- * this module's documentation. Can return null if a schema cannot be provided, in which
- * case a different provider should be used.
- */
- @Nullable
- String getSchema(@NotNull Resource r, @Nullable String [] selectors) throws IOException;
- }
-
-The default provider makes an internal Sling request with for the current Resource with a `.GQLschema` extension.
-
-This allows the Sling script/servlet resolution mechanism and its script engines to be used to generate
-schemas dynamically, taking request selectors into account.
-
-Unless you have specific needs not covered by this mechanism, there's no need to implement your
-own `SchemaProvider` services.
-
-## SlingDataFetcher selection with Schema Directives
-
-The GraphQL schemas used by this module can be enhanced using
-[schema directives](http://spec.graphql.org/June2018/#sec-Language.Directives)
-(see also the [Apollo docs](https://www.apollographql.com/docs/graphql-tools/schema-directives/) for how those work)
-that select specific `SlingDataFetcher` services to return the appropriate data.
-
-A default data fetcher is used for types and fields which have no such directive.
-
-Here's a simple example, the test code has more:
-
- # This directive maps fields to our Sling data fetchers
- directive @fetcher(
- name : String,
- options : String = "",
- source : String = ""
- ) on FIELD_DEFINITION
-
- type Query {
- withTestingSelector : TestData @fetcher(name:"test/pipe")
- }
-
- type TestData {
- farenheit: Int @fetcher(name:"test/pipe" options:"farenheit")
- }
-
-The names of those `SlingDataFetcher` services are in the form
-
- <namespace>/<name>
-
-The `sling/` namespace is reserved for `SlingDataFetcher` services
-which hava Java package names that start with `org.apache.sling`.
-
-The `<options>` and `<source>` arguments of the directive can be used by the
-`SlingDataFetcher` services to influence their behavior.
-
-### Scripted SlingDataFetchers
-
-Besides Java, `SlingDataFetcher` scripts can be written in any scripting language that supported by the Sling instance's configuration.
-
-Here's an example from the test code.
-
-The schema contains the following statement:
-
- scriptedFetcher (testing : String) : Test @fetcher(name:"scripted/example")
-
-And here's the data fetcher code:
-
- var result = {
- boolValue: true,
- resourcePath: "From the test script: " + resource.path,
- testingArgument: environment.getArgument("testing"),
- anotherValue: 450 + 1
- };
-
- result;
-
-The data fetcher provider then looks for a script that handles the `graphql/fetchers/scripted/example` resource type with a `fetcher`script name. `graphql/fetchers`is a prefix (hardcoded for now) and `scripted/example` comes from the above schema's `@fetcher` directive.
-
-In that test, the `/graphql/fetchers/scripted/example/fetcher.js` shown above resolves with those requirements, it is executed to retrieve the requested data. That execution happens with a context consisting of the current `SlingDataFetcherEnvironment` under the `environment` key, and the current Sling Resource under the `resource` key, both used in this test script.