Kevin Montalbo

Welcome to episode 70 of the Coding of Cocktails podcast. My name is Kevin Montalbo with me is ToroCloud and founder David Brown. Good day, David.

David Brown

70 time flies when you're having fun. I had no idea. Up to 70.

Kevin Montalbo

Yeah, too fast. All right. On this edition of Coding Over Cocktails, we're going to have another tech Smackdown. Our third one puts forth two technologies, concepts or architectural styles in a friendly sparring match. Today we're debating between REST versus Graph QL, which web API architectural style should we use? Let me introduce our guests on the rest corner. We have a returning guest from a previous episode. He's currently the Open API lead at postman and is known as the API handyman, helping people from executives to developers and everything in between, understand what API'S are, why they matter and how to do them. He authored the book, the design of web API S which teaches readers how to gather requirements, balance business and technical goals and how to adopt a consumer first mindset while teaching effective practices using numerous interesting examples. Joining us today to represent rest is Arnold Lauret. Hi, Arno, welcome back to the show.

David Brown

All right, back

Kevin Montalbo

On the other corner, we have the technical lead in open technologies. Also at Postman, she focuses on graph QL as one of the five API specifications supported by Postman. Before this, she worked on an API project at Telefonica that exposed back end services including the billing API through their global mobile developer program. She has also begun participating in the Graph QL working group which is responsible for developing and releasing the Graph QL specification. She is the working group cole of the Rust compiler contributor program. She helped create called Rust C contributor. She is working to bring together and share her knowledge of Rust and Graph QL as more graph QL tooling is being developed in Rust by a Polo and the guild representing the graph QL side is Doc Jones. Hi, Doc, welcome to the show.

Doc Jones

Hi, thanks for having me.

Kevin Montalbo

alright on to you David.

David Brown

I know let's get started with the rest. Why don't we start with just a couple of definitions and and the orig I guess the origin of these technologies as well because I think that leads us to some of the use cases for these as well. So rest. What does it do? How did it come about? What's it trying to solve?

Arnaud Lauret

Yeah. So rest is first an architectural stone. It's for rest and for representation of stage transfer, which means absolutely nothing for most people. But if we try to make a naturally usable description of what rest is, it's an architectural style, which was created to actually define the HTTP protocol. But Roy filling nearly needs that thing to explain. What was the rationale, what was the HTTP protocol, its character exists and so on. What is interesting with this Stein is that you can apply the principles that are defined in rest to any other type, any type of API, any other, any type of communication between pieces of software. Nevertheless, some people decided to take the rice names to say,, we are building rice APIs in a sense that they are building R API'S that take advantage of the HTTP protocol and sometimes follow more or less the constraints of the rest architectural style. So nowadays, when you are talking about a rest API, it's an API that is composed of requests for get slash V and post slash vat. What happens if it works within a 200 OK. Responses with some data. If it does not work maybe a 400 or whatever, that's the simple definition of what is a raise. API. There are numerous devices about being purely raised or not. But basically it's API S that try to follow the H GDP protocol and sometimes the virtue or really think about the principle of rest.

David Brown

API si might dive into that. You, you were just alluding to whether it actually is rest or not. And I think the definition of rest has become more loose over time. So why is that? W what, what is the true definition of a restful API as opposed to what we see more often today?

Arnaud Lauret

Yeah. So true and I put quotes around true rest api will first follow the http protocol semantic in a sense that if I see a get slash something, I expect that it's a non dangerous request that will, that will get me some data and absolutely not delete something. And I've seen people creating pseudo API S that do that deleting stuff on a get request to notify the status of the request. You will use the correct http status code 200 when it's OK. 400 when the consumer made a mistake, then you can also take advantage of another constraint of rest, which is cash ability in the sense that when you return some information, you can provide metadata telling. OK. What we have just given you, you can cash it for five minutes one day or do not cash it. You can then use conditional request telling. OK, I had, I had um those that are identified by something I want to get them updated and the server can then respond. OK. No, there, there was no update. So you don't need to retrieve that data again. There is also a clear separation between the consumer and the provider of the API in a sense that the consumer, I do not need any information about how he is implemented. BP I. And it seems it's a principle that is often neglected. And sometimes too often consumers, especially for internal API in the organization, want to mingle in how the consumer, the provider develop its API and so on. But basically, the consumer just has to talk to an interface. They don't care about what is actually happening behind it. And actually, they don't know if the, the, the real system that gave Ben, the answer is the one they are directly talking to. They don't care about that. So there are different constraints, but also we can talk about um being discoverable with the hypermedia stuff in a sense that I can talk with an API and it can tell me what I can do with it. I don't have to rely on documentation.

