Skip to content

Commit 63566b5

Browse files
rsill-neo4jrsill-neo4j
committed
added more examples
1 parent b1c032d commit 63566b5

File tree

1 file changed

+297
-15
lines changed

1 file changed

+297
-15
lines changed

‎modules/ROOT/pages/northwind-api.adoc‎

Lines changed: 297 additions & 15 deletions
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,6 @@
11
[[northwind-api]]
2-
= Creating an API for the Northwind dataset
3-
:description: This tutorial builds an API around the Northwind sample dataset with the Neo4j GraphQL Library.
2+
= Creating an API for the Northwind data set
3+
:description: This tutorial builds an API around the Northwind sample data set with the Neo4j GraphQL Library.
44

55
This tutorial uses the Neo4j GraphQL Library to build an API for the Northwind sample datset.
66

@@ -12,53 +12,64 @@ This model lends itself for a webshop API.
1212

1313
. Set up a new AuraDB instance.
1414
Refer to link:https://neo4j.com/docs/aura/getting-started/create-instance/[Creating a Neo4j Aura instance].
15-
. Populate the instance with the Northwind dataset.
16-
.. In Aura, select **Learning**, then **Beginner** under **Getting started**.
17-
.. Select the **Learn the basics** tile and scroll to page 4/11 in the left side menu.
18-
.. Trigger the import with **Get the Northwind datset** and then **Run import** on the right hand side.
19-
15+
. Populate the instance with the Northwind data set.
16+
+
2017
[NOTE]
2118
====
22-
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**:
19+
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:
2320
2421
[source,cypher]
2522
----
2623
MATCH (n) DETACH DELETE n;
2724
----
2825
====
26+
+
27+
.. In Aura, select **Learning**, then **Beginner** under **Getting started**.
28+
.. Select the **Learn the basics** tile and scroll to page 4/11 in the left side menu.
29+
.. Trigger the import with **Get the Northwind datset** and then **Run import** on the right hand side.
30+
. The code examples in xref:#_use_the_api[] are in JavaScript.
2931

3032

3133
== Goal
3234

33-
A webshop API which connects to the Northwind dataset should be able to:
35+
A webshop API which connects to the Northwind data set should be able to:
3436

3537
* Create new customers
3638
* Place orders
3739
* Calculate prices for orders
3840
* Filter products by supplier and category
3941

42+
See xref:#_use_the_api[] for example implementations.
43+
44+
45+
== Create the GraphQL Data API
4046

41-
== Type definitions
47+
See xref:getting-started/graphql-aura.adoc[] for steps on how to do this.
48+
For the purpose of this tutorial, make sure to **Enable introspection** and **Enable field suggestions**.
4249

43-
First, make the nodes and relationships from xref:#_goal[] available:
50+
51+
=== Type definitions
52+
53+
Make the relevant nodes and relationships available by using these type definitions:
4454

4555
[source, graphql, indent=0]
4656
----
4757
type Customer @node {
4858
contactName: String!
59+
customerID: ID! @id
4960
orders: [Order!]! @relationship(type: "PURCHASED", direction: OUT)
5061
}
5162
5263
type Order @node {
53-
orderID: Int!
64+
orderID: ID! @id
5465
customer: [Customer!]! @relationship(type: "PURCHASED", direction: IN)
55-
products: [Product!]! @relationship(type: "ORDERS", direction: OUT)
66+
products: [Product!]! @relationship(type: "ORDERS", direction: OUT, properties: "ordersProperties")
5667
}
5768
5869
type Product @node {
5970
productName: String!
6071
category: [Category!]! @relationship(type: "PART_OF", direction: OUT)
61-
orders: [Product!]! @relationship(type: "ORDERS", direction: IN)
72+
orders: [Product!]! @relationship(type: "ORDERS", direction: IN, properties: "ordersProperties")
6273
supplier: [Supplier!]! @relationship(type: "SUPPLIES", direction: IN)
6374
}
6475
@@ -68,7 +79,7 @@ type Category @node {
6879
}
6980
7081
type Supplier @node {
71-
supplierID: Int!
82+
supplierID: ID! @id
7283
companyName: String!
7384
products: [Product!]! @relationship(type: "SUPPLIES", direction: OUT)
7485
}
@@ -79,3 +90,274 @@ type ordersProperties @relationshipProperties {
7990
}
8091
----
8192

