The GraphQL Way: A new path for JSON APIs

Talks

Nick Quaranto

#client-side-rendering

#developer-experience-dx

#caching

The GraphQL Way: A new path for JSON APIs

by Nick Quaranto

In "The GraphQL Way: A new path for JSON APIs," presented at RailsConf 2018 by Nick Quaranto, the video explores the challenges of traditional RESTful JSON APIs in Rails and proposes GraphQL as an effective alternative.

Key Points:

- Introduction to GraphQL:

- GraphQL is a query language for APIs, designed to overcome common REST issues such as endpoint explosion and low data discoverability.

- It was developed by Facebook in 2012 and open-sourced in 2015, becoming increasingly popular among companies like GitHub and Shopify.

**Challenges with REST APIs and JSON:
- Traditional REST APIs can lead to difficult-to-manage code, versioning problems, and inefficient data fetching methods.
- JSON while useful, does not solve the underlying limitations of RESTful architecture.
GraphQL Features:
- Strong Typing: Ensures all data inputs and outputs are clearly defined, reducing runtime errors due to incorrect data types.
- Change Resilience: APIs can evolve without the need for versioning, allowing for the addition and depreciation of fields while maintaining backward compatibility.
- Introspection: Developers can explore API types and structures through tools like GraphiQL, allowing easier debugging and documentation.
Integration with Existing Rails Applications:
- Quaranto emphasizes that integrating GraphQL requires a rethink of the application's architecture, especially in separating data presentation from logic.
- The GraphQL Ruby gem streamlines the integration process, providing tools to define types, schemas, and execute queries and mutations.
Pitfalls of GraphQL:
- Lack of built-in error handling necessitates the use of additional gems to manage exceptions.
- Performance issues, like the N+1 problem, can occur if not handled properly. Batch loading strategies and caching can mitigate these concerns.

Conclusion:

GraphQL presents a modern and robust alternative for building APIs in Rails, particularly for new applications. Its strong typing, change resilience, and developer-friendly tools create an enhanced experience for both developers and users. However, careful consideration of application architecture and performance patterns is essential to successfully implement GraphQL in existing systems.

00:00:11.210 Good morning! I'm going to start talking because I have a lot to discuss. Please find a seat; you can come up here and sit down. Seriously, you can make it like a campfire-type gathering, so come sit and don't stand. I'm going to be talking a lot.

00:00:30.619 Alright, I'm going to get rolling here. We're in the GraphQL talk. Let's see if this works... oh, here we go! I got it to work. My phone works.

00:00:43.170 You have to reconsider the basics of GraphQL as we approach 2018. That's the last keynote animation I'll subject everyone to. I'm sorry I don't have a lot of gifts for my talk this year, but I do have these really cute animals, so you're going to have to deal with that.

00:01:01.500 My name is Nick Quaranto. You can find me on the internet as @kewrush on Twitter. I used to have that Instagram account, but I deleted it out of rage, and a Russian guy stole it. So, the real lesson for you today is: Don't delete your Instagram account if you want to keep it.

00:01:22.409 You might know me from making what is now called rubygems.org or GemCutter; I've talked a lot about that in the past. I'm not talking about it today, but I'm happy to help you with any gem problems you may have. Currently, I work for a company called Chatterbug. We're a language learning company based in San Francisco and Berlin, started by a few of the GitHub co-founders.

00:01:48.720 Now we have about a dozen people, and we’re focused on teaching languages. I want to talk about this just a little, as it helps frame the problems we're about to discuss. Currently, we teach English speakers three languages: German, and soon Spanish and French.

00:02:12.660 We have our cute little student band on top and our tutor bear or tutor owl on the bottom. Hopefully, by the end of the year, we will have a marketplace-type model where you can teach a language simply by being a native speaker of English, French, or whatever you know, and then learn another language, too.

00:02:38.450 The cool thing about the platform is that if you've ever used a language learning app, you don't get to speak much. So we combined memorization-type apps with live lessons. You actually have a 45-minute session with another real human being to converse in a different language. It's a really fun experience!

00:02:56.609 I've participated in maybe 30 lessons, both in Spanish and German, and it has challenged me greatly. I took Spanish in high school, but this is on a whole new level of learning. All of this is done from a tech perspective. We are on Rails, using WebRTC, and we leverage Action Cable for cool screen sharing and chat features.

00:03:14.790 One of the things we wanted to do in the past year was to create a mobile app. This is really important because if you're on the run, you want to be able to quickly look at some words to prepare for your next live lesson. We needed a mobile app for that, and we looked at the state of APIs to start from scratch.

00:03:38.730 We already had some APIs, but we really wanted to take a deep dive, and we decided to explore GraphQL. So today, I'll talk about what GraphQL is and share some of the challenges we faced along the way. If you don’t know anything about GraphQL, you’re in for a great introduction in the next 30 minutes.

