apidays LIVE Australia 2020 - Have your cake and eat it too: GraphQL? REST? Why not have both! by Roy Mor
Download as PPTX, PDF0 likes1,129 views
The document discusses the benefits of using GraphQL and REST APIs, highlighting how GraphQL can enhance development velocity and user experience by allowing clients to specify their data needs directly. It presents a solution, graphql2rest, which automatically generates a REST API from a GraphQL schema, eliminating the need for separate code bases while maintaining functionality. The conclusion emphasizes that while GraphQL offers advantages, especially for internal APIs, there are considerations and potential drawbacks for public API implementations.
apidays LIVE Australia 2020 - Have your cake and eat it too: GraphQL? REST? Why not have both! by Roy Mor
- 1. GraphQL? REST API? Or maybe you can have both! Roy Mor @RoyMorTech
- 3. GraphQL? REST API? Or maybe you can have both! Roy Mor @RoyMorTech
- 4. Have your cake and eat it too?
- 5. Roy Mor Tech Lead at Sisense linkedin.com/in/roy-mor/ @RoyMorTech
- 14. Choosing an internal API paradigm for your tech stack:
- 17. Schema describes the shape and relationships of the data Client queries use the types defined in the schema GraphQL API responses are regular JSON – just like REST responses
- 18. • Avoids under-fetching: single round trip (instead of multiple requests in REST) • Avoids over-fetching: client specifies exactly the fields it needs
- 19. • Increased velocity for our development teams • Once the schema is set – frontend and backend teams can work independently • Clear communication, less meetings, schema is single-source-of-truth, changes are easy • Better developer experience for front-end devs: • No more post-processing on API responses • ”Free” (built-in) validation and auto-documentation – due to GraphQL type system • Better UI performance: reduced payloads and roundtrips
- 20. API as data query language • Schema based • Strongly typed • Self documenting & built-in input validation • Client centric: client specifies exactly what data it needs • Better developer experience, faster development cycles • Better performance: smaller payloads & fewer roundtrips
- 22. Got API?
- 23. O GraphQL API!
- 24. …but the world still wants a REST API!
- 26. REST APIs • The “de facto standard” for companies deploying APIs and developer platforms • Proven for decades in large scale • For user: simple to use, uniform interface, doesn’t require special libraries, common knowledge • Leverages HTTP semantics, conventions and logic
- 28. • We have an existing internal GraphQL API • We need to expose an external REST API with the same functionality Offer REST & GraphQL concurrently, running side by side Problem Statement
- 29. 1. Develop REST API manually from scratch? 2. Manually wrap GraphQL API with REST? Our options It’s just not cost-effective to develop, test and maintain two code paths with the same functionality, and keep them in parity over time.
- 32. GraphQL2REST is a Node.js library that reads your GraphQL schema and automatically generates an Express router with fully RESTful HTTP routes —a full-fledged REST API.
- 33. • Creates REST endpoints based on GraphQL schema and a manifest file that you edit • Full customization: your REST API could be very different than your GraphQL layer
- 34. github.com/sisense/graphql2rest graphql2rest on npm We open sourced it:
- 35. We automatically generated a truly RESTful API without writing a single line of API code
- 38. Pre processing step: generateGqlQueryFiles() • One-time only step; can be run at “build time”, or by script
- 40. ”Fully exploded” GraphQL client queries – saved as files
- 42. ç
- 43. Manifest describes all REST endpoints, customizations and mapping to GraphQL operations ç
- 45. At Runtime:
- 46. At Runtime:
- 47. At Runtime:
- 48. At Runtime:
- 49. At Runtime:
- 50. At Runtime:
- 51. At Runtime:
- 53. GraphQL2REST: manifest.json • Describes all REST endpoints and mapping rules to GraphQL operations In REST HTTP: GET /tweets/1234 (200 OK) GraphQL: getTweetById(id: 1234)
- 54. GraphQL2REST: manifest.json • Describes all REST endpoints and mapping rules to GraphQL operations In REST HTTP: GET /tweets/1234 (200 OK) HTTP route path HTTP method GraphQL: getTweetById(id: 1234) GraphQL operation to map to
- 55. GraphQL2REST: manifest.json GraphQL operation name Rename parameters Customize status code Allow flat REST request body Omit fields from REST response PATCH /users/1234 | body = {"name": "Joe", "birthday": "1990-1-15"} 202 Accepted Mutation updateUserData(userOid: UUID!, newData: userDataInput!): User
- 56. Exposes two public functions: • generateGqlQueryFiles() - schema pre-processing • init() - generate Express router at runtime
- 58. Demo Time!
- 60. End Demo
- 61. GraphQL2REST o Works with any type of GraphQL server (local, remote, apollo-link, fetch….) o Customize (almost) everything o Response format o Error format o Status codes (for errors too) o Parameter names and mappings o Map a single REST endpoint to multiple GraphQL operations o Hide fields o Built-in filter for client o And more….
- 62. We automatically generated a truly RESTful API without writing a single line of API code
- 63. Should you choose GraphQL or REST for your public API?
- 64. Why choose GraphQL for your INTERNAL API? • Increased velocity for development teams • Once the schema is set – frontend and backend teams can work independently • Clear communication, less meetings, schema is single-source-of-truth, changes are easy • Better developer experience for front-end devs: • No more post-processing on API responses • ”Free” (built-in) validation and auto-documentation • Better UI performance: reduced payloads and roundtrips, easier for multi-client
- 65. Why not GraphQL? • Doesn’t shine in ALL use cases • Caching is not straightforward (HTTP POST) – requires extra libraries • Error handling – errors are ambiguous (compare to REST) • File upload is not straightforward • Solution: base64? Extra libraries? • Security: exposed to DOS attacks because the client has the control • Solution: maximal query nesting level, timeouts, rate limits… needs configuration • Schema is public, so no “internal”, “hidden”, “private” endpoints for sensitive queries • No conventions like in REST – it’s on US to implement or use extra libraries Everything has a proper solution! Just not out-of-the-box
- 66. There’s a strong case for using GraphQL as an internal API. Is the world ready for GraphQL Public APIs? (what is the difference anyway…)
- 69. Effects of going for GraphQL Public API • “Since our application engineers are using the same GraphQL platform that we’re making available to our integrators, this provides us with the opportunity to ship UI features in conjunction with API access. Using GraphQL on the frontend and backend eliminates the gap between what we release and what you can consume.” – GitHub
- 70. Possible Issues with Public GraphQL API “GraphQL is client-centric, not server-driven”: • GraphQL moves too much of the burden to the user of the API • “Query building is tedious”, “frustration”, “unnecessarily complex compared to good ol’ REST” • Large learning curve for teams/people who might not be interested in using GraphQL • The internal team would have a vested interest in introspecting the API but an external developer might not. • Top client-side performance requires using external libraries • Is this an error or not? ”Lost exceptions”, partial errors, monitoring becomes not straightforward • Using REST = familiar framework = minimize ”business risk” (De-risking)
- 71. Public APIs: GraphQL vs REST – any conclusion? • GraphQL is a great technology, but not a silver bullet • Good tech reasons to choose GraphQL, but also other considerations: • Market penetration • Public API user preferences, habits, needs, skills • Take a leap of faith like GitHub? • Gather information, survery our customers / developers?
- 72. We automatically generated a truly RESTful API without writing a single line of API code
- 74. Roy Mor ([email protected]) Thank You!