Northwind API how to

modules/ROOT/content-nav.adoc

@@ -56,6 +56,7 @@
 * *How-To*
 
 * xref:driver-configuration.adoc[]
+* xref:northwind-api.adoc[]
 
 * *Products*
 

modules/ROOT/pages/northwind-api.adoc

@@ -0,0 +1,370 @@
+[[northwind-api]]
+= Creating an API for the Northwind data set
+:description: This tutorial builds an API around the Northwind sample data set with the Neo4j GraphQL Library.
+
+This tutorial uses the Neo4j GraphQL Library to build an API for the Northwind sample datset.
+
+The Northwind set includes but is not limited to data about products, suppliers, orders and customers.
+This model lends itself for a webshop API.
+
+
+== Prerequisites
+
+. Set up a new AuraDB instance.
+Refer to link:https://neo4j.com/docs/aura/getting-started/create-instance/[Creating a Neo4j Aura instance].
+. Populate the instance with the Northwind data set.
++
+[NOTE]
+====
+If you have completed the GraphQL and Aura Console getting started guide and would like to get rid of the example nodes you have created there, run the following in **Query** before populating your data base with the Northwind set:
+
+[source,cypher]
+----
+MATCH (n) DETACH DELETE n;
+----
+====
++
+.. In Aura, select **Learning**, then **Beginner** under **Getting started**.
+.. Select the **Learn the basics** tile and scroll to page 4/11 in the left side menu.
+.. Trigger the import with **Get the Northwind datset** and then **Run import** on the right hand side.
+//. The code examples in xref:#_use_the_api[] are in JavaScript.
+// Well, there are no examples yet.
+
+== Goal
+
+A webshop API which connects to the Northwind data set should be able to:
+
+* Create new customers
+* Place orders
+* Calculate prices for orders
+* Filter products by supplier and category
+
+See xref:#_use_the_api[] for example implementations.
+
+
+== Create the GraphQL Data API
+
+See xref:getting-started/graphql-aura.adoc[] for steps on how to do this.
+For the purpose of this tutorial, make sure to **Enable introspection** and **Enable field suggestions**.
+
+
+=== Type definitions
+
+Make the relevant nodes and relationships available by using these type definitions:
+
+[source, graphql, indent=0]
+----
+type Customer @node {
+    contactName: String!
+    customerID: ID! @id
+    orders: [Order!]! @relationship(type: "PURCHASED", direction: OUT)
+}
+
+type Order @node {
+    orderID: ID! @id
+    customer: [Customer!]! @relationship(type: "PURCHASED", direction: IN)
+    products: [Product!]! @relationship(type: "ORDERS", direction: OUT, properties: "ordersProperties")
+}
+
+type Product @node {
+    productName: String!
+    category: [Category!]! @relationship(type: "PART_OF", direction: OUT)
+    orders: [Product!]! @relationship(type: "ORDERS", direction: IN, properties: "ordersProperties")
+    supplier: [Supplier!]! @relationship(type: "SUPPLIES", direction: IN)
+}
+
+type Category @node {
+    categoryName: String!
+    products: [Product!]! @relationship(type: "PART_OF", direction: IN)
+}
+
+type Supplier @node {
+    supplierID: ID! @id
+    companyName: String!
+    products: [Product!]! @relationship(type: "SUPPLIES", direction: OUT)
+}
+
+type ordersProperties @relationshipProperties {
+    unitPrice: Float!
+    quantity: Int!
+}
+----
+
+Navigate to the link:https://studio.apollographql.com/sandbox/explorer[Apollo Studio] website and paste your GraphQL Data API URL to the **Sandbox** input.
+Use the cog icon and add `x-api-key` and the API key for your data API under **Shared headers** and **Save**.
+
+=== Make sure the API is working
+
+Verify that the relevant parts of the Northwind data set are accessible:
+
+[source, graphql, indent=0]
+----
+query {
+    categories {
+      categoryName
+    }
+}
+----
+
+You should see as the **Response**:
+
+[source, json, indent=0]
+----
+{
+  "data": {
+    "categories": [
+      {
+        "categoryName": "Beverages"
+      },
+      {
+        "categoryName": "Condiments"
+      },
+      {
+        "categoryName": "Confections"
+      },
+      {
+        "categoryName": "Dairy Products"
+      },
+      {
+        "categoryName": "Grains/Cereals"
+      },
+      {
+        "categoryName": "Meat/Poultry"
+      },
+      {
+        "categoryName": "Produce"
+      },
+      {
+        "categoryName": "Seafood"
+      }
+    ]
+  }
+}
+----
+
+== Use the API
+
+The following sections provide simple examples of how to use the API in a webshop scenario.
+
+
+=== Creating new customers
+
+The following mutation creates a new customer by the name of "Jane Doe":
+
+[source, graphql, indent=0]
+----
+mutation {
+  createCustomers(
+    input: [
+      {
+        contactName: "Jane Doe"
+      }
+    ]
+  ) {
+    customers {
+      contactName
+    }
+  }
+}
+----
+
+To make it generic, pipe the `contactName` from an input into the query and send the request:
+
+[source, javascript, indent=0]
+----
+// JavaScript example
+----
+
+
+=== Placing an order
+
+To place an order, create a new order node that is linked to a number of product nodes and a customer node:
+
+[source, graphql, indent=0]
+----
+mutation {
+  createOrders(
+    input: {
+      customer: {
+        connect: { where: { node: { contactName: { eq: "Jane Doe" } } } }
+      }
+      products: {
+        connect: {
+          edge: { unitPrice: 23.25, quantity: 5 }
+          where: { node: { productName: { eq: "Tofu" } } }
+        }
+      }
+    }
+  ) {
+    orders {
+      orderID
+    }
+  }
+}
+----
+
+Note that the `orderID` is modeled as a UUID and therefore differs from the order IDs on orders that were already part of the Northwind data set.
+The data model could be extended to account for that by keeping track of the order IDs in a separate system, making sure that the IDs are unique.
+
+The products, how many of each of them as well as the customer who places the order must be known.
+A shopping basket typically hands this information to the routine that is placing the order:
+
+[source, javascript, indent=0]
+----
+// JavaScript example
+----
+
+
+=== Calculate prices for orders
+
+Calculating the price of an order is achieved by accessing the `unitPrice` and `quantity` fields of the products that share the `ORDERS` relationship with the order.
+
+Retrieve an order by its ID as well as the products associated with it:
+
+[source, graphql, indent=0]
+----
+query {
+  orders(where: { orderID: { eq: "6a5572bb-41fb-4263-913c-69c678c04766"} }) {
+    products {
+      productName
+    }
+    orderID
+    productsConnection {
+      edges {
+        properties {
+          quantity
+          unitPrice
+        }
+      }
+    }
+  }
+}
+----
+
+The result looks like this:
+
+[source, json, indent=0]
+----
+{
+  "data": {
+    "orders": [
+      {
+        "products": [
+          {
+            "productName": "Tofu"
+          }
+        ],
+        "orderID": "6a5572bb-41fb-4263-913c-69c678c04766",
+        "productsConnection": {
+          "edges": [
+            {
+              "properties": {
+                "quantity": 5,
+                "unitPrice": 23.25
+              }
+            }
+          ]
+        }
+      }
+    ]
+  }
+}
+----
+
+The product of `quantity` and `unitPrice` is the total cost, which in this case is 116.25.
+
+// maybe add another JavaScript example here, that accesses the JSON response and actually calculates the amount. This could also be made generic, so that it is not reliant on the orderID used here.
+
+Note that there is no `discount` field on the `ORDERS` relationship and it is unclear how taxation works in this scenario.
+
+
+=== Filter products
+
+To filter products by category and supplier, first query for the `categoryName`s and supplier `companyName`s:
+
+[source, graphql, indent=0]
+----
+query {
+    categories {
+      categoryName
+    }
+    suppliers {
+      companyName
+    }
+}
+----
+
+Subsequent queries can now yield a filtered product list.
+For products of a certain category:
+
+[source, graphql, indent=0]
+----
+query {
+  products(where: {categoryConnection: {all: {node: {categoryName: {eq: "Produce"}}}}}) {
+    productName
+  }
+}
+----
+
+Result:
+
+[source, json, indent=0]
+----
+{
+  "data": {
+    "products": [
+      {
+        "productName": "Uncle Bob's Organic Dried Pears"
+      },
+      {
+        "productName": "Tofu"
+      },
+      {
+        "productName": "Rössle Sauerkraut"
+      },
+      {
+        "productName": "Manjimup Dried Apples"
+      },
+      {
+        "productName": "Longlife Tofu"
+      }
+    ]
+  }
+}
+----
+
+Similarly, a filter by supplier looks like this:
+
+[source, graphql, indent=0]
+----
+query {
+  products(where: {supplierConnection: {some: {node: {companyName: {eq: "New England Seafood Cannery"}}}}}) {
+    productName
+  }
+}
+----
+
+Result:
+
+[source, json, indent=0]
+----
+{
+  "data": {
+    "products": [
+      {
+        "productName": "Boston Crab Meat"
+      },
+      {
+        "productName": "Jack's New England Clam Chowder"
+      }
+    ]
+  }
+}
+----
+
+
+== Links
+
+* See xref:directives/autogeneration.adoc#type-definitions-autogeneration-id[`@id`] for more on how to handle unique identifiers with the GraphQL Library
+* See xref:directives/database-mapping.adoc#_relationshipproperties[`@relationshipProperties`] for details on relationship properties accessed with the GraphQL Library
+* See xref:filtering.adoc[] for more information about how to apply filters with the GraphQL Library

modules/ROOT/pages/types/relationships.adoc

@@ -147,6 +147,7 @@ type Person @node {
 ----
 
 `queryDirection` can have the following values:
+
 * `DIRECTED`: only directed queries can be performed on this relationship.
 * `UNDIRECTED`: only undirected queries can be performed on this relationship.
 
@@ -335,4 +336,4 @@ type Post @node {
 ----
 
 The relationship at `User.posts` is considered a "many" relationship, which means it should always be of type `NonNullListType` and `NonNullNamedType`. 
-In other words, both the array and the type inside of a "many" relationship should have a `!`.
+In other words, both the array and the type inside of a "many" relationship must have a `!`.