00:04:01.390 There’s also a workshop tomorrow, although I forget the exact time; it’s in your schedule. If you really want to dig in, I suggest signing up for that. But for now, you're going to get a good intro to GraphQL. I want to thank the organizers for moving things around so we could attend both sessions.

00:04:27.210 I'm going to show you how you can implement GraphQL in your application with some examples from our experience. Then I’ll discuss some potential pitfalls we encountered that we are still digging ourselves out of. So let's dive back into the core problem.

00:04:37.890 The problem we're facing is I have a mobile app that needs to communicate with my server—our server, in this context—and as for Rails, it's a very vanilla setup. We use Webpack and React. By the way, Webpack is great, and React is like any app that's existed for any amount of time; it's not all React.

00:05:14.460 We have a lot of JSON APIs. This is something Rails does very well! You can easily get started with a JSON endpoint to dynamically display content on your page. I really like JSON, but I will soon discuss why it isn't perfect.

00:05:42.640 I want to make it clear that I think JSON is a great format, and a lot of the issues aren't with JSON itself, but with REST. If you listened to Dave's keynote, he talked about how REST is a great thing Rails implemented, but there are many problems with REST.

00:06:07.080 For example, there's often an endpoint explosion, meaning you have countless HTTP endpoints to maintain, and your users must understand them. This can lead to expensive round trips. If my network is poor and I’m trying to make many fetch requests, that degrades the app experience and can be costly for the user.

00:06:47.400 Moreover, data discoverability is low. It's hard for developers to understand what the API does. There's not a great developer experience, which is less than ideal. Certainly, backward compatibility is often not considered; I've previously talked about the necessity of a v1 API controller, yet every API has different ways of handling versioning.

00:07:12.259 None of this is built into Rails or JSON APIs, making it something you have to learn and deal with repeatedly. These problems tend to accumulate and lead to frustration. As I looked at all of this, I wondered if we could do things differently and hopefully not repeat these issues.

00:07:46.370 So, let's communicate about GraphQL. I consider myself a bit of a software historian. While others in the JavaScript community have done a better job discussing its history, I'll focus on what matters most to us here today.

00:08:04.080 The main point is that GraphQL was started by Facebook in 2012 to implement their newsfeed. It has since grown internally at Facebook, and in 2015, it was open-sourced. There’s fantastic documentation available for GraphQL and the libraries supporting it in various languages, including Ruby.

00:08:26.400 If you ever need to present GraphQL to your boss, you can highlight that many companies are already using it. Facebook is an obvious example, but other organizations such as GitHub and Shopify also utilize it effectively.

00:08:51.220 I think GraphQL fits nicely into various use cases, especially if you're developing a mobile app or starting from scratch. React Native is a good match, and there’s a great NPM package called Apollo that integrates seamlessly with GraphQL. If you're just making a single-page app, GraphQL can also work well.

00:09:29.800 In general, wherever a JSON API could be beneficial, GraphQL could be applied, although especially with how well Rails handles JSON APIs, you may choose to stick with those instead.

00:09:55.090 So, what exactly is GraphQL? I wanted to clarify this early on. GraphQL is a query language. Essentially, when you build an application, this is the query that you will construct to ask your server for information. Your client, whether on a phone or webpage, will build this request and submit it to your server.

00:10:36.870 The query contains a `currentUser` field, along with multiple subfields such as ID and others needed to display a dashboard or student details. The response will come back in JSON. The real game-changer is that you’re building a query language to ask for your data, and this approach holds numerous benefits.

00:11:16.370 Under the hood, you should not have to interact with complex data manipulation; if you're using a GraphQL client, it parses these requests and serves them in the preferred format. Importantly, this isn't a new format; it's just a different way of asking for data.

00:11:45.540 In case you were wondering, GraphQL is still fundamentally JSON. One of the major advantages is that it's strongly typed—this means that all the input and outputs must be declared and typed. If you've encountered issues in your Rails application, you've likely faced challenges with input validation.

00:12:08.330 GraphQL provides strict type enforcement, meaning it handles a lot of problems you previously had to manage, like dealing with unexpected Boolean or date formats from incoming requests. In GraphQL, everything is handled by type definitions.

00:12:55.130 Another great aspect is GraphQL's change resilience, allowing your API to evolve without breaking existing functionality. If your deployment needs to accommodate new requirements, the system has provisions for handling this gracefully, which can reduce friction in development.

00:13:31.040 In traditional coding discussions, there may be uncertainty regarding how to perform pagination. GraphQL simplifies this process—particularly on the Ruby side with Apollo—by providing built-in functionality, eliminating time-consuming debates about data retrieval strategies.

00:14:04.769 When programming in Rails, there's a familiar principle of convention over configuration, which enhances developer workflow. With GraphQL, you enable your team to focus on building applications rather than worrying over pagination techniques since the system handles that internally.

