Have you used GraphQL yet? If you haven't, you're likely to encounter the technology soon. If you have, you might have questions about how to scale your team and what best practices large and small companies are following. What principles should I be following when developing a new GraphQL API? What tooling is available to help me be more productive and spend less time writing boilerplate code? How can many teams with many apps across one company share one graph? GraphQL Conf 2019 just wrapped up in Berlin where I was fortunate to hear meet thoughtful leaders on these and other subjects related to GraphQL. So, whether you're brand new to GraphQL or have an active project using GraphQL, I'd like to share some of what I have learned so you can be productive with GraphQL and your teams - while keeping relationships at the center of our work.

1. Scaling Your Team with
GraphQL
Why relationships matter
Learnings from GraphQL Conf 2019

2. Joel Bowen
Sr. Software Engineer @ Skookum
@JoelSocialized : hello@joel.software

3. Have you heard about GraphQL?

4. Let’s talk about the spec

5. This is the specification for GraphQL, a query language and
execution engine originally created at Facebook in 2012 for
describing the capabilities and requirements of data models
for client‐server applications. The development of this open
standard started in 2015.
https://graphql.github.io/graphql-spec

6. So, what is GraphQL?

7. GraphQL is an agreement
(hint: relationship)
between the client and the server

8. GraphQL is a query language for APIs

9. GraphQL is not
a database query language

10. GraphQL doesn't
specify where or how to store your data

11. GraphQL doesn't
specify how to execute retrieval of your
data within your various services

12. Still have some questions?
Let’s refactor your mind from REST

13. GET
POST
PUT
PATCH
DELETE
QUERY
MUTATION
SUBSCRIPTION
Refactoring Your Mind From REST — Lachlan Young
https://youtu.be/xHLzguFd8Ug

14. So, what does this look like?

15. GET /projects
/projects/{id}
GET /contributors
/contributors/{id}
...
RESOURCES
REST
https://graphql.org/learn/serving-over-http/

16. GET
/graphql?query={...entities}
GraphQL
https://graphql.org/learn/serving-over-http/

17. GET
/graphql?query={...entities}
POST /graphql
{
query: {...entities}
operationName: ...
variables: { ... }
}
OPTIONAL
GraphQL
https://graphql.org/learn/serving-over-http/

18. Entities?

19. type Project {
name: String
tagline: String
contributors: [User]
}
https://graphql.org/

20. type Project {
name: String
tagline: String
contributors: [User]
}
https://graphql.org/
RELATIONSHIP!

21. {
project(name: "GraphQL") {
tagline
}
}
https://graphql.org/
REQUEST

22. {
project(name: "GraphQL") {
tagline
}
}
https://graphql.org/
REQUEST
YOU COULD ASK
FOR “NAME”, TOO!

23. {
“project”: {
“tagline”: "A query language for
APIs"
}
}
https://graphql.org/
RESPONSE

24. {
project(name: "GraphQL") {
tagline
contributors {
username
}
}
}
https://graphql.org/
REQUEST

25. {
“project”: {
“tagline”: "A query language for
APIs",
“contributors”: [
{username...},
{username...}
]
}
}
https://graphql.org/
RESPONSE

26. So, how does this help?

27. Request Waterfalls
Overfetching1
Underfetching
Type-safety
1
: https://www.arxiv-vanity.com/papers/1906.07535/

28. Documentation
Code Generation
Fast Mocking
Query Validation

29. How does this not help?

30. Caching
Rate Limiting
Authorization
Load Balancing

31. CORS
Tracing & Analytics
File Uploads
(Uploads have been proposed by Apollo, among others, but do not appear to be destined for the spec)
https://blog.apollographql.com/file-uploads-with-apollo-server-2-0-5db2f3f60675
https://github.com/graphql/graphql-spec/issues/563
https://github.com/graphql/graphql-spec/issues/349

32. Why not?

33. “This is the Unix philosophy: Write programs that do one
thing and do it well. Write programs to work together.”
- Doug McIlroy

34. “There are a lot of questions that [GraphQL] very specifically
does not answer… that’s because [these questions] were
already solved by FB in 2012”
- Dan Schafer (GraphQL Co-Creator)
GraphQL before GraphQL — Dan Schafer
https://youtu.be/gb1R-fWP1Yw

