Follow along as we build a GraphQL API using Apollo and Neo4j Database. We’ll show how to leverage the scale of serverless for our GraphQL API and how to take advantage of 3rd party services like Auth0 for handling authentication and authorization in our GraphQL app.

1. Fullstack GraphQL
William Lyon
@lyonwj
lyonwj.com
Austin API Summit
May 2019
bit.ly/austingraphql

2. William Lyon
Software Developer @Neo4j
● Integrations
■ GraphQL
■ Data Visualization
● Helping developers build
graph applications
@lyonwj
lyonwj.com
will@neo4j.com

3. ● GraphQL Overview
● How To Build A GraphQL API
● GraphQL Engines
○ Database integrations
● Deploying GraphQL services
● Querying GraphQL
○ React
● Authorization With GraphQL
3
Agenda

4. ● Fullstack GraphQL
4
Agenda

5. Neo4j 101

6. Graph Database
● Database management system
(DBMS)
● Property Graph data model
● Cypher query language
● Graph analytics
● Data visualization
● Developer tool for building
applications
What is Neo4j?
neo4j.com/

7. ● Knowledge graphs
● Personalized recommendations
● Master data management
● Network & IT Management
● Fraud detection
○ Anti-money laundering
● Analytics
● Identity & Access Management
● Privacy & Compliance
● Logistics & Routing
● Graph Based Search
Graph Use Cases
neo4j.com/use-cases/

8. ● Fullstack framework for building applications
8
All About GRANDstack
grandstack.io

9. What is GraphQL?
9
graphql.org
An API query language and runtime for building APIs

10. “Your Application Data Is A Graph”
-- GraphQL

11. 11
Movies, Genres,
Directors, Actors

12. 12
Movies, Genres, Directors, Actors
GraphQL Type Definitions
● Defined using GraphQL
Schema Definition
Language (SDL)

13. 13
Movies, Genres,
Directors, Actors
Introspection
● Schema can be queried
● Schema becomes API specification /
documentation
● Tools like GraphiQL / GraphQL
Playground

14. 14
Movies, Genres,
Directors, Actors
GraphQL query

15. https://blog.apollographql.com/the-anatomy-of-a-graphql-query-6dffa9e9e747
Operation name and
arguments

16. 16
Selection set

17. 17
GraphQL query
Movies, Genres,
Directors, Actors

18. 18
GraphQL query
GraphQL response
Movies, Genres,
Directors, Actors

19. 1) GraphQL is an API query language, not a database query
language.
2) Limited expressivity (no projections, no aggregations, etc).
3) While GraphQL exposes your application data as a graph, it’s
not (just) for graph databases
19
What is GraphQL?

20. ● Overfetching
○ Less data over the wire
● Underfetching
○ Single round trip
● GraphQL Specification
● “Graphs All The Way Down”
○ Relationships vs Resources
○ Unify disparate systems (microservices)
● Simplify data fetching
○ Component based data interactions
20
GraphQL Advantages

21. ● Some well understood practices from
REST don’t apply
○ HTTP status codes
○ Errors
○ Caching
● Exposing arbitrary complexity to client
○ Performance considerations
● n+1 query problem
● Query costing / rate limiting
21
GraphQL Challenges

22. Example API & How It’s
Built
22

23. Example GraphQL API
Neo4j Community Forum Trending Activity Feeds
23
community.neo4j.com

24. communityapi.neo4jlabs.com24

25. How To Build A GraphQL
Service
25

26. 26
hackernoon.com/building-trending-activity-feeds-using-graphql-and-neo4j-e62ee790238e

27. Community Graph
27

28. http://138.197.15.1:7474/browser/
user: community
password: community
28
Community Graph Demo

29. 29

30. Start With A GraphQL Schema
30
graphql.org/learn/schema/#type-language

31. Start With A GraphQL Schema
31
Type
Definitions

32. Start With A GraphQL Schema
32
API Entry Point(s)
Query & Mutation Types

33. Start With A GraphQL Schema
33
API Entry Point(s)
Query & Mutation Types
graphql.org/learn/schema/#type-language

34. ● Functions that define how to “resolve” data for GraphQL request
34
GraphQL Resolvers
graphql.org/learn/execution/#root-fields-resolvers

35. 35
Cypher Query
https://hackernoon.com/building-trending-activity-feeds-using-graphql-and-neo4j-e62ee790238e

36. 36
Resolvers

37. Apollo Server
https://www.apollographql.com/docs/apollo-server/

38. Apollo Server
38

39. Apollo Server
39

