Powerful REST in a GraphQL world

2020 / ReactConf AU / 29:31

Watch this talk on YouTube

Transcript

34 paragraphs

This is an automatic transcript of the recording above. It is published in full and unedited, apart from correcting names the recogniser reliably mishears. It will contain mistakes.

00:01I'm just going to ignore this part of the room. How are we feeling? Are we good? There was some really good cake out there. I had this thing with caramel or condensed milk. Would have been a little bit better with Vegemite. Anyway, my name is Tejas, pronounced like contagious. Or in light of current events, maybe advantageous is the one I should go with. But you get the idea. It's not like "John." It's an exoticness name. I work at a company called G2i. What I do at G2i, we try to be good news to the Internet. There's a lot of bad news. Open Twitter. We find company who want work and find companies who want them and just match make. And I love the work we do. But really, if I'm honest with myself and with you, what I love the most is the people that I do it with.

00:54These people, I'm telling you. It's just I go to work every day and I'm like, how can kindness of this level exist? But we're not here to talk about that. We're here to talk about REST. And GraphQL. And stuff. Before I continue, though, I need to say it, like, I don't think there's anyone here in this room that's having as good a time as I am. Seriously. Like so, this conference has been, I think one of the best conferences I have ever been to in my whole life. I came from Germany, so it was like a 34hour Germany. But I came here, got to see my parents and stuff. Now I get to see all my friends. We get to talk about code. I am here to talk about REST and GraphQL and stuff. But really, I'm just here to spread the love.

01:45We're going to talk about open source. Thank you! [ Applause ] We're gonna talk about open source. But I want you to look at this talk through the lens of open source as a labor of love. I receive nothing for creating something for free and then giving it to you. Right? And so, it's literally lovedriven. And so, in preparing this talk, I thought long and hard, what is the best way to express these ideas? What is the best way to show you these things what is the best way to talk about REST in a GraphQL world? And I believe the way that would resonate the best with all of us in this room is through narrative. Through a story. And so, let's go down this rabbit trail. I should, before I get into it, this idea of spreading the love came from my uncle Raymond, who if you're watching the livestream, love you.

02:39Story time. This story begins where all great and noteworthy stories start. With JavaScript. and it's, you know, it's good. It's with JavaScript. And so, the context is I was working a previous josh. We had a codebase that developed over many years with JavaScript. It was good. Our customers loved it. We even I think made profit on it. But eventually what happens, happens. Time showed up. And over time, our codebase grew and grew and grew until it was an aged codebase. It was it was old and, you know, for sure there's always something to refactor, right? How many of you know there's not a perfect product ever, right? Exactly. There's always something to optimize. There's always something to refactor.

03:26The only problem is, given the nature of JavaScript, we struggled. We struggled deleting code because we didn't know what else we would break. I was talking to someone here, and they mentioned, I never delete code in my JavaScript projects, I comment it out. I learned that lesson before. This is where we were. We were featurefrozen, but against our own will. So, this is the part in my talk where I come to you and say, hey, I love JavaScript. But perhaps there might be something better. But we need to pause here. And we these to acknowledge the meme king. Where are you? There he is. This Tweet he'll tell you, I'm here to tell you that today. And I don't look at you like this, though, I'm not going to ask if you don't use TypeScript why are you the way you are?

04:22But I am going to tell you about TypeScript as though I was a beggar and I was hungry, and I found bread. You hear what I mean? And so, TypeScript. We found TypeScript. We used TypeScript. So, this product that we built that we loved was amazing. But we couldn't, in good conscience, iterate on it anymore. We actually had to rewrite it. We decided, okay, it's a rewrite. Let's go with TypeScript. Let's see what it's about. This is the time when Flow and TypeScript were competing. We wanted TypeScript. We couldn't understand Flow's output. The errors were hard to parse. It's not a critique, that's what it was. We saw a benefit. We could confidently refactor, deleting things, our bundles became smaller.

