Skip to content

Commit a4cc094

Browse files
rsill-neo4jrsill-neo4j
committed
some changes to getting started
1 parent c11c5a0 commit a4cc094

File tree

3 files changed

+206
-29
lines changed

3 files changed

+206
-29
lines changed

‎modules/ROOT/pages/getting-started/api-creation.adoc‎

Lines changed: 161 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,161 @@
1+
= Creating a GraphQL API
2+
3+
4+
== Before you start
5+
6+
Make sure that you have:
7+
8+
* The ID, username and password for the AuraDB.
9+
* Your type definitions.
10+
* If you intend to use JWKS for authentication, the URL from your identity provider that will be used to verify JWKS tokens.
11+
12+
If you intend to use the Aura CLI, follow the guidance provided in xref:aura-graphql/aura-cli-configuration.adoc[] before proceeding.
13+
14+
15+
== Console
16+
17+
. In the Aura Console, select **Data APIs** from the left side navigation.
18+
. Use **Create API** and fill in the details in the **Create GraphQL Data API** dialog.
19+
+
20+
image::aura-graphql/create/details.png[]
21+
+
22+
[CAUTION]
23+
====
24+
If you set **Enable introspection** and **Enable field suggestions** for production systems the information they provide can be used by malicious actors to reverse-engineer your GraphQL schema and execute arbitrary operations.
25+
26+
**Enable introspection** allows you to query the schema and discover the available queries, mutations, subscriptions, types and fields in the GraphQL API.
27+
28+
**Enable field suggestions** provides suggestions that hint towards GraphQL typos.
29+
Even with just field suggestions enabled, it is possible for a malicious actor to discover your entire schema.
30+
====
31+
+
32+
. Type definitions
33+
+
34+
This is where you describe the graph database in the AuraDB that the GraphQL API will be used with.
35+
The type definitions are the same as those used with Neo4j GraphQL Library with the exception that custom resolvers cannot be used.
36+
+
37+
If you already have data in the AuraDB, a quick way to obtain type definitions is to use the https://graphql-toolbox.neo4j.io[Neo4j GraphQL Toolbox]. This facility has the ability to connect to an AuraDB, automatically create type definitions and allow GraphQL operations.
38+
+
39+
Alternatively you can write your own type definitions from first principles by following the guidance provided in xref:index.adoc[Neo4j GraphQL Library] documentation.
40+
+
41+
If you are using GraphQL Federation then make sure to select **Enable GraphQL subgraph**.
42+
+
43+
image::aura-graphql/create/type-definitions.png[]
44+
+
45+
. Cross-Origin Resource Sharing (CORS) policy
46+
+
47+
If a browser based application will be using this GraphQL API, add an entry in your Cross-Origin Resource Sharing (CORS) policy.
48+
CORS is a browser-based security mechanism that prevents web pages from accessing resources from a server with a different origin.
49+
Allow the URL that serves the browser application by adding it to the CORS policy.
50+
This includes development environments such as node.js, which serves content on your localhost or similar.
51+
This also holds for using web-based tooling for GraphQL APIs such as https://studio.apollographql.com/[Apollo Studio].
52+
+
53+
This is not needed if a non-browser-based application is using the GraphQL API as CORS does not apply to those.
54+
For example, if you are trying out GraphQL operations using cURL.
55+
+
56+
[NOTE]
57+
====
58+
The URL entered in the CORS policy must be an exact match.
59+
For example, http://localhost is not the same as http://localhost:3000/.
60+
Wildcards are not supported.
61+
====
62+
+
63+
To add a CORS policy entry, enter the exact URL, including HTTP/S and any port number, in the **Origin box**.
64+
If you need multiple entries, select **Add allowed origin**.
65+
+
66+
image::aura-graphql/create/cors-policy.png[]
67+
+
68+
. Authentication providers
69+
+
70+
All requests to the GraphQL API are authenticated and there are two options for the type of authentication: API key or JSON Web Key Set (JWKS).
71+
It is possible to use these in combination and have multiples of each.
72+
+
73+
After choosing the authentication provider from the dropdown list, enter a friendly name.
74+
This is all that is needed when using API key.
75+
The API key will be shown after the GraphQL API key has been created.
76+
If you are using JWKS, provide a friendly name and the URL from your identity provider that is used to verify JWKS tokens.
77+
+
78+
Add more more providers via **Add authentication provider**.
79+
+
80+
An authentication provider can be removed by selecting the trash icon.
81+
+
82+
image::aura-graphql/create/auth-providers.png[]
83+
+
84+
[CAUTION]
85+
====
86+
It is not recommended to use API keys with user-facing applications that are using the GraphQL API.
87+
This is due to the risk of the API key being visible to malicious users and very little control over GraphQL operations.
88+
A 3rd party identity provider with JWKS provides better security and allows for granular security rules, based on information within the JWKS token, to be defined within the type definitions to control GraphQL operations.
89+
====
90+
+
91+
. Sizing
92+
+
93+
Sizing a GraphQL API is based on the size and complexity of the type definitions and the workload that is serviced.
94+
Larger sizes have a higher hourly cost.
95+
If the cost is not displayed, refer to the agreement you have with Neo4j.
96+
+
97+
image::aura-graphql/create/sizing.png[]
98+
+
99+
. Creation
100+
+
101+
At this point the configuration is complete for the GraphQL API.
102+
Select **Create** to proceed and create the GraphQL API.
103+
Alternatively, **Cancel** the process at top right of the page.
104+
+
105+
. API key
106+
+
107+
If you chose to use an API key with the GraphQL API it is now displayed.
108+
Store this information securely as it cannot be retrieved again.
109+
Select **I understand** and then **Close** once you have done this.
110+
+
111+
image::aura-graphql/create/save-api-key.png[]
112+
+
113+
. The GraphQL API will now be provisioned.
114+
You can see the status via **Data APIs** from the left side navigation.
115+
When the status changes to "Ready", the API is ready to use.
116+
If it has a status of 'Error', use the three dots icon and **Edit** from the menu to change the configuration.
117+
118+
119+
== Aura CLI
120+
121+
Like the Console, the Aura CLI can also be used to create a GraphQL API.
122+
There is a difference: on creation, only an API Key authentication provider is created.
123+
The authentication providers can be modified using subsequent CLI commands.
124+
125+
To create a GraphQL API with the Aura CLI, proceed as follows.
126+
127+
. Find the AuraDB instance ID
128+
+
129+
From the table, locate the ID of the Aura instance that the GraphQL API will be used with.
130+
+
131+
[source, bash, indent=0]
132+
----
133+
aura-cli instance list
134+
----
135+
+
136+
. Save type definitions
137+
+
138+
To avoid having to encode type definitions into base64 format to use directly with the Aura CLI, save them in a file.
139+
+
140+
. Create
141+
+
142+
Provision the GraphQL API, replacing the values in UPPERCASE with your own:
143+
+
144+
[source, bash, indent=0]
145+
----
146+
aura-cli data-api graphql create --name YOUR_FRIENDLY_NAME --instance-id YOUR_AURA_INSTANCE_ID --instance-username YOUR_AURA_INSTANCE_USER --instance-password YOUR_AURA_INSTANCE_PASSWORD --type-definitions-file FULL_PATH_TO_YOUR_TYPE_DEFS
147+
----
148+
+
149+
The response shows information about the new GraphQL API.
150+
Make sure you note the API Key and ID.
151+
+
152+
. Check progress
153+
+
154+
To see if the GraphQL API is ready to use, run the following command:
155+
+
156+
[source, bash, indent=0]
157+
----
158+
aura-cli data-api graphql get YOUR_GRAPHQL_API_ID --instance-id YOUR_AURA_INSTANCE_ID
159+
----
160+
161+
If the status is "Ready", the API is ready to use.

