apidays LIVE Australia - Building Business Ecosystems Have your cake and eat it too: GraphQL? REST? Why not have both! Roy Mor, Technical Lead at Sisense

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

27. O
(Yonatan Maman)

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:

52. 200 OKAt 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…)

67. GraphQL Public APIs

68. GraphQL Public APIs

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

73. github.com/sisense/graphql2rest
npm: graphql2rest
Roy Mor
roy.mor@sisense.com
linkedin.com/in/roy-mor/
RoyMorTech
Thank You!

74. Roy Mor (roy.mor@sisense.com)
Thank You!

75. Q&A
Roy Mor (roy.mor@sisense.com)
https://www.linkedin.com/in/roy-mor/
https://github.com/sisense