05:16Instead of telling you about it like every other TypeScript programmer, I'm going to show you some of the ways that TypeScript was able to add value to us. This conference, I genuinely have such a good time here because I've rarely been to a conference where there has been this much focus on design system asks CSS and styling in general. And I think that's just an amazing thing. And we're in exception. So, at this job that I worked at, we had a design system. It was, in my opinion the best. I'm a little bit biased. It helped us significantly. And for documentation of this design system, we used something called React styleguidist. How many of you know what styleguidist is? That's 40%. It will take mark down, like a README file, parse and give you interactive code documents.

06:06Let me show it to you. Let's go over here. This is the documentation of our design system. It's called operational UI. It's kind of an embarrassment with bundle size. I'm not gonna lie. But mostly for internal tools. That's no excuse. But this is an older version. So, if we look at on this side, we have the names of different components. And we get documentation for them. So, if I go to button, you will see some text. And living examples and a code playground here. So, I if click on view code, I can kind of see the code and, you know, is it updates. So, if I say button colour equals, let's do red. And so, it's red. And I can, you know, change it to I don't know, I love Jed? And it works. It's living.

06:58The problem, though, is it's not it doesn't reflect the actual component. What I mean by that is I could do, like, I could add here prop that doesn't that does not exist. And I could say, cheese, right? And this is invalid. But there's no indication here that it's invalid. Just kind of this is also a weakness of JavaScript. It just kind of says, yeah, whatever. Cool. Now, this entire page through styleguidist was generated from markdown. I would like to show you. So, if I go to GitHub. Actually, let's just go here. This is a newer version with a source code link because it's open source. And if we go here in the source, there is all of these components here you see are a onetoone mapping of the components here.

07:48And their READMEs create the docs website. So, this README here is parsed into is parsed into this. Literally. It's the same text. So, this text is taken and evalled in the browser and run. And that's how it works. But we thought, can we do better? Can TypeScript help our documentation? And the use is, it can. So, what we did how many of you use VS code in this room. Kind of all of you. If you have used VSCode, even if you don't use TypeScript, you would benefit from the intelli sense. The underlines. We took the underlying code, Monaco, and we put it in our documentation. And since it's a TypeScript project, we get those benefits. Here is the new version, major version 18. If we go here, it's the exact same README, as you can see.

08:44But the editor is a little bit different. This is VSCode's editor. And now, if I try to do something wrong, it will just tell me. So, I'll go here. I'll say button, invalid prop equals no. And it says, whoa, you can't do that. That prop doesn't exist. But more than that, it tells me what does exist. So, let's let's explore this API a little bit. So, we're working with this first button here. And it says press alt plus space for available props. I'm just going to do that here. And I see all of the props available to me in the browser. this documentation is live. What can I do? Well, I can say, well, this button is fullwidth. Bam, I have a fullwidth button. I can say the button I see loading here, click that.

09:32And just like that, I get a spinner. It tells me what I can do. This is throughout the entire codebase. I can do to avatar, a name avatartype thing. And I could say, size. And I could give it a pixel value, 4,000 pixels. Doesn't work. Am I using it wrong? Do I need to look at the docs? These are the docs. And so, number is not assignable to what? Small, extrasmall or medium. So, if I do this, I get even autocompletion on what I can do. I choose medium in realtime, it is extrasmall, choose small. Our documentation through TypeScript is now living. For our consumers, this is invaluable. And I want to publicly praise Mark with a playroom that does this. If you saw his demo, it is autocomplete all over the place.

10:25I believe this is the future and I believe this is a way TypeScript has added value to our design system. We don't have the time to go into the details of how we took VSCode's and put it in the browser. But I did a talk in Finland last year if you can watch that stuff. It requires some gymnastics with code. You simulate a file system in the browser and stuff. It's pretty whacky. We are here to talk about TypeScript. And I hope I have shown ways that it's valuable to us. And I'm going to show you more ways it saved time, improved our productivity and helped us in the context of data communication. The app is good, refactoring, deleting, nothing is breaking. We couldn't trigger runtime exceptions.

