SETCON'18 - Ilya labacheuski - GraphQL adventures

1BREST
GraphQL
adventures
APRIL 22, 2018

2BREST
ILYA LABACHEUSKI
Software developer in EPAM systems.
Also a member of the IT Shark Community.
The main field is frontend Javascript development. I have some experience in
Node.js and React Native. Some other fields of interest are CAD systems, simple
engineering and some bad habits. :)
ILYA
LABACHEUSKI
EPAM Systems, software developer

4BREST
GraphQL. What is it?
A query language for your API
Ask for what you need, get exactly that!
{
hero {
aliasName: name
height
mass
}
}
{
"hero": {
"aliasName": "Luke Skywalker",
"height": 1.72,
"mass": 77
}
}

5BREST
This presentation
1. A very simple tutorial for setting up a GraphQL server
written in TypeScript.
2. Some adventures and thoughts about migration to
GraphQL from REST API.

8BREST
Luggage
Persons
Insurance
Flight
Info
Hotel
Car

9BREST
Luggage
Persons
Insurance
Flight
Info
Hotel
Car
Statistics
Emails
AnalyticsA/B
Testing

10BREST
More features,
more data,
more problems

12BREST
Simple GraphQL schema
type Airport {
id: number!
name: String!
code: String!
# … more fields
}
type Root {
airport(id: number!): Airport
}

13BREST
Simple query example
type Airport {
id: number!
name: String!
}
type Root {
}
query AirportName($id: number) {
airport($id: id) {
name }
}

14BREST
Vanilla Javascript
const airportName = props => (
<div>Name: {props.graphqlValue.airport.fullName}</div>
)
export default connectGraphQL(DeviceNameComponent, () => ({
query: ...
variables: {
airportId: 123342334
},
}))

15BREST
Possible mistakes
)
query: ...
variables: {
},
})) Webpack compiles

16BREST
Type it!
type Airport {
id: number!
name: String!
}
type Root {
}
query AirportName($id: number) {
airport($id: id) {
name }
}
interface AirportNameQuery {
airport: {
name: string;
}
}
interface AirportNameInput {
id: number;
}

17BREST
Type it
)
query: ...
variables: {
},
}))

18BREST
Type it (with TypeScript)
const airportName = (props: Props) => (
)
export default connectGraphQL<Props, AirportNameQuery,
AirportNameInput>(DeviceNameComponent, () => ({
query: ...
variables: {
},
}))
No fullName in type QueryResult
No airportId in type AirportNameInput

19BREST
• Safety — static verification at compile time
• Editor tooling — code help, highlighting, going to definition
• One source of truth — types should have unique reference
Advantages

21BREST
Good tools to use
• ts-node — the same as node for TypeScript
• tslint + rules — eslint for TypeScript
• express (koa …) — works well with TypeScript
• apollo-server-express — for GraphQL
• graphql-playground-middleware-express — a playground
• graphql-voyager — to see everything graphically
• jest + ts-jest — unit testing
• nodemon — reloading the server
• graphql-import — write in .graphql files

25BREST
Server
import express from 'express';
import bodyParser from 'body-parser';
import { graphqlExpress } from 'apollo-server-express';
import { schema } from './schema';
const PORT = 3000;
const app = express();
app.use('/graphql', bodyParser.json(), graphqlExpress({ schema }));
app.listen(PORT);

26BREST
Playground and Voyager
import playground from 'graphql-playground-middleware-express';
import { express as voyager } from 'graphql-voyager/middleware';
...
// bodyParser is needed just for POST.
app.use('/graphql', bodyParser.json(), graphqlExpress({ schema }));
app.get('/graphiql', playground({ endpoint: '/graphql' }));
app.use('/voyager', voyager({ endpointUrl: '/graphql' }));
app.listen(PORT);

27BREST
schema.ts
import { importSchema } from 'graphql-import';
const resolvers = {
Query: {
// ...
},
};
export const schema = makeExecutableSchema({
resolvers,
typeDefs: importSchema('src/schema/root.graphql'),
});

