Introduction to GraphQL at API days

More power to API clients
with GraphQL
Yann Simon - @simon_yann

Who am I
• Yann Simon, backend developer at commercetools
• in the last years, worked with REST APIs:
• for micro-services
• public APIs

Let’s build an
e-commerce API

Let’s build an
e-commerce API
surprise surprise

GET /products/45
{ 
"id": "45", 
"name": "running shoes", 
"price": { 
"centAmount": 3900, 
"currencyCode": "USD" 
} 
}

GET /products/45
{ 
"id": "45", 
"masterVariant": { 
"description": "white color", 
"price": { 
} 
} 
}

GET /products/45
{ 
"id": "45", 
"price": { 
} 
}, 
"variants": [ 
{ 
"description": "black color", 
"price": { 
} 
}, 
{ 
"description": "red color", 
"price": { 
} 
} 
] 
}

GET /products/45
{ 
"id": "45", 
"price": { 
} 
}, 
"variants": [ 
{ 
"price": { 
} 
}, 
{ 
"price": { 
} 
} 
] 
}
OR?

GET /products/45
{ 
"id": "45", 
"id": "3", 
"price": { 
} 
}, 
"variantIds": [ "23", "18" ] 
}

GET /products/45
{ 
"id": "45", 
"id": "3", 
"price": { 
} 
}, 
"variantIds": [ "23", "18" ] 
}
GET /products/45/variants/23

GET /products/45
{ 
"id": "45", 
"id": "3", 
"price": { 
} 
}, 
"variantIds": [ "23", "18" ] 
}
{ 
"id": "23", 
"price": { 
} 
}

GET /products/45
{ 
"id": "45", 
"id": "3", 
"price": { 
} 
}, 
"variantIds": [ "23", "18" ] 
}
{ 
"id": "23", 
"price": { 
} 
}
{ 
"id": "18", 
"price": { 
} 
}

More data, maybe unused
or
more requests?

Let’s build this API
with GraphQL
Demo

With GraphQL
• the client decides which ﬁelds are needed

With GraphQL
{ 
product(id: "45") { 
name 
masterVariant { 
description 
price { 
centAmount 
currencyCode 
} 
} 
variants { 
description 
price { 
centAmount 
currencyCode 
} 
} 
} 
}

With GraphQL
{ 
name 
masterVariant { 
description 
price { 
centAmount 
currencyCode 
} 
} 
variants { 
description 
price { 
centAmount 
currencyCode 
} 
} 
} 
}
{ 
"data": { 
"product": { 
"description": "white", 
"price": { 
} 
}, 
"variants": [ 
{ 
"description": "white", 
"price": { 
} 
}, 
{ 
"description": "black",

• exactly the data the client needs
• in one request

{ 
p45: product(id: "45") { 
name 
} 
 
name 
canBeCombinedWith { 
id 
name 
} 
} 
}
• in one request

{ 
name 
} 
 
name 
id 
name 
} 
} 
}
{ 
"data": { 
"p45": { 
"name": "running shoes" 
}, 
"p54": { 
"name": "basketball shirt", 
"canBeCombinedWith": [ 
{ 
"id": "46", 
"name": "basketball shoes" 
}, 
{ 
"id": "58", 
"name": "basketball T-shirt" 
} 
] 
} 
} 
}
• in one request

{ 
name 
} 
 
name 
id 
name 
} 
} 
}
{ 
"data": { 
"p45": { 
"name": "running shoes" 
}, 
"p54": { 
"name": "basketball shirt", 
"canBeCombinedWith": [ 
{ 
"id": "46", 
"name": "basketball shoes" 
}, 
{ 
"id": "58", 
"name": "basketball T-shirt" 
} 
] 
} 
} 
}
• in one request
m
obile
friendly

With GraphQL
• the client has more power
{ 
variants(master: false, limit: 10, offset: 20) { 
price { 
centAmount 
} 
} 
} 
} 
• and the server can be more generic

Introspection
{ 
__type(name: "product") { 
fields { 
name 
} 
} 
} 
{ 
"data": { 
"__type": { 
"fields": [ 
{ 
"name": "id" 
}, 
{ 
"name": "name" 
}, 
{ 
"name": "masterVariant" 
}, 
{ 
• the schema is used:
• to validate the queries (server & maybe client)
• for introspection
• for documentation

API evolution
GET /products/45
{ 
"id": "45", 
"price": { 
} 
} 
}

API evolution
GET /products/45
{ 
"id": "45", 
"price": { 
} 
} 
}
{ 
"id": "45", 
"names": { 
"en": "running shoes", 
"fr": "godasses pour courir vite" 
}, 
"descriptions": { 
"en": "white color", 
"fr": "couleur blanche" 
}, 
"prices": { 
"us": { 
}, 
"fr": { 
"currencyCode": "EUR" 
} 
}, 
"price": { 
} 
} 
}

Can we remove a
deprecated ﬁeld?

Let’s modify our
GraphQL based API
Demo

With GraphQL
• a field can be deprecated
• still valid for a query
• not in the schema anymore
• the server can track if a field is used
• the field can be removed when not used anymore

REST vs GraphQL?
• REST is here to stay
• simple
• widely used
• GraphQL
• different approach
• solve some limits of REST

ecosystem
• used in Facebook’s native apps in production since 2012
• open source in July 2015
• speciﬁcation
• backend agnostic
• implementation in different languages
• nodejs, java, scala, ruby, php and many more
• front-end frameworks based on GraphQL like relay

So you want to try it?
• https://learngraphql.com/
• create an account on https://admin.sphere.io/
• you can create a project with sample data
• try GraphQL with this account on https://
impex.sphere.io/graphiql

Thanks for your attention
Yann Simon - @simon_yann

Introduction to GraphQL at API days

Recommended

Recommended

More Related Content

What's hot

What's hot (20)

Viewers also liked

Viewers also liked (20)

Similar to Introduction to GraphQL at API days

Similar to Introduction to GraphQL at API days (20)

More from yann_s

More from yann_s (6)

Recently uploaded

Recently uploaded (20)

Introduction to GraphQL at API days