‎modules/ROOT/pages/getting-started/index.adoc‎

Lines changed: 32 additions & 23 deletions
Original file line numberDiff line numberDiff line change
@@ -12,9 +12,10 @@ This tutorial shows you how to:
1212
- Start an instance of the library to generate a GraphQL schema.
1313
- Run an instance of a server to execute queries and mutations against your schema.
1414

15-
The tutorial assumes familiarity with command line and JavaScript, and also that you have a recent version of Node.js installed.
15+
The tutorial assumes familiarity with the command line and JavaScript, and also that you have a recent version of Node.js installed.
1616
The examples use the default `npm` package manager, but you can use another one of choice.
1717

18+
1819
== Create a new project
1920

2021
. Create a new directory and `cd` into it:
@@ -39,33 +40,36 @@ npm init es6 --yes
3940
touch index.js
4041
----
4142

43+
4244
== Install dependencies
4345

44-
. Install the Neo4j GraphQL Library and its dependencies:
45-
+
46-
.. `@neo4j/graphql`: the official Neo4j GraphQL Library package.
47-
It takes your GraphQL type definitions and generates a schema backed by a Neo4j database.
48-
.. `graphql`: the package used to generate a schema and execute queries and mutations.
49-
.. `neo4j-driver`: the official Neo4j Driver package for JavaScript, of which an instance must be passed into the Neo4j GraphQL Library.
46+
Install the Neo4j GraphQL Library and its dependencies with:
5047

