GraphQL vs. REST

A presentation about trade-offs in Web APIs

GraphQL is a great tool for front-end developers who now can retrieve any kind of data in their application in the format they want. However, REST always promised us a better user-perceived performance, better interoperability, better scalability of the entire architecture, and so forth. Can GraphQL be designed in such a way that it follows the REST constraints?

In this presentation we advocate for the GraphQL query to be solved on the client-side, while a JavaScript framework dynamically checks the server for how the data fragments are structured through hypermedia. The presentation is not about GraphQL in specific, but more about thinking thoroughly about how you design your Web APIs to last. A final example is given that goes way beyond GraphQL: open world client-side querying for route planning.

Demos in this presentation

* http://query.linkeddatafragments.org/
* https://hdelva.be/slides/sotm2019/#/
* https://planner.js.org/example.html

Interesting further read if you’re interested in GraphQL: “Linked Data Querying with GraphQL” https://comunica.github.io/Article-ISWC2018-Demo-GraphQlLD/ GraphQL-LD

Other links from this presentation:
* The JSON-LD playground: https://json-ld.org/playground/
* RDF Mapping Language RML http://rml.io/yarrrml/matey/
* Linked Data from Flanders https://data.vlaanderen.be
* https://linkedconnections.org

Transcript

1. GraphQL vs. REST Let’s talk Web APIs Pieter Colpaert Ghent University – IDLab – imec Open Knowledge Belgium
2. https://pietercolpaert.be
3. https://pietercolpaert.be But oranges are obviously better
4. Client: Give me all the things HTTP /thing1 HTTP /thing2 HTTP /thing3 Client: Give me all the things HTTP /graphql?q={thing1,thing2,thing3} joins happen on the client joins happen on the server-side GraphQL: a convenience tool for front-enders
5. https://pietercolpaert.be Data dumps Smart servers Entire query languages over HTTP Subject pages HTTP API Smart agents Yet, what do we want the server to do?
6. https://pietercolpaert.be Data dumps Smart servers Entire query languages over HTTP Dataset split in fragments Smart agents algorithms as a service Other solutions possible? Subject pages HTTP API
7. Client: Give me all the things {thing1,thing2,thing3} joins happening on the client-side, but the front-end developer doesn’t have to know HTTP /thing1and2 HTTP /thing3
8. Client: Give me all the things {thing1,thing2,thing3, ...} And… Why even stick to your own server? HTTP /thing1and2 HTTP /thing3 To the Web and beyond!
9. Towards automated data integration and why GraphQL needs REST
10. https://pietercolpaert.be What did we do? We made the datasets interoperable on 3 levels: 1. Syntactic 2. Semantic 3. Querying And query them using e.g., Comunica (http://query.linkeddatafragments.org)
11. https://pietercolpaert.be What did we do? We made the datasets interoperable on 3 levels: 1. Syntactic 2. Semantic 3. Querying Fixed this using “Linked Data”
12. https://pietercolpaert.be name type city population Gare du Nord Station Paris 2.2m { "Gare du Nord" : { "type" : "Station", "city" : { "name": "Paris", "population":"2.2m" } } } <Garedunord> <type>Station</type> <city name="Paris"> <population> 2.2m </population> </city> <Garedunord> Table / CSV / Spreadsheet JSON XML Serialisations
13. https://pietercolpaert.be <Gare du Nord> <type> <Station> . <Garedunord> <city> <Paris> . <Paris> <population> “2.2m” . Table / CSV / Spreadsheet 3 time a datum Triples – Resource Description Framework (RDF 1.1) { "Gare du Nord" : { "type" : "Station", "city" : { "name": "Paris", "population":"2.2m" } } } <Garedunord> <type>Station</type> <city name="Paris"> <population> 2.2m </population> </city> <Garedunord> JSON XML name type city population Gare du Nord Station Paris 2.2m
14. https://pietercolpaert.be World Wide Web Garedunord city Paris Gare du Nord type Station Paris population 2.2m HTTP Machine 1 HTTP Machine 2 HTTP Machine 3 The Web: a decentralized data ecosystem A user agent visiting each machine knows more than any of the machines independently E.g., data.sncf.com E.g., transport.data.gouv.fr E.g., wikipedia.com
15. https://pietercolpaert.be Solution Gare du Nord → http://www.wikidata.org/entity/Q745942 is a → http://www.w3.org/1999/02/22-rdf-syntax-ns#type Station → http://vocab.gtfs.org/terms#Station Uniform Resource Identifiers (URIs)
16. https://pietercolpaert.be 1. Describes how to express triples in different serializations (RDF) 2. Introduces global identifiers (HTTP URIs) for domain models and their instances Linked Data
17. https://pietercolpaert.be Hahahahahaha You will never get governments to actually do that
18. https://pietercolpaert.be But they are already doing that: data.vlaanderen.be Flemish buildings, addresses, domain models, organizations, … with their official URIs published as Open Data
19. https://pietercolpaert.be Hahahahahaha Writing full URIs everywhere is way too difficult!
20. https://pietercolpaert.be Meet JSON-LD! { "@context": "http://schema.org/", "@type": "Person", "name": "Jane Doe", "jobTitle": "Professor", "telephone": "(425) 123-4567", "url": "http://www.janedoe.com" }
21. https://pietercolpaert.be Or RML.io Maps unstructured data to Linked Data http://rml.io/yarrrml/matey/
22. https://pietercolpaert.be Another great starting point wikidata.org Wikipedia, but for triples!
23. https://pietercolpaert.be What did we do? We made the datasets interoperable on 3 levels: 1. Syntactic 2. Semantic 3. Querying Fixed this using Linked Data! ???
24. https://pietercolpaert.be Let’s apply this to route planning
25. http://api.{mycompany}/?from={A}&to={B} &departuretime=2019-03-27T12:02.024Z &wheelchairaccessible=true &transit_modes=plane,railway,bus,car &algoritm_mode=shortest ... This interface will need to answer all questions for all third party apps…
26. https://pietercolpaert.be data dump Route planning algorithms as a service Asking questions Your system 3d party Your system ? ? ? ? ? ? Does not scale: Extra users comes with extra load Does not give necessary flexibility to companies
27. https://pietercolpaert.be Page X Page ... Page 2 Page 1 time next next Publishing time schedules in fragments on the Web
28. https://pietercolpaert.be http://linkedconnections.org
29. https://pietercolpaert.be Publishing roads in tiles Demo: https://hdelva.be/slides/sotm2019/#/
30. https://pietercolpaert.be Both together https://planner.js.org/example.html ⇒ an SDK for front-end developers
31. https://pietercolpaert.be Take-aways 1. Try to fit your Linked Data in 1 HTTP response 2. If it doesn’t fit, a. fragment your data in multiple resources b. Base your fragmentation on the same way as adding an index in a database c. Add hypermedia links so your clients automatically understand it’s now fragmented 3. Let the client do more, but hide this from your front-enders through SDKs Oh, and for the record REST is not the enemy of GraphQL ;)