00:14:45.760 One of the coolest features is the introspection capability built into GraphQL. This means everything you build can be inspected. For example, a great console tool provided with the Ruby gem allows for direct interaction with your queries, responses, and data processing.

00:15:13.690 Additionally, there's a helpful visual aspect resulting from using GraphQL. The query you're constructing doesn’t need to follow rigid format specifications. This flexibility provides a fantastic sandbox for exploring and testing your API without needing to know its inner workings. You can dive right in!

00:15:47.919 GraphQL requests typically resemble how we've handled data fetching in the past, just treated as a simple process of forwarding the query to the server. However, it’s important to highlight that GraphQL does not function as REST does and operates under a different paradigm.

00:16:17.650 It's crucial to understand that we're solving many of the aforementioned pitfalls with a novel approach. We need to carefully consider how we structure our API to reap the most benefits from GraphQL's functionalities. We may lose some of REST’s elegant HTTP semantics, such as using GET requests to retrieve data.

00:16:46.350 What does GraphQL’s typing look like? GraphQL relies heavily on types. Each input and output must have an associated type. For instance, a request for data corresponds to the query type, while modifications correspond to the mutation type.

00:17:16.499 We can see an example of how this plays out with a user type or updates to a user’s mutation type where changes to data are strongly typed, maintaining a uniform structure throughout the entire API.

00:17:44.370 GraphQL includes a powerful tool called GraphiQL, which allows developers to write queries and retrieve API documentation side by side. This significantly streamlines the development process by providing an interactive interface to explore and test the API.

00:18:13.130 GraphiQL aids in learning how to communicate with the API while providing a growing history of previous queries. Documentation accompanies the interactive environment, making it easier to share changes and communicate updates to the development team.

00:18:37.970 With GraphQL, you won't need to version your API anymore. Instead, you can extend your existing queries seamlessly. This means you won't have to deal with cumbersome v2 APIs or unnecessary overhead.

00:19:06.840 For example, if I log into my app and want to display my upcoming language lessons, I can simply add fields to my existing queries without rebuilding or altering significant portions of my API.

00:19:29.119 GraphQL also addresses potential security concerns. While it’s important to avoid infinite nesting of queries—which could lead to denial of service—developers can set limits on nesting levels as an additional precaution.

00:19:51.950 Underneath all this, GraphQL still communicates in JSON. So if you run these queries through the web inspector, you can see JSON in action.

00:20:12.340 While GraphQL simplifies many of the technical processes we’ve used, one challenge is the lack of a built-in data model, meaning we write specific connectors from GraphQL queries to our databases. This is a straightforward process within Rails.

00:20:37.570 However, one major caveat is the absence of built-in authorization and authentication features. The responsibility for this lies entirely with the developer, and it's recommended to perform authentication processes at the controller level.

00:21:02.950 Testing can be tricky, especially with integration testing for GraphQL applications. Nonetheless, I recommend testing custom logic embedded within your resolvers and treating types as framework code.

00:21:51.920 So while you want to ensure that the types that map to the database work appropriately, focus testing on the business logic residing in your resolver functions to confirm the implementation details are functioning correctly.

00:22:21.610 Another potential pitfall lies in how GraphQL handles errors. By default, error handling is quite basic, which can be bewildering; therefore, I recommend utilizing a gem that provides error handlers to ensure your application manages unexpected outcomes gracefully.

00:23:05.949 Also, due to GraphQL's asynchronous nature, you may encounter N+1 performance issues, which can slow down data retrieval significantly. Fortunately, the GraphQL Ruby community has crafted gems that help mitigate improper performance by batching requests to optimize data fetches.

00:23:37.410 Caching remains a central concern in GraphQL, especially since REST-based HTTP caching mechanisms are not directly applicable. But Rails has built-in caching frameworks, like Redis and memcache, that function perfectly with GraphQL.

00:24:24.470 By combining these features with caching, you can achieve impressive performance improvements, especially for expensive resolve functions, while maintaining structured data and reducing overhead.

00:25:07.460 In summary, GraphQL offers a fresh perspective for building JSON APIs within Rails applications. Adopting its principles can yield significant benefits, especially for new applications or projects aiming for rapid iteration.

00:25:51.799 The industry is trending towards adopting GraphQL, showing that evolving an application using this framework and empowering your development team could lead to a more enjoyable experienceOverall, GraphQL offers a transformative structure for maintaining clean, robust, and efficient data interactions.

00:26:31.480 If you build your app with intentional, clear layers separating your model from presentation, GraphQL naturally fits into modern Rails workflows. Its wide acceptance and the flexibility it provides will empower you and your team to create amazing applications.

00:27:18.320 To conclude, thank you for your attention! If you have any queries, I’m here for questions or clarifications afterward. Remember, we are now walking a path where your experience with APIs can be much more enjoyable than before!

See Slides on speakerdeck.com

RailsConf 2018