11:19We added sentry to log exceptions. How do we test this now? We couldn't cause any exceptions, it was covered with types and good. We saw no error reports. It was amazing. Except at the network layer. So, we would receive things from the backend. We would expect foo, we would get bar, do you know what I mean? Sometimes backend just didn't hold up its deal. It's classic. You have the frontend product manager goes to the frontend, it's the backend! And this is where things would break, explode, error boundary would kick in and people see bugs. And we were sad. We want to create things that we can talk about at conferences with no runtime exceptions. At the time we were using REST. And as it turns out, REST is just is not very good.

12:21And so, we're engineers, though, we can't just say things. You can't just say it's not good. I wish there was one word that we use more in our teams. REST is not very good because a couple reasons. Number one, it's not a formal specification. Like there is no living document that says this is how you implement a REST API. There is now, we have semantics. We have post, put, patch, get, delete, 200, 201, 300, 302. So, we have these things, but there isn't the formal specification that says what they mean. If I have to ask you, hey, our user has no access to this thing, what should the status code be? 401 because they're unauthorised? 404 because they shouldn't even know it exists? What's the policy?

13:14That leads to a tonne of guessing games. You guess things. And where the backend makes assumptions and then the frontend makes assumptions about their assumptions, what happens? Bugs. But my biggest problem with REST is that it just leads to a tonne of meaning less discussions. When I say meaningless, I mean, should this be a put or a patch? I have a tip for you: Your users do not care. I don't see anyone sitting in a train with inconsistent WiFi going, hm, I wonder, was it a put or a patch? But we talk about it in our engineering teams. What should this be? I don't care. Number four. The fundamental issue with REST is there's just no contractual agreements. There isn't a way for the backend to say, hey, this is what I'm going to send you.

14:01The frontend to say, thanks, I got you. There's segregation and discrimination. How can we fix it? The moment I decided where we need to do something when I had to ask this in a Slack conversation. This was not yesterday. This was a screenshot from a long time ago. So, you create something with a put. And at that point I was just, just no thank you. REST, you are not what I need now. Now, thankfully, there is work being done in this space. There was an incredible talk by Petra just before this one that was incredible. Publicly say thank you. Give her a round of applause. That was an incredible, incredible talk. I watched it and I was especially given the context of my talk, I was like, oh, my gosh, yes!

14:55GraphQL is very if you've watched her talk I don't need to do the spiel with you. GraphQL is very good. But because we're engineers, it's very good because number one, it is a formal specification. Yes, the name is Graph Query Language. It suspect just a program or a language for queries. It's not just a protocol, it is a document. It is a document that is a specification. And because it's a specification, it says, do it this way. You know what that does? That means you don't have to guess. If you want to implement the API, do it. It's ready. If you have to guess, it's an open source specification. Meaning if you have some interesting edge case that isn't covered by the spec, you can contribute back to it.

15:40We solved it, can we augment the spec? Yes, it's open source. That's less guessing games for the world. We have meaningful discussions. Not post, put, no. What we're talking about, should we cache this? Should we lazy load? Do these decisions affect your end users? They do. Are these valuable discussions? Yes, they are. And GraphQL allows for them. Lastly, it enforces strong because you start with the schema as Petch so eloquently said. Enforces strong contractual agreements. What we looked at these are just purely the developer experience benefits of GraphQL. We have the discussions, cache this. That's developer experience. If I were to talk about the user experience benefits of GraphQL, I could go offslide.

16:35That would be the whole talk. It is it is very, very valuable. And so, I think I made my point. GraphQL is very good. Now, I spend a lot of time at a lot of conferences talking to a lot of people. And I was once I think it was a GraphQL conference. And there was an entire talk, so, like 35 minutes about how do I convince my manager to adopt GraphQL? 35. And so, was like, what? You need a talk for this? And so, like, I've heard the conversation. Goes like this. Go to your manager, team lead, CTO, whatever. Hi. We want to add a GraphQL service. What's the response? We can't because reasons, reasons. And what are the I've heard these stories. And I've seen some of them with my own eyes. Reason number one, we don't trust JavaScript for an API.

