[MadScalabilty] RESTful APIs are dead, long live GraphQL

Transcript

1. RESTful APIs are dead, long live GraphQL José María Rodríguez Hurtado @durbon chema@durbon.com 1 #madScalability
2. Overview Reviewing RESTful Problems working on product with APIs GraphQL 2
5. ¿Using REST correctly? Nick Schrock. React London Meetup. 2015 5
6. Reviewing RESTful API Three main principles 6
7. Main principles API REST - Define separate resources. Accessible via URI - These resources are manipulated using HTTP requests where the method (GET, POST, PUT, PATCH, DELETE) has specific meaning. - Discover resources, thanks to HATEOAS (Hypertext As The Engine Of Application State). 7
8. API RESTFul Endpoint resources GET /posts - Retrieves a list of posts GET /posts/12 - Retrieves a specific post GET /posts/12/comments - Retrieves comments GET /posts/12/comments/42/ - Retrieve specific comment POST /posts - Creates a new post PUT /posts/12 - Updates post #12 with payload provided PATCH /posts/12 - Partially updates post #12 DELETE /posts/12 - Deletes post #12 8
9. Example Payload JSON { "name": "Luke Skywalker", "height": "172", "mass": "77", "hair_color": "blond", "skin_color": "fair", "eye_color": "blue", "birth_year": "19BBY", "gender": "male", "homeworld": "http://swapi.co/api/planets/1/", "films": [ "http://swapi.co/api/films/6/", "http://swapi.co/api/films/3/", "http://swapi.co/api/films/2/", "http://swapi.co/api/films/1/", "http://swapi.co/api/films/7/" ], "species": [ "http://swapi.co/api/species/1/" ], "vehicles": [ "http://swapi.co/api/vehicles/14/", "http://swapi.co/api/vehicles/30/" ], "starships": [ "http://swapi.co/api/starships/12/", "http://swapi.co/api/starships/22/" 9
10. Working with APIs Product → Design → Engineering 10
11. Excessive Round Trips Client - Server R 11
12. Payload and bandwidth 12
13. /filmsWithDirectorAndTag /filmsWithPrincipalsCharacter /filmSummaries/1 /filmsDetails/1 /filmSummaryWithActors/1 Custom Endpoints (aka “spaghettification”) 13
14. Versioning APIs: breaking changes 14 What is the correct way to version my API? - The URL way? /api/v1/post/12232 V2, v3, v4….?? - The Header way? GET /api/article/1234 HTTP/1.1 Accept: application/vnd.api.article+xml; version=1.0
15. Why not like REST? - Most REST API are really Ad-hoc RPC with custom endpoint definitions. Time spent maintaining many versioned endpoint - REST requires many requests (many Roundtrips) - With REST, you request too much or too little data REST often turns into a maze of poorly-documented endpoints - Weak Typing and Poor Metadata 15
17. GraphQL isn't a new technology. Facebook: It has been delivering data to mobile News Feed since 2012 17
19. GraphQL is a query language, like SQL? You don’t connect GraphQL directly to your backend or database. It’s an API layer, just like REST. GraphQL can be layered over multiple backends and databases, without the client being aware of where the data is coming from, just like REST. 19
20. “GraphQL is a query language designed to build client applications by providing an intuitive and flexible syntax and system for describing their data requirements and interactions.” - GraphQL Specification https://facebook.github.io/graphql/ 20
21. Single Endpoint /graphql 21
23. Query Language “hello world” Query { me { name } } { "me": { "name": "@durbon" } } 23
24. { author(id: 27) { name profilePics { width height url } } } { "author": { "name": "@durbon" "profilePics" : { "width": 250, "height": 250, "url": "http://avatarurl.com/250.jpg" } } } Ask for you want 24
25. { author(id: 27) { name profilePics(size: 640) { width height url } } } { "author": { "name": "Txema Rodríguez" "profilePics" : { "width": 640, "height": 640, "url": "http://avatar.com/640.jpg" } } } Ask for you want 25
26. { author (id: 27) { name, licPic: profilePics (size: 90){ width, height, url }, bigPic: profilePics (size: 800){ width, height, url } } } "author": { "name": "Txema Rodríguez" "licPic" : { "width": 90, "height": 90, "url": "http://avatar.com/90.jpg" }, "bigPic" : { "width": 800, "height": 800, "url": "http://avatar.com/800.jpg" } } } Ask for you want 26
27. Nested connection resources { me { name posts { title } } } { "me": { "name": "@durbon" "posts" : [ { title: "GraphQL is cool" }, { title: "API REST is dead" }, { title: "Scalability rocks!" },.. 27
28. { latestPost { title, author { name, twitter } }, authors { name } } { "data": { "latestPost": { "title": "¿Por qué deberíamos abandonar REST?", "author": { "name": "Txema Rodríguez", "twitter": "@durbon", } }, "authors": [ { "name": "Txema Rodriguez" }, { "name": "Dummy Blogger" } ] } } 28 Combining Queries
30. Mutation: also you can write using GraphQL: Mutations are the way to allow GraphQL clients(or external parties) to modify your dataset. mutation writePost { post: createPost( title: "GraphQL is Awesome", content: "Yep, it's awesome." ) { _id, Title } } 30
31. GraphQL Core principles 31
32. Type System GraphQL schema language it's similar to the query language, and allows us to talk about GraphQL schemas in a language-agnostic way. 32
33. Schemas and types - Object types and fields - Scalar types: Int, Float, String, Boolean, ID - Lists and Non-Null - Arguments: Every field on a GraphQL object type can have zero or more arguments - Enumeration types: a special kind of scalar that is restricted to a particular set of allowed values 33
34. Contract Client Backend Possibilities GraphQL Type System GraphQL Schema Requirements GraphQL Languages Queries Mutation App Server View 34
35. Schema type Query { me: Author author (id: Int): Author } type Author { name: String profilePicture(size: Int = 50): ProfilePicture followers: [Author] } type ProfilePicture { width: Int! height: Int! url: String! } 35
36. Error Handling { errors: [ { message: 'Filed "createPost" argument "title" of type "String!" is required but not provided' } ] } 36
37. Composition GraphQL includes reusable units called fragments 37
38. Fragments fragment authorInfo on Author { _id, name } fragment postInfo on Post { title, content, author { ...authorInfo }, comments { content, author { ...authorInfo } } } { post1: post(_id: "03390abb557) { ...postInfo } } 38
39. TimeLineView HeaderView BodyView fragment headerFragment on User { name profilePicture (size: 250){ url } coverPhoto (size: 1200){ name, url } } fragment bodyFragment on User { location { name } friends } 39 fragment timelineFragment on User { ...headerFragment ...bodyFragment }
40. Introspection Creating documentation, or rich IDE experiences 40
41. IntrospectionQuery query IntrospectionQueryTypeQuery { __schema { queryType { name fields { name description type { name kind } } } } } { "data": { "__type": { "name": "Developer", “Description”: “Name developer” "fields": [ { "name": "id", "type": { "name": null, "kind": "NON_NULL" } }, { "name": "name", "type": { "name": null, "kind": "NON_NULL" } 41
42. Auto documentation Generates API documentation for our consumers, and prevents us from spending precious coding time on documentation. 42
44. Static validation & IDE Integration 44
45. Code Generation 45
46. Execution After being validated, a GraphQL query is executed by a GraphQL server which returns a result that mirrors the shape of the requested query 46
48. Database “Microservices” Remote Services whatever your tech stack Your existing code GraphQL Execution 48
49. Think in Graph, not endpoint Fields independently of each other. Apply different context in order to retrieve such data 49
50. Function Resolver Each field on each type is backed by a function called the resolver which is provided by the GraphQL server developer When a field is executed, the corresponding resolver is called to produce the next value. 50
53. 53 Where we can begin?
54. 54 GraphQL.org
55. Draft RFC Specification for GraphQL https://facebook.github.io/graphql/ 55
56. Reference implementation of GraphQL https://github.com/graphql/graphql-js 56
57. Wrapping a API REST 57
58. Javascript Python (graphene) Scala (sangria) Ruby Java Clojure Go PHP C# .NET Elixir Swift …. graphql.org/code/ 58
59. Client library 59 Relay React iOS Android
60. Public GraphQL APIs 60 Early Github GraphQL API https://developer.github.com/early-access/graphql/explorer/ SWAPI http://graphql.org/swapi-graphql/ More APIs https://github.com/APIs-guru/graphql-apis
61. Benefits of Exposing Data Through GraphQL - Boost your client development: combining and Querying Data and Picking Your Payload - Specification: the spec determines the validity, Strongly Typed, hierachical with nested fields - An application layer. GraphQL is not a storage model or a database query language. - Auto documentation. Yeah!!! 61
62. A new scientific truth does not triumph by convincing its opponents and making them see the light, but rather because its opponents eventually die out, and a new generation grows up that is familiar with it. — Max Planck Are RESTful APIs dead? 62
63. @durbon 63 Thanks, #madscalability!