This is a presentation given by Dirk-Jan Rutten and Florentijn Hogerwerf at the React-Amsterdam Winter Event held on the 23rd of February 2017 (https://www.meetup.com/React-Amsterdam/events/237423993/).

1. LESSONS LEARNED FROM IMPLEMENTING A GRAPHQL API

2. Dirk-Jan @excite-engineer
Dirk is a Software Engineer with a
focus on Javascript who gets (way
too) excited about writing stable and
well tested code. GraphQL fan.
Florentijn @Mr_Blue_Sql
GraphQL enthusiast. Focusing on
Javascript and realizing highly
available, easy to maintain solutions
on AWS. I like giving high ves.

3. HI THERE
hi-there.community

4. Agenda
What is GraphQL?
Lessons Learned from
implementing a GraphQL API

5. What is GraphQL?
A query language for your API

6. Properties
Client controls data, not the server
Multiple resources in a single
request
Documentation is awesome
Type system
Developer tools: GraphiQL

7. GraphQL Demo

8. LESSON 1
Separation of concerns

9. Query Joke
{
joke(id: "1") {
id
text
funnyLevel
}
}

10. Implement the query
const query = {
joke: {
type: GraphQLJoke,
args: {
id: {
type: new GraphQLNonNull(GraphQLID)
}
},
resolve: (root, args) {
return db.joke.findById(args.id);
}
}
}

11. Authorization: Joke can only be retrieved
by creator
const query = {
joke: {
type: GraphQLJoke,
args: {
id: {
type: new GraphQLNonNull(GraphQLID)
}
},
resolve: async (root, args, context) {
const data = await db.joke.findById(args.id);
if (data == null) return null;
/* Authorization */
const canSee = data.creator === context.viewer.id;
return canSee ? data : null;
}
}
}

12. Implement the Joke object type.
const GraphQLJoke = new GraphQLObjectType({
name: 'Joke',
fields: {
id: {
type: new GraphQLNonNull(GraphQLID),
resolve: (data) => data.id
},
text: {
type: new GraphQLNonNull(GraphQLString),
resolve: (data) => data.text
},
funnyLevel: {
type: new GraphQLNonNull(GraphQLInt),
resolve: (data) => data.funnyLevel
}
}
});

13. Result
{
joke(id: "1") {
id
text
funnyLevel
}
}
{
"joke": {
"id": "1",
"text": "What is the key difference between snowmen and snowwomen? Snowballs.",
"funnyLevel": 0
}
}

14. Update joke mutation
mutation {
updateJoke(jokeId: "1", funnyLevel: 10) {
id
text
funnyLevel
}
}

15. Implementation in GraphQL
const mutation = {
type: new GraphQLNonNull(GraphQLJoke),
description: "Update a joke.",
args: {
jokeId: { type: new GraphQLNonNull(GraphQLID) },
funnyLevel: { type: new GraphQLNonNull(GraphQLInt) }
},
resolve: (root, args, context) => {
//...
}
}

16. Duplicate authorization logic
resolve: async (root, args, context) => {
/* validation */
if (args.funnyLevel < 0 || args.funnyLevel > 5)
throw new Error('Invalid funny level.');
const data = await db.joke.findById(args.jokeId);
if (data == null) throw new Error('No joke exists for the id');
/* authorization */
if (data.creator !== context.viewer.id) throw new Error('No joke exists for the id')
/* Perform update */
data.funnyLevel = funnyLevel;
async data.save();
return data;
}

17. Result
mutation {
updateJoke(jokeId: "1", funnyLevel: 10) {
id
text
funnyLevel
}
}
{
"errors": [
{
"message": "Invalid funny level",
}
]
}

18. Building out the schema
Retrieve a list of jokes
Delete a joke
Create a joke
...

19. Authorization/Database logic all over the
place!

20. Direct effects
Logic spread around independent
GraphQL resolvers: Hard to keep in sync.
Testing dif cult.
Hard to maintain.

21. Long term issues: In exibility
Hard to switch from GraphQL to
other API protocol.
Hard to switch to other DB type.

22. The solution! Separation

23. Business Logic
Single source of truth for enforcing
business rules.
Determines how data is retrieved,
created and updated from DB.
Performs authorization for data
Performs validation

24. Connecting GraphQL to the business
logic:
Resolver functions maps directly to the
business logic.

25. Example 1: Query Joke
{
joke(id: "1") {
id
text
funnyLevel
}
}

26. Before the split
const query = {
joke: {
type: GraphQLJoke,
args: {
id: {
type: new GraphQLNonNull(GraphQLID)
}
},
resolve: async (root, args, context) {
const data = await db.joke.findById(args.id);
if (data == null) return null;
/* Authorization */
const canSee = data.creator === context.viewer.id;
return canSee ? data : null;
}
}
}

27. After the split
import Joke from "../logic";
const query = {
joke: {
type: GraphQLJoke,
args: {
id: {
type: new GraphQLNonNull(GraphQLID)
}
},
resolve: (root, args, context) => Joke.gen(context.viewer, args.id)
}
}

28. Business logic Layer
const areYouOwner = (viewer: User, data) => {
return viewer.id === data.creator;
}
class Joke {
static async gen(viewer: User, id: string): Promise<?Joke> {
const data = await db.joke.findById(id);
if (data == null) return null;
const canSee = areYouOwner(viewer, data);
return canSee ? new Joke(data) : null;
}
constructor(data: Object) {
this.id = String(data.id);
this.text = data.text;
this.funnyLevel = data.funnyLevel;
}
}

29. Example 2: Mutation to update a joke
mutation {
updateJoke(jokeId: "1", funnyLevel: 10) {
id
text
funnyLevel
}
}

30. GraphQL
const mutation = {
type: new GraphQLNonNull(GraphQLJoke),
description: "Update a joke.",
args: {
jokeId: { type: new GraphQLNonNull(GraphQLID) },
funnyLevel: { type: new GraphQLNonNull(GraphQLInt) }
},
resolve: (root, args, context) => {
//...
}
}

31. Single source of truth for authorization
import Joke from "../logic";
resolve: (root, args, context) => {
/* Authorization */
const joke = Joke.gen(context.viewer, args.jokeId);
if (!joke) throw new Error('No joke found for the id');
/* Performs validation and updates DB */
joke.setFunnyLevel(args.funnyLevel);
return joke;
}

32. - graphql.org

33. Bene ts
Single source of truth for enforcing
business rules.
Testability
Maintainable

34. LESSON 2
Relay Compliant Schema

35. What is it?
A GraphQL schema speci cation that
makes strong assumptions about
refetching, pagination, and realizing
mutation predictability.

36. Client Side Caching

37. Joke Query
//GraphQL query:
query {
viewer {
id
jokes {
id
}
}
}
//Result:
{
"viewer": {
"id": "1",
"jokes": [{
"id": "1"
}]
}
}

38. Solution
Create globally unique opaque ids

39. Joke Query Unique Ids
//GraphQL query:
query {
viewer {
id
jokes {
id
}
}
}
//Result:
{
"viewer": {
"id": "Sh3Ee!p=",
"jokes": [{
"id": "m0=nK3Y!"
}]
}
}

40. The Result
Caching becomes simple
Database assumptions opaque to
client

41. ... and every object can easily be
refetched

42. Refetching

43. Retrieve resource using single query
query {
node(id: "E4sT3r!39g=") {
id
... on Joke {
title
funnyness
}
}
}

44. Pagination

45. List Example
"data" {
"viewer" {
"jokes": [
{
"id": "1",
"text": "How do you make a tissue"
},
...
{
"id": "500",
"text": "Pfooo, only half way"
},
...
{
"id": "1000",

46. Why Pagination?
More ne-grained control
Prevents app from being slow
Improves back-end performance

47. Pagination done right using connection
approach
query {
viewer {
jokes(first: 10 /*The offset*/, after: "TUr71e=!" /*Cursor*/) {
edges {
cursor //Cursor
node {
text
funnyLevel
}
}
pageInfo { //pageInfo contains info about whether there exist more edges
hasNextPage
}
}
}
}

48. Opportunity to change to Relay if you
wish

49. Advantages Relay Compliant Schema
Enforce globally unique id that is
opaque
Any resource that belongs to you
can be retrieved using a single query
Pagination for lists is built in
Opportunity to change to Relay if
you wish

50. To Sum Up
Lesson 1: API, Business Logic,
Persistence Layer
Lesson 2: Relay compliant schema

51. More Lessons
Authentication
Caching & Batching
Error Handling

52. Reach us on twitter!
@excite-engineer
@Mr_Blue_Sql

53. Thanks!