93+
Navigate to the link:https://studio.apollographql.com/sandbox/explorer[Apollo Studio] website and paste your GraphQL Data API URL to the **Sandbox** input.
94+
Use the cog icon and add `x-api-key` and the API key for your data API under **Shared headers** and **Save**.
95+
96+
=== Make sure the API is working
97+
98+
Verify that the relevant parts of the Northwind data set are accessible:
99+
100+
[source, graphql, indent=0]
101+
----
102+
query {
103+
categories {
104+
categoryName
105+
}
106+
}
107+
----
108+
109+
You should see as the **Response**:
110+
111+
[source, json, indent=0]
112+
----
113+
{
114+
"data": {
115+
"categories": [
116+
{
117+
"categoryName": "Beverages"
118+
},
119+
{
120+
"categoryName": "Condiments"
121+
},
122+
{
123+
"categoryName": "Confections"
124+
},
125+
{
126+
"categoryName": "Dairy Products"
127+
},
128+
{
129+
"categoryName": "Grains/Cereals"
130+
},
131+
{
132+
"categoryName": "Meat/Poultry"
133+
},
134+
{
135+
"categoryName": "Produce"
136+
},
137+
{
138+
"categoryName": "Seafood"
139+
}
140+
]
141+
}
142+
}
143+
----
144+
145+
== Use the API
146+
147+
The following sections provide simple examples of how to use the API in a webshop scenario.
148+
149+
150+
=== Creating new customers
151+
152+
The following mutation creates a new customer by the name of "Jane Doe":
153+
154+
[source, graphql, indent=0]
155+
----
156+
mutation {
157+
createCustomers(
158+
input: [
159+
{
160+
contactName: "Jane Doe"
161+
}
162+
]
163+
) {
164+
customers {
165+
contactName
166+
}
167+
}
168+
}
169+
----
170+
171+
To make it generic, pipe the `contactName` from an input into the query and send the request:
172+
173+
[source, javascript, indent=0]
174+
----
175+
// JavaScript example
176+
----
177+
178+
179+
=== Placing an order
180+
181+
To place an order, create a new order node that is linked to a number of product nodes and a customer node:
182+
183+
[source, graphql, indent=0]
184+
----
185+
mutation {
186+
createOrders(
187+
input: {
188+
customer: {
189+
connect: { where: { node: { contactName: { eq: "Jane Doe" } } } }
190+
}
191+
products: {
192+
connect: {
193+
edge: { unitPrice: 23.25, quantity: 5 }
194+
where: { node: { productName: { eq: "Tofu" } } }
195+
}
196+
}
197+
}
198+
) {
199+
orders {
200+
orderID
201+
}
202+
}
203+
}
204+
----
205+
206+
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.
207+
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.
208+
209+
The products, how many of each of them as well as the customer who places the order must be known.
210+
A shopping basket typically hands this information to the routine that is placing the order:
211+
212+
[source, javascript, indent=0]
213+
----
214+
// JavaScript example
215+
----
216+
217+
218+
=== Calculate prices for orders
219+
220+
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.
221+
222+
Retrieve an order by its ID as well as the products associated with it:
223+
224+
[source, graphql, indent=0]
225+
----
226+
query {
227+
orders(where: { orderID: { eq: "6a5572bb-41fb-4263-913c-69c678c04766"} }) {
228+
products {
229+
productName
230+
}
231+
orderID
232+
productsConnection {
233+
edges {
234+
properties {
235+
quantity
236+
unitPrice
237+
}
238+
}
239+
}
240+
}
241+
}
242+
----
243+
244+
The result looks like this:
245+
246+
[source, json, indent=0]
247+
----
248+
{
249+
"data": {
250+
"orders": [
251+
{
252+
"products": [
253+
{
254+
"productName": "Tofu"
255+
}
256+
],
257+
"orderID": "6a5572bb-41fb-4263-913c-69c678c04766",
258+
"productsConnection": {
259+
"edges": [
260+
{
261+
"properties": {
262+
"quantity": 5,
263+
"unitPrice": 23.25
264+
}
265+
}
266+
]
267+
}
268+
}
269+
]
270+
}
271+
}
272+
----
273+
274+
The product of `quantity` and `unitPrice` is the total cost, which in this case is 116.25.
275+
276+
// 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.
277+
278+
Note that there is no `discount` field on the `ORDERS` relationship and it is unclear how taxation works in this scenario.
279+
280+
281+
=== Filter products
282+
283+
To filter products by category and supplier, first query for the `categoryName`s and supplier `companyName`s:
284+
285+
[source, graphql, indent=0]
286+
----
287+
query {
288+
categories {
289+
categoryName
290+
}
291+
suppliers {
292+
companyName
293+
}
294+
}
295+
----
296+
297+
Subsequent queries can now yield a filtered product list.
298+
For products of a certain category:
299+
300+
[source, graphql, indent=0]
301+
----
302+
query {
303+
products(where: {categoryConnection: {all: {node: {categoryName: {eq: "Produce"}}}}}) {
304+
productName
305+
}
306+
}
307+
----
308+
309+
Result:
310+
311+
[source, json, indent=0]
312+
----
313+
{
314+
"data": {
315+
"products": [
316+
{
317+
"productName": "Uncle Bob's Organic Dried Pears"
318+
},
319+
{
320+
"productName": "Tofu"
321+
},
322+
{
323+
"productName": "Rössle Sauerkraut"
324+
},
325+
{
326+
"productName": "Manjimup Dried Apples"
327+
},
328+
{
329+
"productName": "Longlife Tofu"
330+
}
331+
]
332+
}
333+
}
334+
----
335+
336+
Similarly, a filter by supplier looks like this:
337+
338+
[source, graphql, indent=0]
339+
----
340+
query {
341+
products(where: {supplierConnection: {some: {node: {companyName: {eq: "New England Seafood Cannery"}}}}}) {
342+
productName
343+
}
344+
}
345+
----
346+
347+
Result:
348+
349+
[source, json, indent=0]
350+
----
351+
{
352+
"data": {
353+
"products": [
354+
{
355+
"productName": "Boston Crab Meat"
356+
},
357+
{
358+
"productName": "Jack's New England Clam Chowder"
359+
}
360+
]
361+
}
362+
}
363+
----

0 commit comments

Comments
 (0)