Skip to content

Latest commit

 

History

History
566 lines (390 loc) · 11 KB

Lesson-1.md

File metadata and controls

566 lines (390 loc) · 11 KB
Raw

FEW 2.9 GraphQL Intro

Welcome to FEW 2.9

Why you should know this?

GraphQL represents a new way to work with network transactions. It provides many benefits over REST.

Class Learning Objectives

  1. Compare REST with GraphQL
  2. Define RESTful routes
  3. Describe the benefits of GraphQL
  4. Compare and contrast REST and GraphQL
  5. Write GraphQL Queries

Warm Up (5 mins)

ELI5 (Explain Like I'm 5). Choose one of these to explain

  • How do Web Pages work?
  • How do web browsers work?
  • What are Web APIs?

What makes the web work?

REST 😴 and SOAP 🧼

These are two different approaches to online data transmission. These describe how data is passed around over the internet.

SOAP 🧼

Simple Object Access Protcol

is the official standard maintained by the W3C. SOAP uses XML exclusively!

<book>
  <isbn>1929394</isbn>
  <author>Secret Agent Man</author>
  ...
</book>

xml: Extensible Markup Language

REST 😴

Representational State Transfer

is an architectural 🏛 principal and guidelines
for creating public APIs.

Wikipedia says: REST is a software architectural style...

How does REST 😴 work?

A REST API is an API that follows REST-ful Routing. REST-ful routing is a set of conventions for implementing CRUD on an HTTP server.

These conventions are common rules around the type of HTTP request and the URLS that are used for reading, updating, creating or deleting data on a server.

URL HTTP Method/Type Operation
/posts POST ???
/posts GET ???
/posts/10 PUT ???
/posts/23 DELETE ???
/posts/5 GET ???
/users/2/posts POST ???

What would be the operations for each of these routes? What do they do?

Here's a real API.

The Star Wars API (SWAPI) uses the following routes:

Unlike REST 😴 a GraphQL 😎 server would use a single ☝️ endpoint to serve all of it's resources.

The SWAPI (REST) had 5 endpoints!

Compare REST and GraphQL

  • REST 😴 - Multiple endpoints 🖐
  • GrapQL 😎 - Single endpoint ☝️

Try out REST 😴 with the SWAPI server (REST).

Try the people 👯‍♀️ endpoint.

Challenge: find C-3PO, Han Solo, Chewbacca and Boba Fett

Use the planets 🪐 endpoint.

Try it with GraphQL 😎

With GraphQL 😎 you will send a query that might look like this:

{
  posts {
    title
  }
}

Or this:

{
  users {
    name
  }
}

A query begins with:

{
  ...
}

Next add a type and any parameters for that type. In this case person is our type and personID is the parameter:

{
  person(personID: 5) {
    ...
  }
}

Add fields that you want. Note that person() returns a Person type and we can only include fields that exist on Person!

{
  person(personID: 5) {
    name
    eyeColor
    ...
  }
}

Try out GraphQL 😎 with SWAPI!

To do this you'll use GraphiQL. It's a web page that let's you write GraphQL queries and see the results.

First, open the GraphiQL browser:

http://graphql.org/swapi-graphql

  • Type a Query in the left side
  • Click the ▶️ button at the top
  • Look 👁 at the results on the right
  • Try the following queries...

Challenge: Get characters with GraphQL 😎

# Leia 
{
  person(personID: 5) {
    name
  }
}

Challenge: change the id to find Luke, Han, R2, C3PO and Vader

Over Fetching

Over fetching occurs when you make a request and receive more 🗑 data than you need.

This happens often. Think of all of those fields that you never use. 🤔

Look at the results that are returned with
the REST response vs the GraphQL 😎 response.

What's the difference? 🤔

The REST API returns the following when you use the /people route:

{
	"name": "Luke Skywalker",
	"height": "172",
	"mass": "77",
	"hair_color": "blond",
	"skin_color": "fair",
	"eye_color": "blue",
	"birth_year": "19BBY",
	"gender": "male",
	"homeworld": "https://swapi.dev/api/planets/1/",
	"films": [
		"https://swapi.dev/api/films/2/",
		"https://swapi.dev/api/films/6/",
		"https://swapi.dev/api/films/3/",
		"https://swapi.dev/api/films/1/",
		"https://swapi.dev/api/films/7/"
	],
	"species": [
		"https://swapi.dev/api/species/1/"
	],
	"vehicles": [
		"https://swapi.dev/api/vehicles/14/",
		"https://swapi.dev/api/vehicles/30/"
	],
	"starships": [
		"https://swapi.dev/api/starships/12/",
		"https://swapi.dev/api/starships/22/"
	],
	"created": "2014-12-09T13:50:51.644000Z",
	"edited": "2014-12-20T21:17:56.891000Z",
	"url": "https://swapi.dev/api/people/1/"
}

With GraphQL 😎 we only received:

{
  "data": {
    "person": {
      "name": "Luke Skywalker"
    }
  }
}

If we needed more we could ask for more!

If we only wanted the name field the GraphQL 😎
query would have saved some bandwidth! 🗜

Describe the fields you want in the query:

{
  person(personID: 4) {
    name
    eyeColor # includes eye color
  }
}

Challenge: Get Vader's, height, and eyeColor

Compare REST with GraphQL

  • GraphQL 😎 - we describe what we want
    in our query and server returns 🎁 data that matches the query.
  • REST 😴 - you get everything (often over fetching)

Under Fetching 🥚

Under fetching 🥚 occurs when you don't get all of the data you need in a single request and have to make another request to get the data you require.

Challenge: Use REST to find Leia's homeworld. 🌍

Challenge:

Use the REST API to find:

  1. Find Chewbacca's homeworld.
  2. Find R2-D2's homeworld
  3. Find Han's homeworld

What happened? 🧐

Each time you found a person, you had to make a second request to find their homeworld.
(under fetching)

Along the way you loaded more data than you needed.(over fetching)

Try it with GraphQL 😎

{
  person(personID: 4) {
    name
    homeworld {
      name
    }
  }
}

Here in a single query we get the character's name and the name of the homeworld.

Challenge:

  1. Get R2-D2's name and homeworld
  2. Get Leia's name and homeworld
  3. Get Han's name, height, and homeworld
  4. Get R2's name, eyecolor, homeworld and it's diameter

Compare REST with GraphQL

  • REST 😴 - over or under fetches
  • GraphQL 😎 - fetches only what you ask for in a single ☝️ query!

GraphQL vs REST

Pair and discuss the pros and cons of REST and GraphQL.

Tell your partner everything that was just covered. Think how this might improve your work or where there might be problems.

  • REST 😴
    • Requires multiple endpoints. Makes for a complex API.
      • Harder to make changes to your API.
    • Often over fetches providing more data than you need eating bandwidth
    • Often under fetchs, requiring more complex queries and more bandwidth.
  • GraphQL 😎
    • Uses a single endpoint.
      • Easier to manage
      • More tolerant to changes
    • Fetches only what you ask for
      • Prevents over fetching
      • Prevents under fetching
      • Saves bandwidth
  • GraphQL 😎 provides other benefits!
    • Type safety 🛡
    • Introspection 🔎

Core features of GraphQL

  • Query Language
    • Query
    • Mutation
    • Subscription
  • Schema Definition Language
    • Strong Typing
    • Introspection

So, What is GraphQL 🤔

GraphQL is an open-source data query and manipulation language for APIs, and a runtime for fulfilling queries with existing data.

From wikipedia

Aliases

Since the query describes the structure of what is returned sometimes you need to change the names.

Consider a scenario where you need two people:

{
  person(personID:2) {
		name    
  }
  
  person(personID:3) {
    name
  }
}

(Doesn't work!)

The results would have a problem

{
  "data": {
    "person": { <-- Duplicate field!
      "name": "C-3PO"
    },
    "person": { <-- Duplicate field!
      "name": "R2-D2"
    }
  }
}

(Hypothetical results from the previous query)

Use an alias to solve the problem!

{
  personA: person(personID:2) {
		name    
  }
  
  personB: person(personID:3) {
    name
  }
}

(personA and personB are aliases, you could use any name for these!)

The result would look like this:

{
  "data": {
    "personA": {
      "name": "C-3PO"
    },
    "personB": {
      "name": "R2-D2"
    }
  }
}

(Results from the previous query)

After Class

  • Watch the videos here: https://www.howtographql.com
    • Introduction
    • GraphQL is the better REST
    • Core Concepts
    • Big Picture (Architecture)
  • Answer the questions in assignment 1 on GradeScope.
    • For each question provide the GraphQL query that would provide what was asked for.

Evaluate your Work!

  1. Compare REST with GraphQL
  2. Define RESTful routes
  3. Describe the benefits of GraphQL
  4. Compare and contrast REST and GraphQL
  5. Write GraphQL Queries
- Does not meet Meets Exceeds
Understanding Can't describe GraphQL Could describe GraphQL it basic features and usage Can confidently describe GraphQL and suggest use cases
Comprehension Can't compare GraphQL and REST Could compare GraphQL and REST and identify the features unique to each Can contrast GraphQL and REST and posit use cases suitable for each
GraphQL Query Language Can't write a query with graphQL Can write a graphQL Query Can see a path to writing GraphQL queries for a wide variety of operations

Additional Resources