35. These are still important considerations!

36. GraphQL as a spec is “small”, and should
remain a thin layer in your stack

37. What might a GraphQL architecture look
like?

38. https://www.howtographql.com/basics/3-big-picture/
CLIENTS DATABASE

39. https://www.howtographql.com/basics/3-big-picture/
CLIENTS DATABASE

40. https://www.howtographql.com/basics/3-big-picture/
CLIENTS DATABASE
MICROSERVICE
THIRD-PARTY

41. https://www.howtographql.com/basics/3-big-picture/
CLIENTS DATABASE
MICROSERVICE
THIRD-PARTY

42. https://www.howtographql.com/basics/3-big-picture/
CLIENTS DATABASE
MICROSERVICE
THIRD-PARTY
DEFINE THE
RELATIONSHIPS

43. So, you want to build a GraphQL API
Let’s talk about principles

44. Principled GraphQL
INTEGRITY / AGILITY / OPERATIONS
https://principledgraphql.com

45. INTEGRITY
1. One Graph
Your company should have one unified graph, instead of multiple graphs created
by each team.
https://principledgraphql.com/integrity#1-one-graph

46. INTEGRITY
2. Federated Implementation
Though there is only one graph, the implementation of that graph should be
federated across multiple teams.
https://principledgraphql.com/integrity#2-federated-implementation

47. 3. Track the Schema in a Registry
There should be a single source of truth for registering and tracking the graph.
INTEGRITY
https://principledgraphql.com/integrity#3-track-the-schema-in-a-registry

48. 4. Abstract, Demand-Oriented Schema
The schema should act as an abstraction layer that provides flexibility to
consumers while hiding service implementation details.
AGILITY
https://principledgraphql.com/agility#4-abstract-demand-oriented-schema

49. 5. Use an Agile Approach to Schema Development
The schema should be built incrementally based on actual requirements and
evolve smoothly over time.
AGILITY
https://principledgraphql.com/agility#5-use-an-agile-approach-to-schema-development

50. 6. Iteratively Improve Performance
Performance management should be a continuous, data-driven process, adapting
smoothly to changing query loads and service implementations.
AGILITY
https://principledgraphql.com/agility#6-iteratively-improve-performance

51. 7. Use Graph Metadata to Empower Developers
Developers should be equipped with rich awareness of the graph throughout the
entire development process.
AGILITY
https://principledgraphql.com/agility#7-use-graph-metadata-to-empower-developers

52. 8. Access and Demand Control
Grant access to the graph on a per-client basis, and manage what and how
clients can access it.
OPERATIONS
https://principledgraphql.com/operations#8-access-and-demand-control

53. 9. Structured Logging
Capture structured logs of all graph operations and leverage them as the primary
tool for understanding graph usage.
OPERATIONS
https://principledgraphql.com/operations#9-structured-logging

54. 10. Separate the GraphQL Layer from the Service Layer
Adopt a layered architecture with data graph functionality broken into a separate
tier rather than baked into every service.
OPERATIONS
https://principledgraphql.com/operations#10-separate-the-graphql-layer-from-the-service-layer

55. The most important thing about GraphQL
is...

56. The schema.graphql
Author’s opinion

57. You will have many data stores and
services but one graph

58. How do you get schema out of your
services?

59. “Though there is only one graph, the implementation of that
graph should be federated across multiple teams.”
- Principled GraphQL: #2
https://principledgraphql.com/integrity#2-federated-implementation

60. What if I want to distribute my schema
authorship across my services?

61. This. Is. Difficult.

62. This. Is. Confusing.
Schema Stitching, Schema Federation,
GraphQL Gateway, GraphQL Modules,
Namespaces, Schema Delegation,
Schema Composition...

63. “When we distribute our GraphQL Schema across different
services... what we're saying is 'I want to use GraphQL for my
inter-service communication'”
- Marc-André Giroux (GitHub)
So You Want to Distribute Your GraphQL Schema — Marc-Andre Giroux
https://youtu.be/Vq0ajno-zgw

64. Focus on what matters: use-cases

65. Focus on what matters: use-cases
RELATIONSHIPS
FEATURES <-> DATA

66. Don’t design your schema based on your
services architecture

