REST vs GraphQL: The What, How and Why

What they are, how they differ and when to use each, or both.

Transcript

1. REST vs GraphQL The What, How and Why Berlin PHP Usergroup, November 7 2017
2. 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
6. Is REST really dead?
7. What is REST? • REpresentational State Transfer • 2000, Roy Fielding’s PhD dissertation • Architectural concept for network-based software
8. 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)
9. /users // all users /users/1 // user with the ID “1” /users/1/avatar // user 1’s avatar
10. 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)
11. // 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
12. 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)
13. 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)
14. { "userId": 2, "name": "Leeroy Jenkins", "links": [ { "href": "/users/2/high-scores", "rel": "high-scores", "type" : "GET" } ] }
15. 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
16. 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!
17. Querying Data POST /graphql { user(id: "2") { name, birthdate, username } } 200 OK { “data”: { “user”: { “name”: “Leeroy Jenkins”, “birthdate”: “1995-07-13”, “username”: “foobar” } } }
18. 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” } } }
19. 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"}} ] } } } }
20. 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!
21. 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!
22. 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!
23. Mutations POST /graphql mutation CreateReviewForEpisode( 1: Episode!, {“stars”: 5}: ReviewInput! ) { createReview( episode: 1, review: {“stars”: 5} ) { stars } } 200 OK { "data": { "createReview": { "stars": 5 } } }
24. 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!
25. Core Differences REST • Architecture for APIs • Utilizes HTTP to the fullest GraphQL • Query language • Uses HTTP as a “dumb” data transfer mechanism
26. Core Differences REST • Architecture for APIs • Utilizes HTTP to the fullest GraphQL • Query language • Uses HTTP as a “dumb” data transfer mechanism
27. 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
28. GET /users/1 PUT /users/1/avatar POST /users/1/highscores … // It’s inherently obvious what’s going on
29. POST /graphql POST /graphql POST /graphql …
30. 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
31. 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
32. 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
33. 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
34. 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
35. 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
36. 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
37. Core Differences REST • Architecture for APIs • Utilizes HTTP to the fullest GraphQL • Query language • Uses HTTP as a “dumb” data transfer mechanism
38. 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
39. 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
40. 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
41. 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
42. 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
43. 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.
44. Thanks for listening! Questions?