17:25It's JavaScript, come on. You would use JavaScript to add a little clock that follows your cursor over the screen. Drop downs, jQuery, but an API? How about this one: We already have an API team and they're busy. Just look in Jira. Right? Where are my Atlassian people at? Or number three, we don't have time. We're superbusy shipping RESTful APIs that break. Or lastly, we need to ship. At this point, you go, come on. We see the benefit. And at some point, it's not just you, it's your entire team. Oh, come on. This we believe in this. Why can we not implement it? Now, I found myself in this circumstance. This was a constraint. For whatever reason way above me we had to continue using REST. Ah!

18:22Now, I want to pause here. There was a talk earlier by Mitchell. I loved this talk. 18 years old. Oh, my goodness, I need to publicly go, that was incredible. If you [ Applause ] If you weren't here, you missed out. Watch it on the video. It was incredible. It's always awkward to drink water because all of you are looking at me while I drink. Anyway, so, you go, this is a constraint. What do we do? If you're on your phone, Tweet it if you're not on the phone, look at me. In the face of constraints, you can either get bitter or you can get better. You understand? We thankfully, my team, we were like, we don't like REST. What can we do and get better? That led to an idea. We decided, let's start a side project.

19:16Because, you see, we worked with GraphQL. We loved GraphQL mainly for the guarantees. We didn't have any errors with GraphQL. We loved the Apollo project and open source foundational piece of amazing you know, I'm doing a lot of public applause. They deserve it. GraphQL, incredible. Client server engine. It's just an amazing piece of software. We loved it and decided, let's create something like that but for REST. That's what we did. Call it RESTful React. It's the same API as Apollo but without the type safety, sadly. And I would love to show it to you right now. So, what I have running is a little project here. I'm just gonna go ahead and code insiders it. I like living on the edge. And I believe it's already running.

20:03So, what we're gonna do is we're gonna go split screen. And I believe it's local host local host 8081. Nice. Okay. Hello, ReactConf AU. It's a basic React app with nothing really special about it. Let's add RESTful React to this thing and see how it's similar. So, we'll go here. And step one with RESTful React. Add something to give context. Say RESTful, it doesn't want to help me out. Okay. Import something from RESTful React. And we will import the RESTful provider. This gives it context. We will just do that. And what we can see is already TypeScript is helping me out. Hey, look, base is missing. You need this prop. You need to tell us what HTTP host you're talking to. I'm going to talk to my favorite API in the whole world.

21:03The dog API. And so, now that my app has context, I'll go in here. And what I'll do is I'll use a hook. So, we have a hook. It's called use get. And we have use post, use mutate is the other one. But we have use get. And I will it's, again, it's gonna help me out and say, hey, you need to fetch something from a path. Path is missing. So, I'll go ahead and add that. Breeds, image random, I believe. I've memorized the dog API. Yeah. And so, we'll just add a quick image here to see if it works. Good boy SRC is I get something from here. So, let's say data. And actually, just make sure I have data before I do that. I think it's message and notice, I just guessed that it's message. That's really important.

21:57And so, now what we should see is perfect. It works. It's working nicely. And every time I reload, I get a random dog. But I had no idea. That's a little disturbing. [ Laughter ] That's better. I had no idea that this was message. So, if I'm, you know, if I'm misinformed, I could type massage, maybe. And then I'm like, oh, no, why is it not working? This is where TypeScript helps me out. It's called a type argument or a generic. I expect something with message, and message should be a string. It says, message, massage doesn't exist. I get autocompletion, yes, message. And everything is fine. I literally cannot stuff this up. And this code will never reach my users if it's broken, it will fail ahead of time.

22:45That's a nice way to get some safety. But, my friends, is that enough? Kind of. Can we do better? In the beginning, we said REST is just not good because all these reasons. We have been over this. But the last one is not entirely true. There's something called Open API. It's a long document that describes all your possible routes with all the methods, with the status code. This is a 35,000 at least line of JSON or YAML. It looks like this. Which good luck reading that. And so, we were like, okay, so, we have this thing. How can we can we use it? And my coworker, Fabian, he's French, loves wine and cheese. Although I don't mean to enforce stereotypes. But he is one. And he was like, you know what we should do?

