FIGHTING API FRAGMENTATION WITH

GraphQL

https://xkcd.com/927/

Can you easily traverse the data model of our entire organization?

Can you determine what part of the data model can change?

First day on the job

Umm, We have REST APIS...

WITH SWAGGER

Growth leads to increased data model complexity

Which leads to REST APIS with Swagger calling rest APIs with Swagger

APIS!!!

Which leads to Complexity+Latency

Bored Already?

Demo(lition) time

What & When

Strongly-typed, declarative, introspective query language and type system for your entire organization-wide domain model
RFC spec published in 2015
Used internally by Facebook since 2012
Open source implementations in Node, Scala, Python, PHP, etc.

WHO

JSON IS GREAT AT DESCRIBING DATA trees

BUT TREES ARE JUST SNAPSHOTS OF PARTS OF A GRAPH

JSON IS BAD AT DESCRIBING DATA GRAPHS

"MOST DOMAIN MODELS ARE GRAPHS" -- Abe Lincoln

STEPS TO UNDERSTANDING GraphQL

1. On the server,

Describe your TYPES

type Project {
  name: String
  tagline: String
  contributors: [User]
}

type User {
  name: String
  email: String
  failedLogins: Integer
  isActive: Boolean
  homepage: String
}

2. On the server,

RESOLVE your data

  {
    project: ({id}) => projectsService
      .get(`/projects/${id}`)
      .then(data => ({
        tagline: data.PoorlyNamedTagLine,
        contributors: data.contributors
      })
  }

3. On the CLIENT,

REQUEST SOME DatA

{
  project(name: "GraphQL") {
    tagline
    contributors {
      name
      email
    }
  }
}

4. On the CLIENT,

YOU GET SOME JSON DATA

{
  "project" : {
    "tagline": "A query language for APIs",
    "contributors" : [
      {
        "name": "Jim Cummins",
        "email": "jimthedev@gmail.com"
      },
      {
        "name": "Bart Simpson",
        "email": "bart@springfield.us"
      }
    ]
  }
}

{
  project(name: "GraphQL") {
    tagline
    contributors {
      name
      email
    }
  }
}

Notice how the response shape mimics the query shape.

Why does it matter?

When putting graph data in a tree, you over-fetch data which makes your responses large and your site feel slow.

SQL has been around for over 40 years and is popular because it is declarative and does not over-fetch.

In a declarative language I must declare exactly what data I want. The computer then gives me only the exact data I want.

Is it meant to replace JSON- rest?

Not necessarily. GraphQL can compliment JSON REST by sitting in front of it.

If REST is not available or not needed, it can fetch data itself by connecting directly to the DB.

How do I know if I need GraphQL?

IS GRAPHQL SQL?

No, but it is declarative like SQL.

Unlike SQL it can query APIs or databases.

GraphQL is not tied to a specific database, vendor or backend language.

You'LL know you've hit the limits of Tree structures (JSON) over rest when

Your API has querystring filters like:
?includes=['products', 'profile']

You fetch more than one resource type at a time to save bandwidth. (thus replicating rpc)

The majority of your the calls to your rest api are cache misses.

Your payload size is growing at a faster rate than the size of the fields you want off the payload.

You return duplicate data.

DB SCHEMAS AND APIs HARD TO CHANGE

DOCUMENTATIONFRAGMENTATION CHANG

FRONT END NOT PERFORMANT