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
   

   View Slide

2. https://pietercolpaert.be
   

   View Slide

3. https://pietercolpaert.be
   But oranges are
   obviously better
   

   View Slide

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
   

   View Slide

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?
   

   View Slide

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
   

   View Slide

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
   

   View Slide

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!
   

   View Slide

9. Towards automated data
   integration
   and why GraphQL needs REST
   

   View Slide

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)
    

    View Slide

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”
    

    View Slide

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"
    }
    }
    }
    
    Station
    
    
    2.2m
    
    
    
    Table / CSV / Spreadsheet
    JSON XML
    Serialisations
    

    View Slide

13. https://pietercolpaert.be
    .
    .
    “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"
    }
    }
    }
    
    Station
    
    
    2.2m
    
    
    
    JSON XML
    name type city population
    Gare du Nord Station Paris 2.2m
    

    View Slide

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
    

    View Slide

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)
    

    View Slide

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
    

    View Slide

17. https://pietercolpaert.be
    Hahahahahaha
    You will never get governments to
    actually do that
    

    View Slide

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
    

    View Slide

19. https://pietercolpaert.be
    Hahahahahaha
    Writing full URIs everywhere
    is way too difficult!
    

    View Slide

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"
    }
    

    View Slide

21. https://pietercolpaert.be
    Or RML.io
    Maps unstructured data to Linked Data
    http://rml.io/yarrrml/matey/
    

    View Slide

22. https://pietercolpaert.be
    Another great starting point
    wikidata.org
    Wikipedia, but for triples!
    

    View Slide

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!
    ???
    

    View Slide

24. https://pietercolpaert.be
    Let’s apply this to route planning
    

    View Slide

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…
    

    View Slide

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
    

    View Slide

27. https://pietercolpaert.be
    Page X
    Page ...
    Page 2
    Page 1
    time
    next
    next
    Publishing time schedules in fragments
    on the Web
    

    View Slide

28. https://pietercolpaert.be
    http://linkedconnections.org
    

    View Slide

29. https://pietercolpaert.be
    Publishing roads in tiles
    Demo:
    https://hdelva.be/slides/sotm2019/#/
    

    View Slide

30. https://pietercolpaert.be
    Both together
    https://planner.js.org/example.html ⇒ an SDK for front-end developers
    

    View Slide

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 ;)
    

    View Slide