This is an automated email from the ASF dual-hosted git repository.
shuber pushed a commit to branch master
in repository https://gitbox.apache.org/repos/asf/unomi.git
The following commit(s) were added to refs/heads/master by this push:
new 110286ad7 UNOMI-576 : Create documentation for GraphQL schema usage
(#653)
110286ad7 is described below
commit 110286ad74ecaec927f3b61c54140d852dfbd4fe
Author: Pavel Milkevich <[email protected]>
AuthorDate: Thu Feb 15 10:20:23 2024 +0100
UNOMI-576 : Create documentation for GraphQL schema usage (#653)
---
manual/src/main/asciidoc/graphql-examples.adoc | 253 +++++++++++++++++++++++++
manual/src/main/asciidoc/index.adoc | 2 +
2 files changed, 255 insertions(+)
diff --git a/manual/src/main/asciidoc/graphql-examples.adoc
b/manual/src/main/asciidoc/graphql-examples.adoc
new file mode 100644
index 000000000..b4602288e
--- /dev/null
+++ b/manual/src/main/asciidoc/graphql-examples.adoc
@@ -0,0 +1,253 @@
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+// http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+//
+=== Graphql request examples
+
+You can use embedded GraphiQL interface available at
http://localhost:8181/graphql-ui or use any other GraphQL client using that url
for requests.
+
+==== Retrieving your first profile
+
+Profile can be retrieved using `getProfile` query
+
+[source,graphql]
+----
+query($profileID: CDP_ProfileIDInput!, $createIfMissing: Boolean) {
+ cdp {
+ getProfile(profileID: $profileID, createIfMissing: $createIfMissing) {
+ firstName
+ lastName
+ gender
+ cdp_profileIDs {
+ client {
+ ID
+ title
+ }
+ id
+ }
+ }
+ }
+}
+----
+
+This query accepts two variables that need to be provided in the `Query
variables` section:
+
+[source,json]
+----
+{
+ "profileID": {
+ "client":{
+ "id": "defaultClientId"
+ },
+ "id": 1001
+ },
+ "createIfMissing": true
+}
+----
+
+NOTE: If you don't want profile to be created if missing, set
`createIfMissing` to `false`.
+
+The response will look like this:
+
+[source,json]
+----
+{
+ "data": {
+ "cdp": {
+ "getProfile": {
+ "firstName": null,
+ "lastName": null,
+ "gender": null,
+ "cdp_profileIDs": [
+ {
+ "client": {
+ "ID": "defaultClientId",
+ "title": "Default Client"
+ },
+ "id": "1001"
+ }
+ ]
+ }
+ }
+ }
+}
+----
+
+==== Updating profile
+
+Now let's update our profile with some data.
+It can be done using `processEvents` mutation:
+
+[source,graphql]
+----
+mutation($events: [CDP_EventInput]!) {
+ cdp {
+ processEvents(events: $events)
+ }
+}
+----
+
+This mutation accepts one variable that needs to be provided in the `Query
variables` section:
+
+[source,json]
+----
+{
+ "events": [
+ {
+ "cdp_objectID": 1001,
+ "cdp_profileID": {
+ "client": {
+ "id": "defaultClientId"
+ },
+ "id": 1001
+ },
+ "cdp_profileUpdateEvent": {
+ "firstName": "John",
+ "lastName": "Doe",
+ "gender": "Male"
+ }
+ }
+ ]
+}
+----
+
+The response will have the number of processed events:
+
+[source,json]
+----
+{
+ "data": {
+ "cdp": {
+ "processEvents": 1
+ }
+ }
+}
+----
+
+NOTE: `processEvents` accepts a number of other event types that are listed on
`CDP_EventInput` type.
+
+If you run the `getProfile` query again, you will see that the profile has
been updated.
+
+==== Restricted methods
+
+Some methods are restricted to authenticated users only.
+One example is `findProfiles` query:
+
+[source,graphql]
+----
+query {
+ cdp {
+ findProfiles {
+ totalCount
+ edges {
+ node {
+ cdp_profileIDs {
+ client{
+ title
+ ID
+ }
+ id
+ }
+ }
+ }
+ }
+ }
+}
+----
+
+And if you run it now, you will get an error.
+
+To make this query work you need to supply authorization token in the `HTTP
headers` section:
+
+[source,json]
+----
+{
+ "authorization": "Basic a2FyYWY6a2FyYWY="
+}
+----
+
+The above header adds `Basic` authorization scheme with base64 encoded
`karaf:karaf` value to the request.
+
+The result will now show the list of profiles:
+
+[source,json]
+----
+{
+ "data": {
+ "cdp": {
+ "findProfiles": {
+ "totalCount": 1,
+ "edges": [
+ {
+ "node": {
+ "cdp_profileIDs": [
+ {
+ "client": {
+ "title": "Default Client",
+ "ID": "defaultClientId"
+ },
+ "id": "1001"
+ }
+ ]
+ }
+ }
+ ]
+ }
+ }
+ }
+}
+----
+
+==== Deleting profile
+
+Profile can be deleted using `deleteProfile` mutation:
+
+[source,graphql]
+----
+mutation($profileID: CDP_ProfileIDInput!) {
+ cdp {
+ deleteProfile(profileID: $profileID)
+ }
+}
+----
+
+This mutation accepts one variable that needs to be provided in the `Query
variables` section:
+
+[source,json]
+----
+{
+ "profileID": {
+ "client":{
+ "id": "defaultClientId"
+ },
+ "id": 1001
+ }
+}
+----
+
+The response will show the result of the operation:
+
+[source,json]
+----
+{
+ "data": {
+ "cdp": {
+ "deleteProfile": true
+ }
+ }
+}
+----
+
+==== Where to go from here
+
+* You can find more <<Useful Apache Unomi URLs,useful Apache Unomi URLs>> that
can be used in the same way as the above examples.
+* Read https://graphql.org/learn/[GraphQL documentation] to learn more about
GraphQL syntax.
diff --git a/manual/src/main/asciidoc/index.adoc
b/manual/src/main/asciidoc/index.adoc
index f8bdab770..616712320 100644
--- a/manual/src/main/asciidoc/index.adoc
+++ b/manual/src/main/asciidoc/index.adoc
@@ -54,6 +54,8 @@ include::jsonSchema/json-schema.adoc[]
include::graphql.adoc[]
+include::graphql-examples.adoc[]
+
== Migrations
include::migrations/migrations.adoc[]