40. Apollo Server
40

41. Apollo Server
41

42. communityapi.neo4jlabs.com42

43. 1) Schema Duplication
2) Mapping / translation layer from graph ←→ (???)
3) Boilerplate code
4) n+1 query problem
Common Problems With “Standard Approach”
https://blog.grandstack.io/five-common-graphql-problems-and-how-neo4j-graphql-aims-to-solve-them-e9a8999c8d43

44. GraphQL “Engines”
44

45. ● Tools for auto-generating GraphQL schema, generating
database queries from GraphQL requests
45
GraphQL “Engines” Overview
prisma.io aws.amazon.com/appsync hasura.io graphile.org grandstack.io
Neo4j-GraphQL

46. Neo4j-GraphQL
46

47. ● GraphQL First Development
○ GraphQL schema drives the database datamodel
● Generate Cypher from GraphQL
○ Single query / single round trip to database
● Generate GraphQL CRUD API from type definitions
● Auto-generated resolvers (no boilerplate!)
● Extend GraphQL functionality with Cypher
○ @cypher schema directive
47
Goals for Neo4j-GraphQL Integration

48. 48
GraphQL First Development

49. 49
Generate Cypher From GraphQL

50. 50
Extend GraphQL w/ Cypher
grandstack.io/docs/neo4j-graphql-js.html#cypher-directive
@cypher GraphQL schema directive

51. 51
www.npmjs.com/package/neo4j-graphql-js

52. 52
neo4j-graphql-js
neo4j-graphql-js
apollo-server

53. Demo
53
GRANDstack starter
project
grandstack.io

54. GRANDstack.io
54

55. ● Declarative database integrations for
GraphQL
● GraphQL type definitions define
database model
● Provision CRUD GraphQL API
○ Auto-generated GraphQL API
○ Schema enrichments
● Generate database queries
○ auto-generated resolvers
○ reduce boilerplate
55
GraphQL ”Engines”

56. How Do GraphQL Engines Generate
Database Queries From GraphQL Requests?
resolveInfo resolver
argument
● GraphQL query AST
● GraphQL schema
● Selection set
● Variables
● ...
56

57. Deploying A GraphQL
Service

58. GraphQL Deployment
“Traditional” Approaches Serverless Options
58
● PaaS
○ Heroku, AWS Elastic
Beanstalk
● Docker container
● VPS
● ...
● AWS Lambda, Google Cloud
Functions, Azure
● Serverless Framework
○ serverless.com
● Zeit Now
○ zeit.co/now
● Netlify Functions
○ netlify.com

59. 59
neo4j-graphql-js
apollo-server
Neo4j Cloud
AWS Lambda
GCP Functions
Static CDN
GraphQL Deployment

60. https://blog.apollographql.com/deploy-a-fullstack-apollo-app-with-netlify-45a7dfd51b0b
60

61. 61

62. 62
grandstack.io

63. What’s A GRANDstack?
grandstack.io

64. The GRAND stack
● A new paradigm for building APIs
● Schema definition
● Query language for APIs
● Community of tools
graphql.org/

65. The GRAND stack
● JavaScript library for building user interfaces
○ Web, mobile (React Native), VR
● Component based
○ Reusable
○ Composable
reactjs.org/

66. The GRAND stack
● Frontend framework
integrations
● Caching
● Code generation
● Schema creation
● Mocking
● Schema stitching
● Engine
Client-side tooling Server-side tooling
● “A set of tools designed to leverage GraphQL and work together to create a
great workflow”
www.apollodata.com/

67. The GRAND stack
● Native graph database
● Flexible and intuitive property graph data model
● Cypher query language
○ Express complex traversals
● Client drivers in many languages
neo4j.com/

68. The GRAND stack

69. The GRAND stack

70. 70
grandstack.io

71. GRANDstack
71
https://github.com/grand-stack/grandstack.io/issues/1

72. GraphQL Clients
Apollo Client Alternatives
72
● Most popular
● Frontend integrations for:
○ React, Angular, vue.js,
scala.js,iOS, Android,
etc
● Relay
● urql
● graphql-request
● GraphiQL
● GraphQL Playground
● fetch
● <any http client>

73. Apollo Client (for React)
73

74. Apollo Client (for React)
74

75. Apollo Client (for React)
75

76. 76
Query GraphQL endpoint
Render our table

77. 77
<Query> component

78. 78
Handle GraphQL response
and render table

79. 79

80. Authorization In
GraphQL
80

81. Authorization In GraphQL
81