67. Stay client focused, consider BFF
https://philcalcado.com/2015/09/18/the_back_end_for_front_end_pattern_bff.html
https://philcalcado.com/2019/07/12/some_thoughts_graphql_bff.html

68. If you do distribute your schema, “stitch”
statically, track changes
https://principledgraphql.com/integrity#3-track-the-schema-in-a-registry
Marc-Andre Giroux: https://youtu.be/Vq0ajno-zgw?t=1102

69. But ideally, distribute your execution,
not your schema

70. So you Want to Distribute your GraphQL Schema?
Marc Andre-Giroux
30 min
https://youtu.be/Vq0ajno-zgw
Infinite Backwards Compatibility
Adam D. I. Kramer
30 min
https://youtu.be/FGCqA9PjVQk
Apollo Schema Federation
James Baxley
30 min
https://youtu.be/Uw-Z1aUQvgg

71. So, you want to use a GraphQL API
Let’s talk about tools

72. You’ve got a schema, how do you use it?

73. One option: graphql-cli
https://github.com/graphql-cli/graphql-cli

74. .graphqlconfig
https://github.com/graphql-cli/graphql-cli

75. schema.graphql
https://github.com/graphql-cli/graphql-cli

76. GraphQL
Prisma | 53,771 installs | 185,888 downloads | Free
GraphQL extension for VSCode adds syntax highlighting, validation, and language features like go
to definition, hover information and autocompletion for graphql projects. This extension also
works with queries annotated with gql tag.
https://marketplace.visualstudio.com/items?itemName=Prisma.vscode-graphql

77. https://marketplace.visualstudio.com/items?itemName=Prisma.vscode-graphql
+

78. https://marketplace.visualstudio.com/items?itemName=Prisma.vscode-graphql
+

79. graphql-voyager
CLI Plugin
https://github.com/graphql-cli/graphql-cli-voyager

80. graphql playground
$ graphql playground

81. graphiql: explorer plugin
https://github.com/onegraph/graphiql-explorer

82. graphiql: explorer plugin
https://github.com/onegraph/graphiql-explorer

83. graphql-request
Select your character client
https://github.com/chentsulin/awesome-graphql#clients
https://github.com/apollographql/apollo-client
https://relay.dev/ (React)
https://aws-amplify.github.io/docs/js/api#using-graphql-endpoints
https://github.com/prisma/graphql-request

84. Generate mock data!
One option: https://github.com/APIs-guru/graphql-faker

85. Generate docs!
Browse some options: https://github.com/chentsulin/awesome-graphql

86. Consider maximizing your benefits with a
type-safe codebase

87. “When apps are developed in a typed language like TypeScript,
Java, or Swift, type information can be propagated all the way
from service type declarations through every line of code in
the app, ensuring fullstack type correctness and instant
feedback on errors.”
- Principled GraphQL: #7
https://principledgraphql.com/agility#7-use-graph-metadata-to-empower-developers

88. Building custom GraphQL tooling for your team
Sashko Stubailo
30 min
https://youtu.be/jegQWT-Wl64
Scaling Your GraphQL Client
Matt Mahoney
30 min
https://youtu.be/Vo8nqjiKI3A
200 OK! Error Handling in GraphQL
Sasha Solomon
30 min
https://youtu.be/A5-H6MtTvqk

89. So, have you heard about GraphQL?

90. We’re gunna program like it’s 1999
Lee Byron (GraphQL Co-Creator)
30 min - Closing Keynote
https://youtu.be/ADEav6zlDjg
“The mental model for building for the web largely
hasn’t changed in the last 20 years... This year the web
turns 30, and we look back at the steady march forward
of better abstractions, better syntax, and better mental
models that brought us here.”

91. How about the relationships that brought
us here?

92. How about the relationships that will
take us there?

93. Relationships thrive when they have
shared language & shared goals

94. “Coordination between Engineers happens with GraphQL
schemas as our common language”
- Jon Wong (Coursera)
Evolving the Graph — Jon Wong
https://youtu.be/fmsDlaKTJZs

95. GraphQL is an agreement
(relationship)
between the client and the server

96. <TeamA> & <TeamB>

97. Don’t just think in terms of data graphs
think in terms of relationships

98. Thank You
@JoelSocialized : hello@joel.software