David Brown

Yes. Yeah. OK. So there are some features of the, the rest api what I guess has made it all pervasive what has led to its success.

Arnaud Lauret

I think that the main, in my opinion, as someone who has written a book about API design and is really an API designer. Gee it's the uniform interface in a sense that either I'm using an API from company A or company B I don't want to quote the usual name. But even if you do not deal with the same topic, for example, on an API dealing with telecommunication and FP I dealing with banks. If they are true DP, they will work the same because they share the HTTP semantic. So I already know how they work without having to think about it. Also the HTTP protocol is for us made with what it is today. It is um it is accepted by a wide range of equipment from security equipment, routing, whatever. it's not, it's easy to implement in any technology, whatever programming language will take, there will be the implementation to basically support the HTTP protocol. Now there are frameworks that allow you to develop R API more easily. But if you just want to stick with the HTTP protocol, you can do it in any programming language. So it's really um I think it's, it's simple to develop. if you do them even if they are not well used, you have a uniform interface that makes them somehow easier to use, but you can still make terrible R API S because we are concerned. But yeah, I think that's why they were successful in the last, let's say two decades.

David Brown

Yeah. OK. Well, the rest has been incredibly successful and it is simple. The tooling is robust and all pervasive and covers a lot of programming language as an, as I was just saying. So what caused graphql to emerge? What problem was it trying to solve? That rest wasn't already solved?

Doc Jones

Well, I think I'm probably you and, and many listeners to this program know that graph hasn't been around as long as rest. Um It was something that was developed as part of Facebook's effort to create an IOS client. Um And so as they were trying to create a user experience on a mobile device for the news feed, they found issues with having multiple endpoints to, to just to be able to deliver the Facebook U I which has many, many components. Um And so the other thing that the other benefit that they got from, from creating graph QL was the decoupling of the client from the server. So if you're building a restful API S, then there is coordination that has to occur between the server and the client, the client receives, you know, whatever data is available as a generally a large, fairly large object that then they then they have to handle and parse on the client side. Um But with graph QL, you can create a query and only request the data that you need for your service or for your U I component. Um There were so let me go back and, and start where Arnold did, which is with the definition. And I will say I will caveat caveat all of this by saying that both graph QL and I are much newer to this, you know, to the, to, to, to the API world than restful or Arnold. They've, they've both got a couple of decades on us. I think Arnold's been telling other people how to build API'S for at least a decade, maybe longer, but he has tremendous expertise and, and experience. Um I'm much newer to this. I've been the, the Graph QL lead at Postman for two months. So a lot of what you'll see on my blog is me learning in public. I, I've been encouraged to do that and in fact, prodded to do that by Ken Lane and he's absolutely right about it. the more I do of it, the more value I see in it and, and why it works. Um But let's start with graph QL. Graph QL is a query language and a server side run time for API'S that prioritizes giving clients exactly the data that they request. So, you and, and your listeners probably have heard of, of over fetching as being an issue with rest. And that's what I described earlier where you get this very large object, whether you need all that data or not. And then the client has to take on the responsibility of parsing it. Um And graph QL alleviates some of that. Now, I will say that graph QL and rest have become um incredible technology partners in a number of use cases. It's not unusual to have a variety of either external API S that are delivering arrest API to then be unified in a graph QL API. And the purpose of that is to combine various rest API S in different combinations to create a, a single service. One example of that would be in the ecommerce space which there's, this is fairly getting more common using the, the back end for front end pattern where you create an endpoint for a specific application as opposed to um a single endpoint for everyone in the public. Um Graph QL is refining um as it goes along and, and the patterns that it uses in the architectural styles that fit with it. And unified Graph is definitely becoming more popular. Um So whether you, whether you have micro services on the back end with, with GRPC API S or external API S with rest or directly to a database, all of those things can be unified in a graph QL, basically API gateway. Um And then again, you can provide various endpoints for whatever service you're trying to you know, trying to service or trying to, to provide data for, for example, shipping is a, is a, is a an activity on the front end that calls various backend services. So inventory, um you know, shipping providers, you know, a combination of those various data um what am I trying to say? I'm suddenly flickering on my on the word I'm looking for anyway, data sources. Um So, and you can go combine them in various ways. And again, being able to unify them into a graph QL API gateway has been extremely helpful. And again, you're decoupled from the client. So the client can go ahead and develop their applications and determine what data they need and create queries around that without waiting for the development of back end services. So you, you gain companies are reporting that they're gaining speed in, in, in development and time to market by using graphics. Well, this way, um there are I think probably the company that has the most responsibility for creating um excitement around graph QL is definitely Netflix. So the very first company outside of Facebook that deployed was AirBNB. But when Netflix basically created subgraphs for all of the microservices, the, the thousands and thousands and thousands of microservices that they run to then unify those into a, a single um graph QL API gateway. They have an entire team that does nothing but manage their schema. Um creating subgraphs allowed them to basically um allow domain experts within the different service domains to be responsible for creating their own schema. Um And so you push again, it's sort of a decoupling idea where you're pushing that responsibility down to the people who are experts within a certain service area because they developed the microservice. And then you the the schemas are combined at the API gateway level and not all instances of using a unified graph result in a public graph QL API. Um There are a number of instances where the public API is actually a client of the graph QL API gateway.