28BREST
root.graphql
# import Flight from 'flight.graphql'
# import Airport from 'airport.graphql'
# Root query description
type Query {
# Simple description
airport(id: ID!): Airport
flight(id: ID!): Flight
}

29BREST
schema.ts
import { importSchema } from 'graphql-import';
export const schema = makeExecutableSchema({
resolvers,
typeDefs: importSchema('src/schema/root.graphql'),
});
Will generate combined AST for your schema:
- root.graphql
| — flight.graphql
| — airport.graphql
| | — importInAirport.graphql
...

30BREST
nodemon settings
{
"ignore": ["**/*.test.ts", "**/*.spec.ts", ".git", "node_modules"],
"watch": ["src"],
"execMap": {
"ts": "./node_modules/.bin/ts-node"
},
"events": {
"start": "./node_modules/.bin/tslint -c ./tslint.json 'src/**/*.ts' --format
stylish --force"
},
"ext": "ts js graphql",
"env": {
"NODE_ENV": "development"}
}

32BREST
Schemifying your REST APIs
• Write by hand?
• Auto generate?
• Do both?
• Do you have full documentation for REST APIs?
• Are all fields in requests and responses defined?

33BREST
Writing a schema manually
Pros:
• GraphQL will be defined for your specific needs.
• Easy to extend, simplify or remove types.
Cons:
• Any update in REST APIs requires attention.
• Requires big analysis of how you use your API.
• The process is long.

34BREST
Auto generation from REST APIs
Pros:
• You can generate a schema from existing REST schemas
(Swagger/OpenAPI) relatively easily.
• You can combine multiple API REST and GraphQL services.
Cons:
• The schema will be more complex.
• Changes in types require a complex tool to generate an updated
schema properly.

35BREST
Combination of both
Pros:
• Automatic translation for basic types.
• Flexibility to make your schema simpler and better.
Cons:
• Your schema will be the source of truth and will not repeat your
REST APIs.
• Still a lot of work.

36BREST
No documentation for REST APIs
What we have done:
- Logged all API requests and their responses to JSON.
- Translated responses in JSON files to TypeScript types.
- Translated TypeScript types to a GraphQL schema.
- Tried to make an automatic script that will repeat all the needed
API calls to make a ‘happy flow.’

37BREST
Logged APIs
[{ "timestamp": 1521795786330,
"id": "b543e0f663d2",
"type": "request",
"payload": {
"url": "https://api.oursite.com/params",
"method": "GET" }
},{
"timestamp": 1521795786691,
"id": "b543e0f663d2",
"type": "response",
"payload": {
"body": { ... },
"status": 200 }
}, ... ]

38BREST
Convert JSON to files
- Initial Loading Requests
| — 01_RootApi_response.ts
| — 02_FlightApi_response.ts
| — 03_PassengersDetailsAPI_response.ts
...
`https://api.oursite.com/87fdg7sdfr9`
`https://api.oursite.com/flight/868`
`https://api.backend.com/passenges/87fdg7sdfr9/details/578d`

39BREST
Typescript files content
// https://api.oursite.com/87fdg7sdfr9
export interface RootApiResponse {
_links: Links;
}
export interface FlightDetails {
href: string;
template: boolean;
}
export interface Links {
self: Self;
"flight:details": FlightDetails;
"passengers:details": FlightDetails;
}
export interface Self { href: string; }
Root API
flight:details passengers:details
airports
car:shop
insurance:details
REST HAL

40BREST
Problems — 1
_links: Links;
}
href: string;
template: boolean;
}
self: Self;
}
Repeated types

41BREST
Problems — 2
_links: Links;
}
href: string;
template: boolean;
}
self: Self;
}
Forbidden symbols in GraphQL

42BREST
Problems — 3
_links: Links;
}
href: string;
template: boolean;
}
self: Self;
}
Merged types

43BREST
Problems — 4
_links: Links;
}
href: string;
template: boolean;
}
self: Self;
}
Names do not express
the semantics.

44BREST
Converting to GraphQL
type RootApiResponse {
_links: Links;
}
type FlightDetails {
href: string;
template: boolean;
}
type Links {
self: Self;
flightDetails: FlightDetails;
passengersDetails: FlightDetails;
}
type Self { href: string; }