23:43Let's do some code gen. Let's take this file as input and just output. And I was like, you can output type definitions. And he was like, no, let's output React hooks. RESTful React also exposes a command line interface, CLI. Right here I will yarn RESTful React import. Oh, oops. I have a typo. React import. And I'm just gonna autofill this. And you can actually just go ahead and fetch this file off GitHub. You don't even need to have it locally. GitHub username, GitHub repo, branch and file path and you tell it where you want to save it. So, I've created an open document for the Giphy or Giphy, however you want to say it. In case you blinked, I'm sorry, you missed it. You have a new file, this green thing.

24:41API. TSX. This is stuff I don't care about. I don't need to deal with that. But now I can use it in a fully typesafe way. I'm here to show you. I will change this. No longer speaking to dog CEO. I'm speaking to Giphy.com/v1. I've changed. This is gonna fail, understandably so. And I'm going to the app, and instead of the use get, I'm going to do something else. I'm going to import something from my new API file. But what am I going to import? This generates React hooks. What am I looking for? What's the word that starts hooks? You what? I'm just gonna stay here until someone answers me. Use. So, we type "Use." And this is all from the Giphy API. I just directly here. I don't need to look anywhere.

25:43It's just there. I will use a random GIF and I will destructure whatever I get back. Use random GIF. Does it want anything? It's good. And I get back data. Watch this. I will call this GIF response, actually. Okay? And now, it's like, look, message doesn't exist anymore. Well, what does? It's actually GIF response. What does? Okay. Dot. Look at this. This is from some API somewhere right here in my editor. It's endtoend type safety with data fetching. So, what I want is images.original.URL. And all of this optional chaining, everything is just there for free. And I'm gonna save that. And does it work? It doesn't. Why doesn't it work? Because I'm not authenticated. So, Giphy requires a query param from my access token.

26:38I'll add query params, API key. I need you to cover your eyes for a second. Because look, I even blurred it out. How cool is that? So, I'm just gonna let's see if I can paste this and scroll away quickly. Oop! Okay. Are we ready? Okay. I'm just gonna save this now. And there you go. Endtoend. [ Applause ] Endtoend type safety. And look at this. Why not? Instead of use random GIF, I could say use random sticker, save. And if the API is the same, bam. I okay, that's maybe suggestive. Let's do something else. Anyway [ Applause ] I love this talk because it's so unexpected. But you get the idea. Let's get back to it. My friends, what we've achieved, endtoend type safety with a REST API. I could code an entire user interface and not even leave the editor.

27:41That's kind of ridiculous. But that's what we did in light of the constraints. I'm going to wrap up. Let's talk some takeaways. There's only three. But these are three that I believe are fundamental and very important to me personally, but I think to us as a community. Number one: Let's innovate against constraints. Constraints are amazing. We need to understand this. Constraints we sometimes don't like them. How many of you have an ESLint rule that you think is garbage? Yeah, that's right. Me too. But sometimes the constraints lead to innovation. Jason Miller, author of preact is someone I appreciate. 700 bytes, start with the file size and innovate against that. Constraints can be incredible for coming up with some groundbreaking things.

28:29Let's value them. Number two: You could get bitter, you could get better. But one letter makes a big difference. I personally want to make the commitment to choose better over bitter. And lastly: This one is really important to me. Because this is not the first time I do this talk. And every time I speak about some open source project that I've created, there is, you know, you would expect, there's a lot of issues, there's a lot of involvement. And sometimes I open my notifications. I look at this mountain and then I just I go, I can't. I get overwhelmed and quit. And it keeps me from actively maintaining things. One way to support that could be open collective or donate or do something. But open source while it has so much to contribute, we don't support people.

29:16I would encourage us to support open source a little bit more. With that, thank you so much for having me. This has been an incredible experience. Appreciate you very much. [ Applause ]

More talks

All 19 transcripts

Elsewhere

There is every talk I have given, all 69 of them, ConTejas Code, the podcast, and Fluent React, the O'Reilly book on how React works inside.