David Brown

Say that again. Sorry, just repeat that again for me.

Doc Jones

So Twitter is a really good example. Their public API is restful but it is a client of the graph QL API gateway.

David Brown

OK. Got it. Mhm So I mean we started out by saying rest is simple. It's, you know, MI HP protocol, there's lots of tooling and programming languages. Now I feel like I just want to use graph QL for everything like I can get the exact data I need, I don't get to the payload, make it overloaded with a payload. So I know I know how, how does rest deal with these challenges? Does it have an alternative?

Arnaud Lauret

And I will also come back to a few things you said about decoupling the client and the server, that's one of the constraints of rest. So you have that out of the box and either you are doing rest your R PC graph or sub services, you still have the decoupling between client and server because you can create mocks, you have server definition and so on. So whatever type of API you have that you can also query with, with rest, which are far less advanced than when you can get with graph Q. But if you want to restrain the amount of data you will get, you can do that. You can use standard format that is on API S. When you call the rest Twitter API, which is backed by a graphical API. But when you call the rest API, you can tell which are the properties you want when you are retrieving your Twitter feed. So it's possible. and also regarding the over fetching and fetching whatever. Yes. In most cases, I've seen people come to me to say, hey, we want to use graph fuel because we have shoes. Actually, the problem was not choosing between West and graph. The problem was designing API S and either a rest API or a graphical API. If you do not work on the design, it will not work. And so sometimes I made that mistake a long time ago when designing a banking api resulting in the client having a mobile application having to do many small requests always because the design was wrong. I misidentified the needs from a pure business perspective. And so I fixed that by creating a bigger operation, retrieving more. But that was making sense from a pure business perspective. So that's really important for people to understand that design is important for all types of API and rest like any other and graph girl. And also talking about simplicity, sorry graft your if you can retrieve exactly the letter you want constrict request. Exactly like what you want. You will get a big bag of data or a small bag of data which is made for you and you need, which is cool. Is it exactly what you want? The problem you can have with that is how are you under cash? Mhm So there are tools that help if and correct me if I'm wrong but there are tools on the client side that help to solve that problem. But in the very beginning of graph D, this was a problem. You cannot cash the data or you can catch them. But you don't know how long for how long you also have to and with rest API, you can easily protect the system, exposing rest API, putting a gateway and froling when you create a graphical request for the consumer. If there are no bounds, no boundaries, they can do anything they want so they can create a very complex request unless, and I've seen maybe that you have some info about that, but I've seen that now. Maybe it's embedded in some graphical system. You can calculate the complexity of the request to avoid putting the system down behind that.

David Brown

OK. Doc you, you were shaking your head there. So tell us.

Doc Jones

