You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@causeway.apache.org by da...@apache.org on 2024/01/28 19:29:37 UTC
(causeway) 02/03: CAUSEWAY-3676: updates GraphQL docs
This is an automated email from the ASF dual-hosted git repository.
danhaywood pushed a commit to branch master
in repository https://gitbox.apache.org/repos/asf/causeway.git
commit 62381f742347668ba97fcac297a68fc898743f4f
Author: danhaywood <da...@haywood-associates.co.uk>
AuthorDate: Sun Jan 28 17:18:35 2024 +0000
CAUSEWAY-3676: updates GraphQL docs
---
viewers/graphql/adoc/modules/ROOT/pages/about.adoc | 99 +++++++++++++++++++++-
.../ROOT/pages/setup-and-configuration.adoc | 71 +++++++++++-----
2 files changed, 149 insertions(+), 21 deletions(-)
diff --git a/viewers/graphql/adoc/modules/ROOT/pages/about.adoc b/viewers/graphql/adoc/modules/ROOT/pages/about.adoc
index fe1ed0099b..9679c0a8ae 100644
--- a/viewers/graphql/adoc/modules/ROOT/pages/about.adoc
+++ b/viewers/graphql/adoc/modules/ROOT/pages/about.adoc
@@ -4,10 +4,107 @@
The GraphQL viewer automatically exposes an Apache Causeway domain object model as a link:https://graphql.org/[graphql] API.
It is implemented using link:https://spring.io/projects/spring-graphql[Spring GraphQL] project, which in turn is built on top of link:https://www.graphql-java.com/[GraphQL Java].
+This also means that it automatically provides the link:https://github.com/graphql/graphiql[GraphiQL] interactive query tool.
+
+== Example
+
+How the viewer works is probably most easily explained by an example.
+The diagram below shows a simple domain footnote:[in fact, this is the domain used by the GraphQL viewer's own tests].
+
+image::test-domain.drawio.png[width=600]
+
+To list all Departments:
+
+[source,graphql]
+----
+{
+ university_dept_Departments {
+ findAllDepartments {
+ invoke { #<.>
+ name {
+ get #<.>
+ }
+ staffMembers {
+ get { #<.>
+ name {
+ get #<.>
+ }
+ _gqlv_meta {
+ id #<.>
+ logicalTypeName #<5>
+ }
+ }
+ }
+ }
+ }
+ }
+}
+----
+<.> invokes the action, returning a list of ``Department``s
+<.> gets (accesses) the `name` property of each returned `Department`
+<.> also gets (accesses) the `staffMembers` collection of each returned `Department`, returning a list of ``StaffMember``s
+<.> gets the `name` prperty for each returned `StaffMember`
+<.> returns the internal id and logicalTypeName of each `StaffMember`.
+Together, these make up the xref:refguide:applib:index/services/bookmark/Bookmark.adoc[] of the domain object.
+
+As well as accessing properties and collections and invoking (safe) actions, the GraphQL viewer also allows access to the usual supporting semantics.
+For example:
+
+[source,graphql]
+----
+{
+ university_dept_Departments {
+ findAllDepartments {
+ disabled #<.>
+ invoke {
+ name {
+ hidden #<.>
+ }
+ }
+ }
+ }
+}
+----
+<.> whether this action is disabled
+<.> whether the property of the resultant object is hidden
+
+Similarly, there are fields for:
+
+* `validate` - is the proposed action parameter valid?
+* `disable` - is the action or action parameter disabled?
+* `choices` - for an action parameter, are their choices?
+* `autoComplete` - for an action parameter, is there an auto-complete?
+* `default` - for an action parameter, is there a default value?
+
+
+=== Support for "mutating" queries
+
+According to the link:https://spec.graphql.org/June2018/#sec-Language.Operations[GraphQL specification], queries should be read-only; they must not change the state of the system.
+
+The GraphQL viewer (optionally) relaxes this rule, allowing actions to be invoked that _do_ change the state of the system, and -- indeed -- allowing properties to be modified.
+This is done through these additional fields:
+
+* `invokeIdempotent` - to invoke an action whose action semantics are idempotent
++
+As specified by xref:refguide:applib:index/annotation/Action.adoc#semantics[@Action#semantics].
+* `invokeNonIdempotent` - to invoke an action whose action semantics are non-idempotent
+* `set` - to modify a property.
+
+
+It also means that the above fields for supporting methods also apply to properties:
+
+* `validate` - is the proposed value of the property valid?
+* `disable` - is the property disabled?
+* `choices` - for a property, are their choices?
+* `autoComplete` - for a property , is there an auto-complete?
+
+
+This relaxed mode is enabled by default, but if you want read-only queries then there is a configuration property, see xref:setup-and-configuration.adoc[].
+
+IMPORTANT: GraphQL mutations are currently not yet implemented, and so there is not yet any spec-compliant way to mutate the state of the system.
== See also
As well as this viewer, Apache Causeway also provides the xref:vro::about.adoc[], which performs the same function, but using REST instead of GraphQL.
-
diff --git a/viewers/graphql/adoc/modules/ROOT/pages/setup-and-configuration.adoc b/viewers/graphql/adoc/modules/ROOT/pages/setup-and-configuration.adoc
index d9907a020b..477a880777 100644
--- a/viewers/graphql/adoc/modules/ROOT/pages/setup-and-configuration.adoc
+++ b/viewers/graphql/adoc/modules/ROOT/pages/setup-and-configuration.adoc
@@ -29,43 +29,74 @@ public class AppManifest {
== Configuration Properties
+The most important configuration property is:
+
+* xref:refguide:config:sections/causeway.viewer.graphql.adoc#causeway.viewer.graphql.api-variant[causeway.viewer.graphql.api-variant]
++
+Whether to support relaxed (but non-spec compliant) queries with mutations, or instead to expose an API that is query only.
+
+In addition:
+
+* xref:refguide:config:sections/causeway.viewer.graphql.adoc#causeway.viewer.graphql.meta-data.field-name[causeway.viewer.graphql.meta-data.field-name]
++
+Defines the field name of the "meta data" structure used to expose the id, logical type name and (for entities) the version of a domain object.
++
+The default value for this config property is "_gqlv_meta".
+
The xref:refguide:config:about.adoc[Configuration Guide] includes a xref:refguide:config:sections/causeway.viewer.graphql.adoc[section] for the GraphQL viewer.
+== SPI Services
+The GraphQL viewer defines a couple of services that are intended to act as SPI hooks for more sophisticated implementations.
+The viewer does provide default implementations.
-=== SPI
-=== Standard
+=== UserMementoProvider
-Standard configuration properties:
+The purpose of the xref:refguide:viewer:index/graphql/applib/auth/UserMementoProvider.adoc[] SPI is to obtain the xref:refguide:applib:index/services/user/UserMemento.adoc[] -- in other words the identity -- of the client executing the API.
-* xref:refguide:config:sections/causeway.viewer.graphql.adoc#causeway.viewer.graphql.authentication.fallback.username[causeway.viewer.graphql.authentication.fallback.username] and xref:refguide:config:sections/causeway.viewer.graphql.adoc#causeway.viewer.graphql.authentication.fallback.roles[causeway.viewer.graphql.authentication.fallback.roles]
-+
-Are used by the default implementation of xref:refguide:viewer:index/graphql/applib/auth/UserMementoProvider.adoc[], to provide a statically defined user as the executor of the API.
+In a production app, this would be inferred by hooking into the request execution parameters; these are provided to the service.
-* xref:refguide:config:sections/causeway.viewer.graphql.adoc#causeway.viewer.graphql.meta-data.field-name[causeway.viewer.graphql.meta-data.field-name]
-+
-Defines the field name of the "meta data" structure used to expose the id, logical type name and (for entities) the version of a domain object.
+The default (fallback) implementation simply uses a hard-coded value taken from the configuration:
+
+* xref:refguide:config:sections/causeway.viewer.graphql.adoc#causeway.viewer.graphql.authentication.fallback.username[causeway.viewer.graphql.authentication.fallback.username]
+
-The default value for this config property is "_gqlv_meta".
+The username of the client assumed to be making the GraphQL call.
-* xref:refguide:config:sections/causeway.viewer.graphql.adoc#causeway.viewer.graphql.type-mapper.local-date-format[causeway.viewer.graphql.type-mapper.local-date-format] and xref:refguide:config:sections/causeway.viewer.graphql.adoc#causeway.viewer.graphql.type-mapper.zoned-date-time-format[causeway.viewer.graphql.type-mapper.zoned-date-time-format]
+* xref:refguide:config:sections/causeway.viewer.graphql.adoc#causeway.viewer.graphql.authentication.fallback.roles[causeway.viewer.graphql.authentication.fallback.roles]
+
-GraphQL does not have a built-in date datatype, and so dates must be represented as strings.
-These configuration properties define the format of such strings.
+Corresponding roles.
+May or may not be used, depending upon the security configuration.
+(For example, if xref:security:secman:about.adoc[] is in use, then the roles are defined by SecMan itself and this config property is ignored).
+
+
+
+=== TypeMapper
+
+The purpose of the xref:refguide:viewer:index/graphql/applib/types/TypeMapper.adoc[] SPI is to provide an extension point for the marshalling of datatypes.
+
+The default implementation uses a number of configuration properties:
+
+* xref:refguide:config:sections/causeway.viewer.graphql.adoc#causeway.viewer.graphql.type-mapper.local-date-format[causeway.viewer.graphql.type-mapper.local-date-format].
+
-The defaults are:
+GraphQL does not have a built-in date datatype, and so must be represented as strings.
+This configuration property define the format of such a string for a local date.
+
-** "yyyy-MM-dd"
+The default for local dates is "yyyy-MM-dd"
+
+* xref:refguide:config:sections/causeway.viewer.graphql.adoc#causeway.viewer.graphql.type-mapper.zoned-date-time-format[causeway.viewer.graphql.type-mapper.zoned-date-time-format]
+
-for local date
-** "yyyy-MM-dd HH:mm:ss z"
+GraphQL does not have a built-in date/time datatype, and so must be represented as strings.
+This configuration property define the format of such a string for a zoned date time.
+
-for (zoned) date time.
+The default for a zoned date time is "yyyy-MM-dd HH:mm:ss z".
-+
-These are used by the default implementation of xref:refguide:viewer:index/graphql/applib/types/TypeMapper.adoc[].
+
+The default implementation does cover the most common data types, so it may not be necessary to override this implementation; but the option is there if required.
+=== SPI
+
+