45BREST
Simplify and correct schema
type RootApiResponse {
_links: Links!;
}
type Link {
href: string!;
template: boolean;
}
type Links {
self: Link!;
flightDetails: Link!;
passengersDetails: Link!;
}

46BREST
No response — no type
export interface Passengers {
passenger: Passenger;
baggage: Baggage;
}
export interface Baggage {
Items: any[];
}

47BREST
Automatic scripts
import { BaggageResponse } from './05_BaggageApi_response'
import { PassengersResponse } from './02_PassengersAPI_response';
const baggage = await fetchJson<BaggageResponse>(baggageUrl);
const flightPassengersInput = { baggage, person }
const passengersResult = await fetchJson<PassengersResponse>(url, {
body: flightPassengersInput,
});

48BREST
Exposing REST API structure

49BREST
Mimicing REST API vs making GraphQL first
query {
flightResourse {
getPassengers(flightId: ID!) : Passengers
}
}
# vs
query {
getPassengersByFlightId(flightId: ID!) : Passengers
}
Nested structure
Flat structure with many root queries

50BREST
Mimicing REST API
type MutationOnPage {
postPassengers(opts: PassengersInput!): PassengersResponseSubmit
}
Can be a completely unique type.

51BREST
Mimicing REST API: getting your data
type MutationOnPage {
postPassengers(opts: PassengersInput!): PassengersResponseSubmit
}
input PassengersInput {
baggage: [Baggages!]!
Person: Person!
}
input BaggagesInput {
Items: [Baggage!]!
}
Comes from another request, that depends on
another request, that depends… and so one

52BREST
Mimicing REST API forces to make a nested schema
query getInfoForPassengersInput {
getFlight(id: ID!) {
getPassengers {
getBaggage {
...
}}}}
query getInfoForInsuranceInput {
getFlight(id: ID!) {
getServices {
getPassengers {
...
}}}}
For every unique situation you will have its
own nesting with possibly unique types

53BREST
Mimicing REST APIs
Pros:
• Easy to convert
Cons:
• Your schema will be a mess of unique flows and types.
• Getting data is a traversing graph.

54BREST
Making GraphQL first
flight(id: ID!) {
passengers { ... }
baggage { ... }
}}}
query getInfoForInsuranceInput {
flight(id: ID!) {
services { ... }
passengers { ... }
}}}

55BREST
Making GraphQL first
flight(id: ID!) {
passengers { ... }
baggage { ... }
}}}
const resolvers = {
passengers: ({flightId, serviceId}, opts, ctx) => {
return flightId
? restApiCall('https://api.flights.com/')
: restApiCall('https://api.services.com/')
}
},
},
};

56BREST
GraphQL first
Pros:
• Reuse of types
• Simpler schema and queries
• Simpler for a data client
Cons:
• Resolvers can be very smart.

57BREST
REST APIs with expiration tokens
`https://api.oursite.com/{token}`
query {
flight(id: ID!) { <- 300 ms REST API call
passengers { <- 400 ms REST API call
baggage { <-- here the token expires
}
}
}
}
You should have a strategy what to do in such case.

58BREST
Query complexity
query {
flight(id: ID!) {
carrier
price
}
airport(limit: 20) {
name
city
}
}
flight + carrier + price = 3
In case for every airport is needed separate
REST API request:
(airport + name + city) * 20 = 60
Total = 63

60BREST
CONTACT INFORMATION
Your_mail@epam.c
om
Usernam
e
Usernam
e
Usernam
e
Usernam
e
Ilya Labacheuski ilya.labacheuski@gmail.com
https://github.com/ilabacheuski

SETCON'18 - Ilya labacheuski - GraphQL adventures

Recommended

Recommended

More Related Content

What's hot

What's hot (20)

Similar to SETCON'18 - Ilya labacheuski - GraphQL adventures

Similar to SETCON'18 - Ilya labacheuski - GraphQL adventures (20)

More from Nadzeya Pus

More from Nadzeya Pus (7)

Recently uploaded

Recently uploaded (20)

SETCON'18 - Ilya labacheuski - GraphQL adventures