Yeah. So I think, I mean, II, I think um I have not done a very good job of um sharing with my colleague, all the things that I've learned about graph QL and certainly it's modern incarnation. Um Yeah. So caching is common both on the, the, the server and the client side. Um The other thing that's interesting about graph QL, the tooling again, graph QL has not been around as long as rest. And so the tooling is not in some cases, not there or immature. This is a fact that's why most of the tooling that exists at very large implementations like um Netflix or Twitter are custom. they've developed their own tooling because in most cases when they started, it just didn't exist, um there's a lot of work going on with graph QL. Certainly Graph QL has been able to adapt and adopt a number of tools from our rest brethren and colleagues. Authorization is a really key one because it's something that is not at all included in the graphical spec. There's nothing about authentication or authorization in the spec. Um And so most implementations and implements and even tool builders will use oo and other authorization tools from the rest world. Um And there are, there are other things that, you know, that are still sort of an issue that are, that are, you know, constantly in, developed in development. But the good thing about um the way that graph QL is constructed, especially on the server side, A schema I should say is that you have a lot of it's very extensible. So you have a lot of flexibility in terms of creating what are called directives. Um There are some that are that, that come along with the spec that are built in. Um There is introspection as alluded to which allows you to submit a special query that will give you the schema for a given graph QL. But it's been, you know, a best practice for quite a while. Unless you're dealing with an internal graph QL that you really want to um disable introspection, you don't want the outside world to be able to get a copy of your schema. Um And that's, that's a common best practice kind of thing. Um And so that vulnerability has been addressed, I don't disagree that it was not a problem, you know, early in the early, early days when things were new. Um But I think there's a number of things that, you know, have been addressed. The other thing that I would say is that it's really important to take a look at the fact that most large scale graph QL implementations or even well done ones rely heavily on rest API S. So you're, you've got graph QL being successful because rest is so prevalent and ubiquitous. So you can combine, you know, multiple resting points and wrap them in a graph and you know, create a service that is easier for the client to consume because it's wrapped in a graph. The other thing that I would like to point out is that a graph in itself um as, as we like to combine new data sources and many, many, many more data sources at scale to get, you know, insights, make decisions, all kinds of things. Um Graph QL has some capability and the fact that it is a graph. So not only do you have the nodes or what I tend to think of as resources in a restful sort of paradigm. But you have context on the edges. So there's important data that exists in the relationships between the nodes. And it's more than just like, you know, relational database type information. For example, if you look at the most basic implementation of a graph, it would be like online mapping. So you have destinations and you can create a route between those destinations. But you also on the edge, living on the edge have context for things like distance and traffic and weather conditions that are commonly now being reported as part of your, you know, mapping service. Um There are other examples. um I'm not sure how much more of that you want

David Brown

some of that. Is this a case of like when we talk about rest versus graphql, is it a case of horses for courses? And that there are some natural use cases for graphql versus rest? Are there particular use cases which suit Graphql better than rest? Let's dive into those if there are.

Doc Jones

there are. So um there was actually an episode of Ken Lane does a, a video podcast called Breaking Changes and he did an episode with um a gentleman from, from Oracle Hospitality and Oracle Hospitality serves, you know, all of these hotel rooms and resorts and that sort of thing. So, the reason that they chose graph QL is because when it comes to doing a reservation, for example, there's a lot of information about a given room that's not within the room object. So there could be you know a maintenance issue, there could be,, it, you know, it's, it's available, but in housekeeping, so there's all these kinds of, and I'm not going to represent this, you know, as well as it would be if somebody went and watched that episode of breaking changes, which I highly recommend you do because, um, that gentleman is a, is an expert on, on this. Um But there's a, there's a lot of state information that lives on the, on the connection between the nodes. And so, they found that being able to describe that context on those connections was extremely valuable and was actually helpful in terms of their network usage. And the speed of the application again, I'm not an expert. So you would have to consult him. Um But that makes sense.

David Brown

So that was, that was a natural use case for graph QL I know is there what, what are the natural use cases for rest?

Arnaud Lauret

Nowadays, I would say everything as a, as an architect, everything because that's there is no silver bullets never in architecture, but there is the usual ones so that you look first and the other ones and already and already I'm speaking French. And nowadays R is the default type for mini API because that works well. you have the uniform interface, you know, it works, you don't have to think about it and you can easily define a bounded API that will do specific things under a specific subdomain of activity. And so it works. But most public, if not, most, probably 99% of public API S are rest API S because everybody knows how to use them. But maybe it will change in the future. We just had a graph clear in my tool box and I usually recommend it as um Doug describes it in the back and forth from them. Typically, I'm building a mobile application, a web app and I know I have different API'S to call to aggregate and whatever and using graphical can be really useful for that. I think, and I think the graph will be be probably on the rest of the idol.

