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

More Related Content

What's hot

Viewers also liked

Similar to Introduction to GraphQL at API days

More from yann_s

Recently uploaded

Introduction to GraphQL at API days