Tweet
Tweet

Slide 1

Slide 1 text

REST vs GraphQL The What, How and Why Berlin PHP Usergroup, November 7 2017

Slide 2

Slide 2 text

About Me ● Hi, I’m Marco Petersen! ● My home on the internet: ma.rcopetersen.com ● My nickname on the interwebs: ocrampete16 ● Slides are published on Speaker Deck

Slide 3

Slide 3 text

No content

Slide 4

Slide 4 text

No content

Slide 5

Slide 5 text

No content

Slide 6

Slide 6 text

Is REST really dead?

Slide 7

Slide 7 text

What is REST? ● REpresentational State Transfer ● 2000, Roy Fielding’s PhD dissertation ● Architectural concept for network-based software

Slide 8

Slide 8 text

What is REST? ● URIs serve as unique identifiers for resources ● HTTP verbs denote what is to be done with a resource ● Leverages HTTP features (headers, status codes etc.) ● HATEOAS (Hypertext As The Engine Of Application State)

Slide 9

Slide 9 text

/users // all users /users/1 // user with the ID “1” /users/1/avatar // user 1’s avatar

Slide 10

Slide 10 text

What is REST? ● URIs serve as unique identifiers for resources ● HTTP verbs denote what is to be done with a resource ● Leverages HTTP features (headers, status codes etc.) ● HATEOAS (Hypertext As The Engine Of Application State)

Slide 11

Slide 11 text

// create a new user POST /users // replace a user’s avatar PUT /users/1/avatar // delete the user’s high score with the ID “42” DELETE /users/2/high-scores/42

Slide 12

Slide 12 text

What is REST? ● URIs serve as unique identifiers for resources ● HTTP verbs denote what is to be done with a resource ● Leverages HTTP features (headers, status codes etc.) ● HATEOAS (Hypertext As The Engine Of Application State)

Slide 13

Slide 13 text

What is REST? ● URIs serve as unique identifiers for resources ● HTTP verbs denote what is to be done with a resource ● Leverages HTTP features (headers, status codes etc.) ● HATEOAS (Hypertext As The Engine Of Application State)

Slide 14

Slide 14 text

{ "userId": 2, "name": "Leeroy Jenkins", "links": [ { "href": "/users/2/high-scores", "rel": "high-scores", "type" : "GET" } ] }

Slide 15

Slide 15 text

What is GraphQL? ● Developed in 2012 by Facebook, publicly released in 2015 ● Query language ● Lots of tools and libraries to facilitate development of GraphQL-compatible APIs ● Reference implementation in (server-side) Javascript

Slide 16

Slide 16 text

What is GraphQL? ● What You Want Is What You Get ● Single endpoint for all requests (typically /graphql ) ● Relies on own conventions instead of using HTTP ○ All client requests are POST ○ All server responses are 200 OK ● Uses queries and mutations for fetching and modifying data ● And much more!

Slide 17

Slide 17 text

Querying Data POST /graphql { user(id: "2") { name, birthdate, username } } 200 OK { “data”: { “user”: { “name”: “Leeroy Jenkins”, “birthdate”: “1995-07-13”, “username”: “foobar” } } }

Slide 18

Slide 18 text

Customizing Field Names POST /graphql { user(id: "2") { fullName: name, dateOfBirth: birthdate, username } } 200 OK { “data”: { “user”: { “fullName”: “Leeroy Jenkins”, “dateOfBirth”: “1995-07-13”, “username”: “foobar” } } }

Slide 19

Slide 19 text

Querying Subresources POST /graphql { me: viewer { fullname: name repositories(first: 2) { edges { node { name } } } } } 200 OK { "data": { "me": { "fullname": "Foobar Spameggs", "repositories": { "edges": [ {"node": {"name":"repo1"}}, {"node": {"name": "repo2"}} ] } } } }

Slide 20

Slide 20 text

What is GraphQL? ● What You Want Is What You Get ● Single endpoint for all requests (typically /graphql ) ● Relies on own conventions instead of using HTTP ○ All client requests are POST ○ All server responses are 200 OK ● Uses queries and mutations for fetching and modifying data ● And much more!

Slide 21

Slide 21 text

What is GraphQL? ● What You Want Is What You Get ● Single endpoint for all requests (typically /graphql ) ● Relies on own conventions instead of using HTTP ○ All client requests are POST ○ All server responses are 200 OK ● Uses queries and mutations for fetching and modifying data ● And much more!

Slide 22

Slide 22 text

What is GraphQL? ● What You Want Is What You Get ● Single endpoint for all requests (typically /graphql ) ● Relies on own conventions instead of using HTTP ○ All client requests are POST ○ All server responses are 200 OK ● Uses queries and mutations for fetching and modifying data ● And much more!

Slide 23

Slide 23 text

Mutations POST /graphql mutation CreateReviewForEpisode( 1: Episode!, {“stars”: 5}: ReviewInput! ) { createReview( episode: 1, review: {“stars”: 5} ) { stars } } 200 OK { "data": { "createReview": { "stars": 5 } } }

Slide 24

Slide 24 text

What is GraphQL? ● What You Want Is What You Get ● Single endpoint for all requests (typically /graphql ) ● Relies on own conventions instead of using HTTP ○ All client requests are POST ○ All server responses are 200 OK ● Uses queries and mutations for fetching and modifying data ● And much more!

Slide 25

Slide 25 text