David Brown

Yeah, sorry doc

Doc Jones

I was just gonna, I was just gonna, I just, I realized another aspect of graph QL that's interesting for people who like to use it. And that is the fact that you can specify error handling within the schema. And so that's not an external thing. Um You know, errors are, are handled automatically for every query and every mutation

David Brown

0I'd like to.

Arnaud Lauret

Speaking of mutation, the one thing I really like is the query capacity of graph club. It's really amazing. Hm But when it comes to modifying that, I don't like that because I lose the uniform interface because we raised the API. You have your address resource, you get your address and if you want to modify it, you just use the same endpoint change http method. And it works with graph QL. When it comes to modifying it, we come back to the R PC world. And so you have to define your functions. Unless I'm mistaken, there are no I think that Netflix and Twitter if they want to provide a fun um a media, whether those to update something, they can name it, update this or save that. And so you cannot guess how it works by just looking at it. Hopefully you have the schema, but it's just, I'm, I'm a bit let's say complicated. I like to put things in boxes to be able to go from one thing to another. And in graph fuel, the query is, in my opinion, too much separated from the modification. But that's probably a problem only for me and most people, especially people who develop mobile applications and websites don't care about that. But for a public api when you need to guess how things work quickly and easily

David Brown

you start off by saying rest is an architectural style. So I'd like to throw a Spanner in the works too. To bring the show to a conclusion is say the emergence and dominance that we're seeing with event based processing and pub sub architectures is an API format like async API gonna come along and eat both your breakfast.

Doc Jones

I'm gonna start on this one because this is my favorite. My favorite thing is when somebody says a technology is going to replace another technology in my experience and then in this industry that never happens ever. So there will be rest. graph QL will continue and async API will take its place and there will be because we have these great fit for purpose technologies. There will be specialization and you know, people will, after, you know, experience more with graph QL, it will find its place and its role within these new complex systems that were faced with going forward. And the increasing amount of data that is required to be handled by everything. Um And async API does a beautiful job of focusing on messages as opposed to um the, the, the kinds of things that, that graph QL and, and open API deal with. Um So the answer I, I am completely convinced and strongly believe is yes and so rest and graph QL and an API.

Arnaud Lauret

Yeah, totally agree with that. And there is no silver bullet and it's really important that people stop being fun boys and I purposely say fun boys because let's be honest. meaning technology can be a bit dense sometimes. But it's really first, what kind, what is the problem you are trying to solve? Work on that? The technical problem with business perspective, settle, define your problem, what you want to do and then choose the right technology that will work in the context of your problem and in the context of your organization, because if you want to introduce a completely new technology that nobody can deal with inside your organization, it's a huge problem. And if you choose the wrong technology, it's a huge problem. You will just create new problems instead of solving them.

David Brown

I can't think of a better way to end the program on Arno and Doc. Thank you very much for joining us today. I think that was really informative to differentiate between the two technologies. It was great to have you on the show today.

Doc Jones

Thank you for inviting us.

Kevin Montalbo

My  pleasure. All right guys. That's a wrap. Thank you so much. Yeah. You can finally have your coffee now or tea or if you want a dog, it's really, really early there and you can have lunch or not. So yeah, thank you. So, thank you so much. That's great. 

David Brown

Thank you very much guys. Um Come, come a lot of ground there. Appreciate that.

Doc Jones

Thank you. You know, I can't wait till this comes out because there's a couple of things that Arnold said and I was like, I want to ask him questions, but I know I should not interrupt him. So I, I can't wait for them to be available so I can slack and go. Hey, I was gonna ask you about this. Can you explain this to me or, you know, there's a couple of those,

David Brown

there definitely will be letting you know when it's published. Typically, we turn them around in a few days. So we'll let you know as soon as that's done. And, and,

Doc Jones

So David, are you, is this going to come out after the 14th?

Kevin Montalbo

Um Doc has a request that we come out on the 15th or after the 15th because I wasn't aware of that.

David Brown

So, whatever you've organized with us, that's no problem at all.

Doc Jones

Thank you. Thank you later Arnold. Thanks for inviting me.

David Brown

Bye bye.