51-
. Install a GraphQL server package to host your schema and allow the execution of queries and mutations against it.
52-
.. The https://www.apollographql.com/docs/apollo-server/[`@apollo/server`] is the default package for Apollo Server:
53-
+
5448
[source, bash, indent=0]
5549
----
5650
npm install @neo4j/graphql graphql neo4j-driver @apollo/server
5751
----
5852

59-
. Set up a https://neo4j.com[Neo4j database].
53+
- `@neo4j/graphql` is the official Neo4j GraphQL Library package.
54+
It takes your GraphQL type definitions and generates a schema backed by a Neo4j database.
55+
- `graphql` is the package used to generate a schema and execute queries and mutations.
56+
- `neo4j-driver` is the official Neo4j Driver package for JavaScript, of which an instance must be passed into the Neo4j GraphQL Library.
57+
58+
Install a GraphQL server package to host your schema and allow the execution of queries and mutations against it.
59+
The https://www.apollographql.com/docs/apollo-server/[`@apollo/server`] is the default package for Apollo Server.
60+
61+
Set up a https://neo4j.com[Neo4j database].
6062
Make sure it fulfills the xref::index.adoc#_requirements[requirements], including the necessary plugins.
63+
Populate the database, for example with the Northwind dataset, available link::https://neo4j.com/docs/getting-started/appendix/example-data/[here].
64+
6165

6266
== Set GraphQL type definitions
6367

64-
The Neo4j GraphQL Library is primarily driven by type definitions which map to the nodes and relationships in your Neo4j database.
68+
The Neo4j GraphQL Library is driven by type definitions which map to the nodes and relationships in your Neo4j database.
6569
To get started, use a simple example with two node types, one with label "Actor" and the other "Movie":
6670

67-
. Open the previously created `index.js` in your editor of choice and write your type definitions.
68-
Add all of the necessary package imports:
71+
. Open the file `index.js` from xref:#_create_a_new_project[] in your editor and write your type definitions.
72+
Add all the necessary package imports:
6973
+
7074
[source, javascript, indent=0]
7175
----
@@ -75,27 +79,29 @@ import { Neo4jGraphQL } from "@neo4j/graphql";
7579
import neo4j from "neo4j-driver";
7680
7781
const typeDefs = `#graphql
78-
type Movie @node {
79-
title: String
80-
actors: [Actor!]! @relationship(type: "ACTED_IN", direction: IN)
82+
type Product @node {
83+
productName: String
84+
category: [Category!]! @relationship(type: "PART_OF", direction: OUT)
8185
}
8286
83-
type Actor @node {
84-
name: String
85-
movies: [Movie!]! @relationship(type: "ACTED_IN", direction: OUT)
87+
type Category @node {
88+
categoryName: String
89+
products: [Product!]! @relationship(type: "PART_OF", direction: IN)
8690
}
8791
`;
8892
----
8993
+
90-
Note that these type definitions only *define* the node labels "Actor" and "Movie", and a relationship "ACTED_IN" between the two.
94+
Note that these type definitions only define the node labels "Product" and "Category", and a relationship "PART_OF" between the two.
9195
When the schema is generated, you can then execute queries for `actors` and `movies` to read data from the database.
9296

93-
. Alternatively, you can also automatically generate type definitions from an existing database by xref::introspector.adoc[introspecting the schema].
97+
. Alternatively, you automatically generate type definitions from an existing database by xref::introspector.adoc[introspecting the schema].
98+
9499

95100
== Create an instance of `Neo4jGraphQL`
96101

97102
To create an instance of the Neo4j GraphQL Library, you need a Neo4j driver to connect to your database.
98103

104+
99105
=== Using AuraDB
100106

101107
. For an AuraDB database, https://neo4j.com/cloud/platform/aura-graph-database/?ref=docs-graphql[create an instance].
@@ -104,6 +110,7 @@ To create an instance of the Neo4j GraphQL Library, you need a Neo4j driver to c
104110
+
105111
image::neo4j-aura-dashboard.png[width=500]
106112

113+
107114
=== Using a Neo4j database
108115