Core Differences REST ● Architecture for APIs ● Utilizes HTTP to the fullest GraphQL ● Query language ● Uses HTTP as a “dumb” data transfer mechanism

Slide 26

Slide 26 text

Core Differences REST ● Architecture for APIs ● Utilizes HTTP to the fullest GraphQL ● Query language ● Uses HTTP as a “dumb” data transfer mechanism

Slide 27

Slide 27 text

Differences: Architecture vs Query Language REST ● Multiple endpoints ● Flexible in what requests it accepts ● No clear consensus on how to evolve APIs ● Returns entire resources (by default) GraphQL ● One endpoint for everything ● Limited to the query language ● API evolution is easy w/ great tooling ● What You Want Is What You Get

Slide 28

Slide 28 text

GET /users/1 PUT /users/1/avatar POST /users/1/highscores … // It’s inherently obvious what’s going on

Slide 29

Slide 29 text

POST /graphql POST /graphql POST /graphql …

Slide 30

Slide 30 text

Differences: Architecture vs Query Language REST ● Multiple endpoints ● Flexible in what requests it accepts ● No clear consensus on how to evolve APIs ● Returns entire resources (by default) GraphQL ● One endpoint for everything ● Limited to the query language ● API evolution is easy w/ great tooling ● What You Want Is What You Get

Slide 31

Slide 31 text

Differences: Architecture vs Query Language REST ● Multiple endpoints ● Flexible in what requests it accepts ● No clear consensus on how to evolve APIs ● Returns entire resources (by default) GraphQL ● One endpoint for everything ● Limited to the query language ● API evolution is easy w/ great tooling ● What You Want Is What You Get

Slide 32

Slide 32 text

Differences: Architecture vs Query Language REST ● Multiple endpoints ● Flexible in what requests it accepts ● No clear consensus on how to evolve APIs ● Returns entire resources (by default) GraphQL ● One endpoint for everything ● Limited to the query language ● API evolution is easy w/ great tooling ● What You Want Is What You Get

Slide 33

Slide 33 text

Differences: Resources vs What You See Is What You Get REST ● Clients receive data in a predefined structure ● Easier to cache ● Multiple API calls may be necessary ● No information on which fields are actually used GraphQL ● Clients receive data structured the way they need it ● Less cache hits ● Can fetch all data with a single API call ● Granular information on which fields are used

Slide 34

Slide 34 text

Differences: Resources vs What You See Is What You Get REST ● Clients receive data in a predefined structure ● Easier to cache ● Multiple API calls may be necessary ● No information on which fields are actually used GraphQL ● Clients receive data structured the way they need it ● Less cache hits ● Can fetch all data with a single API call ● Granular information on which fields are used

Slide 35

Slide 35 text

Differences: Resources vs What You See Is What You Get REST ● Clients receive data in a predefined structure ● Easier to cache ● Multiple API calls may be necessary ● No information on which fields are actually used GraphQL ● Clients receive data structured the way they need it ● Less cache hits ● Can fetch all data with a single API call ● Granular information on which fields are used

Slide 36

Slide 36 text

Differences: Resources vs What You See Is What You Get REST ● Clients receive data in a predefined structure ● Easier to cache ● Multiple API calls may be necessary ● No information on which fields are actually used GraphQL ● Clients receive data structured the way they need it ● Less cache hits ● Can fetch all data with a single API call ● Granular information on which fields are used

Slide 37

Slide 37 text

Core Differences REST ● Architecture for APIs ● Utilizes HTTP to the fullest GraphQL ● Query language ● Uses HTTP as a “dumb” data transfer mechanism

Slide 38

Slide 38 text

Differences: Utilizing HTTP vs merely transferring data REST ● Caching is easy ● HTTP verbs carry more semantic information ● Clearly defined protocol for marking errors GraphQL ● Cannot cache at the network level ● Queries/mutations not as precise ● Hard to infer errors programmatically

Slide 39

Slide 39 text

Caching: REST vs GraphQL Caching Types REST GraphQL Client Caching (browser etc.) yes yes, but it’s harder and most won’t bother Network Caching (Varnish, Squid etc.) yes no Application Caching (Redis, Memcache etc.) yes yes

Slide 40

Slide 40 text

Differences: Utilizing HTTP vs merely transferring data REST ● Caching is easy ● HTTP verbs carry more semantic information ● Clearly defined protocol for marking errors GraphQL ● Cannot cache at the network level ● Queries/mutations not as precise ● Hard to infer errors programmatically

Slide 41

Slide 41 text

Differences: Utilizing HTTP vs merely transferring data REST ● Caching is easy ● HTTP verbs carry more semantic information ● Clearly defined protocol for marking errors GraphQL ● Cannot cache at the network level ● Queries/mutations not as precise ● Hard to infer errors programmatically

Slide 42

Slide 42 text

If you can’t decide which to use… use both! ● Option 1: Add a /graphql endpoint and implement the API from scratch ● Option 2: Have a GraphQL server act as a data proxy to other REST APIs ○ Easier, but slight performance penalty ○ Cache as much as possible to mitigate performance hits

Slide 43

Slide 43 text

To recap... ● REST is an API architecture style, GraphQL a query language ● GraphQL is a good alternative, not REST 2.0 ● If you’re happy with REST, no reason to change. ● If you’re have vastly different clients that require data in different combinations, GraphQL might be right for you. ● Or use both, if you could benefit from both approaches a lot.

Slide 44

Slide 44 text

Thanks for listening! Questions?