From 844d5da1c13840aabe950063de8bf75e606c6c58 Mon Sep 17 00:00:00 2001 From: Richard Sill Date: Thu, 10 Jul 2025 16:57:58 +0200 Subject: [PATCH 1/4] added page for northwind api --- modules/ROOT/content-nav.adoc | 1 + modules/ROOT/pages/northwind-api.adoc | 81 +++++++++++++++++++++ modules/ROOT/pages/types/relationships.adoc | 3 +- 3 files changed, 84 insertions(+), 1 deletion(-) create mode 100644 modules/ROOT/pages/northwind-api.adoc diff --git a/modules/ROOT/content-nav.adoc b/modules/ROOT/content-nav.adoc index 751870ed..cee271c8 100644 --- a/modules/ROOT/content-nav.adoc +++ b/modules/ROOT/content-nav.adoc @@ -53,6 +53,7 @@ * *How-To* * xref:driver-configuration.adoc[] +* xref:northwind-api.adoc[] * *Products* diff --git a/modules/ROOT/pages/northwind-api.adoc b/modules/ROOT/pages/northwind-api.adoc new file mode 100644 index 00000000..eb615cea --- /dev/null +++ b/modules/ROOT/pages/northwind-api.adoc @@ -0,0 +1,81 @@ +[[northwind-api]] += Creating an API for the Northwind dataset +:description: This tutorial builds an API around the Northwind sample dataset 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 dataset. +.. 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. + +[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**: + +[source,cypher] +---- +MATCH (n) DETACH DELETE n; +---- +==== + + +== Goal + +A webshop API which connects to the Northwind dataset should be able to: + +* Create new customers +* Place orders +* Calculate prices for orders +* Filter products by supplier and category + + +== Type definitions + +First, make the nodes and relationships from xref:#_goal[] available: + +[source, graphql, indent=0] +---- +type Customer @node { + contactName: String! + orders: [Order!]! @relationship(type: "PURCHASED", direction: OUT) +} + +type Order @node { + orderID: Int! + customer: [Customer!]! @relationship(type: "PURCHASED", direction: IN) + products: [Product!]! @relationship(type: "ORDERS", direction: OUT) +} + +type Product @node { + productName: String! + category: [Category!]! @relationship(type: "PART_OF", direction: OUT) + orders: [Product!]! @relationship(type: "ORDERS", direction: IN) + supplier: [Supplier!]! @relationship(type: "SUPPLIES", direction: IN) +} + +type Category @node { + categoryName: String! + products: [Product!]! @relationship(type: "PART_OF", direction: IN) +} + +type Supplier @node { + supplierID: Int! + companyName: String! + products: [Product!]! @relationship(type: "SUPPLIES", direction: OUT) +} + +type ordersProperties @relationshipProperties { + unitPrice: Float! + quantity: Int! +} +---- + diff --git a/modules/ROOT/pages/types/relationships.adoc b/modules/ROOT/pages/types/relationships.adoc index 80b1da47..d7965558 100644 --- a/modules/ROOT/pages/types/relationships.adoc +++ b/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 `!`. From 63566b52a3292aecd039e53360a53b9fde9a7222 Mon Sep 17 00:00:00 2001 From: Richard Sill Date: Wed, 16 Jul 2025 12:20:15 +0200 Subject: [PATCH 2/4] added more examples --- modules/ROOT/pages/northwind-api.adoc | 312 ++++++++++++++++++++++++-- 1 file changed, 297 insertions(+), 15 deletions(-) diff --git a/modules/ROOT/pages/northwind-api.adoc b/modules/ROOT/pages/northwind-api.adoc index eb615cea..7434d57a 100644 --- a/modules/ROOT/pages/northwind-api.adoc +++ b/modules/ROOT/pages/northwind-api.adoc @@ -1,6 +1,6 @@ [[northwind-api]] -= Creating an API for the Northwind dataset -:description: This tutorial builds an API around the Northwind sample dataset with the Neo4j GraphQL Library. += 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. @@ -12,53 +12,64 @@ This model lends itself for a webshop API. . 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 dataset. -.. 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. - +. 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**: +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. == Goal -A webshop API which connects to the Northwind dataset should be able to: +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 -== Type definitions +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**. -First, make the nodes and relationships from xref:#_goal[] available: + +=== 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: Int! + orderID: ID! @id customer: [Customer!]! @relationship(type: "PURCHASED", direction: IN) - products: [Product!]! @relationship(type: "ORDERS", direction: OUT) + 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) + orders: [Product!]! @relationship(type: "ORDERS", direction: IN, properties: "ordersProperties") supplier: [Supplier!]! @relationship(type: "SUPPLIES", direction: IN) } @@ -68,7 +79,7 @@ type Category @node { } type Supplier @node { - supplierID: Int! + supplierID: ID! @id companyName: String! products: [Product!]! @relationship(type: "SUPPLIES", direction: OUT) } @@ -79,3 +90,274 @@ type ordersProperties @relationshipProperties { } ---- +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" + } + ] + } +} +---- \ No newline at end of file From 858b1e786de6df0f6d050f9b3865ef59bd91e705 Mon Sep 17 00:00:00 2001 From: Richard Sill Date: Wed, 16 Jul 2025 12:30:07 +0200 Subject: [PATCH 3/4] added link section --- modules/ROOT/pages/northwind-api.adoc | 9 ++++++++- 1 file changed, 8 insertions(+), 1 deletion(-) diff --git a/modules/ROOT/pages/northwind-api.adoc b/modules/ROOT/pages/northwind-api.adoc index 7434d57a..a27758a6 100644 --- a/modules/ROOT/pages/northwind-api.adoc +++ b/modules/ROOT/pages/northwind-api.adoc @@ -360,4 +360,11 @@ Result: ] } } ----- \ No newline at end of file +---- + + +== 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 \ No newline at end of file From 1d17fa0aa08ae5dd8f8e9dd618dc16efa8bf1a68 Mon Sep 17 00:00:00 2001 From: Richard Sill Date: Wed, 16 Jul 2025 12:33:24 +0200 Subject: [PATCH 4/4] comment out --- modules/ROOT/pages/northwind-api.adoc | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/modules/ROOT/pages/northwind-api.adoc b/modules/ROOT/pages/northwind-api.adoc index a27758a6..4098291b 100644 --- a/modules/ROOT/pages/northwind-api.adoc +++ b/modules/ROOT/pages/northwind-api.adoc @@ -27,8 +27,8 @@ 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. - +//. The code examples in xref:#_use_the_api[] are in JavaScript. +// Well, there are no examples yet. == Goal