109116
For a database located at the default "neo4j://localhost:7687" (see more about https://neo4j.com/docs/operations-manual/current/configuration/ports[port configuration]), with the username "username" and the password "password", add the following to the bottom of your `index.js` file:
@@ -118,6 +125,7 @@ const driver = neo4j.driver(
118125
const neoSchema = new Neo4jGraphQL({ typeDefs, driver });
119126
----
120127

128+
121129
== Create an instance of `ApolloServer`
122130

123131
To create an Apollo Server instance using the generated schema, in which you can execute queries against it, add the following to the bottom of `index.js`:
@@ -135,8 +143,8 @@ const { url } = await startStandaloneServer(server, {
135143
console.log(`🚀 Server ready at ${url}`);
136144
----
137145

138-
== Start the server
139146

147+
== Start the server
140148

141149
Make sure that your `index.js` file looks like this:
142150

@@ -285,6 +293,7 @@ Since you only created one "Movie" node and one "Actor", the Response panel show
285293
}
286294
----
287295

296+
288297
== Conclusion
289298

290299
This concludes the tutorial.

‎modules/ROOT/pages/index.adoc‎

Lines changed: 13 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -8,20 +8,20 @@ The Neo4j GraphQL Library is a highly flexible, low-code, open source JavaScript
88
With Neo4j as the graph database, the GraphQL Library makes it simple for applications to have data treated as a graph natively from the frontend all the way to storage.
99
This avoids duplicate schema work and ensures flawless integration between frontend and backend developers.
1010

11+
// Modify links below
12+
1113
If you are new to Neo4j and GraphQL take a look at xref:getting-started/index.adoc[Creating a new project] and xref:getting-started/toolbox.adoc[Neo4j GraphQL Toolbox] to learn the fundamentals of the Neo4j GraphQL Library and how to create GraphQL APIs backed by a Neo4j graph database.
1214

13-
[NOTE]
14-
====
15-
The GRANDstack starter app has been deprecated.
16-
For more information, read the section on xref::deprecations.adoc[Deprecations].
17-
====
1815

1916
== How it works
2017

2118
The Neo4j GraphQL Library requires a set of type definitions that describes the shape of your graph data.
2219
It can generate an entire executable schema with all of the additional types needed to execute queries and mutations to interact with your Neo4j database.
2320

24-
For every query and mutation that is executed against this generated schema, the Neo4j GraphQL Library generates a single Cypher query which is executed against the database. This eliminates the https://www.google.com/search?q=graphql+n%2B1[N+1 Problem], which can make GraphQL implementations slow and inefficient.
21+
For every query and mutation that is executed against this generated schema, the Neo4j GraphQL Library generates a single Cypher query which is executed against the database.
22+
This eliminates the https://www.google.com/search?q=graphql+n%2B1[N+1 Problem], which can make GraphQL implementations slow and inefficient.
23+
24+
The Neo4j GraphQL Library features:
2525

2626
- Automatic generation of xref::queries-aggregations/queries.adoc[Queries] and xref::mutations/index.adoc[Mutations] for CRUD interactions.
2727
- xref::/types/index.adoc[Types], including temporal and spatial.
@@ -36,19 +36,23 @@ For every query and mutation that is executed against this generated schema, the
3636

3737
== Interaction
3838

39+
// Modify link below and add info about aura graphql
40+
3941
In the xref::getting-started/index.adoc[Getting Started] guide, Apollo Server is used to host the GraphQL schema, so you can interact directly with your API with no frontend.
4042
In case you prefer to use frontend frameworks, these are some clients that interact with GraphQL APIs:
4143

4244
- https://reactjs.org/[React] - support through https://www.apollographql.com/docs/react/[Apollo Client]
4345
- https://vuejs.org/[Vue.js] - support through https://apollo.vuejs.org/[Vue Apollo]
4446
- https://angularjs.org/[AngularJS] - support through https://apollo-angular.com/docs/[Apollo Angular].
4547

48+
4649
== Deployment
4750

4851
There are a variety of methods for deploying GraphQL APIs.
4952
In the xref::getting-started/index.adoc[Getting Started] guide, Apollo Server is being used for demonstration.
5053
You can check their own documentation about https://www.apollographql.com/docs/apollo-server/deployment[Deployment] for more details.
5154

55+
5256
== Versioning
5357

5458
The Neo4j GraphQL Library uses https://semver.org/[Semantic Versioning].
@@ -66,17 +70,20 @@ Additionally, prerelease version numbers may have additional suffixes, for examp
6670

6771
`NUMBER` in the suffix is simply an incrementing release number in each phase.
6872

73+
6974
== Requirements
7075

7176
. https://neo4j.com/deployment-center/#gdb-selfmanaged[Neo4j Database] or https://neo4j.com/product/auradb/[Neo4j AuraDB] version 5.x with APOC core plugin. Note that with version 5.15 or higher you are using using the xref:/directives/indexes-and-constraints.adoc#_vector_index_search[`@vector` directive].
7277
. https://nodejs.org/en/[Node.js] 20+.
7378

79+
7480
== Resources
7581

7682
. https://github.com/neo4j/graphql[GitHub]
7783
. https://github.com/neo4j/graphql/issues[Issue Tracker]
7884
. https://www.npmjs.com/package/@neo4j/graphql[npm package]
7985

86+
8087
== License
8188

8289
ifndef::backend-pdf[]

0 commit comments

Comments
 (0)