82. Lots of options…
● Authorization In Resolvers
● Business Logic / Data Access Layer
● Wrapping Resolvers
● Schema Directives
82
Authorization In GraphQL

83. Pros:
● Easy to implement
● Fast prototyping
Cons:
● No single source of truth
● Duplicated logic
83
Authorization In Resolver

84. Pros:
● Flexible request
processing
● Single implementation
Cons:
● How to handle generated
resolvers (GraphQL
engines)?
84
Auth In Business Logic / Data Access Layer
https://graphql.org/learn/authorization/

85. Pros:
● Permissions defined
together, single source for
auth rules
Cons:
● Permissions must match
resolvers
● Difficult to work with
generated resolvers
Wrapping Resolvers - GraphQL Shield
https://github.com/maticzav/graphql-shield

86. Pros:
● Declarative way to define
permissions by annotating
type definitions
● Works with generated
resolvers
GraphQL Schema Directives For Auth
Cons:
● Spreads auth rules across
the GraphQL schema

87. ● Identifier preceded by “@”, with optional arguments
● A way of extending a GraphQL schema by annotationing type
definitions.
● Custom logic defined on server
What’s a Schema Directive?
https://www.apollographql.com/docs/graphql-tools/schema-directives.html

88. How To Implement Custom Directives
https://www.apollographql.com/docs/graphql-tools/schema-directives.html#Implementing-schema-directives

89. ● Don’t need to implement our
own auth directives
● Works with JWTs
● Implements:
@isAuthenticated
@hasRole
@hasScope
● Included in neo4j-graphql.js
graphql-auth-directives npm module
https://www.npmjs.com/package/graphql-auth-directives

90. ● Can be used on Types or Fields
● User must be authenticated to access the resource
○ Request contains a valid signed JWT
@isAuthenticated
https://www.npmjs.com/package/graphql-auth-directives

91. ● Can be used on Types or Fields
● Request must contain a valid signed JWT and roles claim must
include specified role
@hasRole
https://www.npmjs.com/package/graphql-auth-directives

92. ● Can be used on Query or Mutation fields
● Request must contain a valid signed JWT and scopes claim must
include specified claim for that operation
@hasScope
https://www.npmjs.com/package/graphql-auth-directives

93. How To Use
graphql-auth-directives
With Auth0?
93

94. ● Cryptographically
signed claims
embedded in a
token
● Claims specified in
payload
Json Web Token (JWT)
jwt.io
How to add
claims?

95. Adding Claims With Auth0 Rules
https://auth0.com/docs/rules

96. ● Assign role
● Does email address
end in
@grandstack.io?
○ Yes → admin role
○ No → user role
JWTs & Auth0 Rules
https://auth0.com/docs/rules

97. Auth0 Client Code
https://auth0.com/docs/quickstart/spa/react/01-login

98. ● Apollo Client used to
interact with GraphQL
API
● Use apollo-link to add
JWT to request header
JWTs & Auth0 Apollo Client

99. ● Resolvers generated by
neo4j-graphql.js
● Enable auth
● Attach request headers
(and database driver) to
context object
Apollo Server

100. Demo
100 https://github.com/johnymontana/grand-stack-starter-auth0-demo

101. Add parameters from context object into generated Cypher query
Fine Grained Auth

102. Looking Forward
102

103. ● isAuthenticated, hasRole, hasScope are generic, can be used
with any GraphQL implementation
● What could a neo4j-graphql.js specific @auth directive do?
○ Auditing data access (createdAt, createdBy)
○ Fine grained data access (owner)
○ More complex permissions specified by the graph?
@auth directive
Let us know what you think: https://github.com/neo4j-graphql/neo4j-graphql-js/issues

104. Resources
104

105. ● JavaScript
○ Apollo Server apollographql.com
○ graphql-js graphql.org
● Java
○ GraphQL Java graphql-java.com
● Python
○ Graphene graphene-python.org
● Ruby
○ GraphQL Ruby graphql-ruby.org
105
GraphQL Implementations (Server)

106. ● Open GraphQL Medium publication
○ https://medium.com/open-graphql
● GRANDstack Starter Project
○ https://grandstack.io/
● GraphQL.org
○ https://graphql.org/
106
GraphQL Resources

107. GRANDstack.io
107

108. 108
grandstack.io/docs/neo4j-graphql-js-api.html

109. 109
blog.grandstack.io

110. 110
neo4jsandbox.com

111. Questions?
111

112. (you)-[:HAVE]->(question)<-[:ANSWERS]-(will)
112