REST vs. GraphQL with Arnaud Lauret and Doc Jones

Kevin Montalbo

Welcome to Episode 71 of the Coding Over Cocktails podcast. My name is Kevin Montalbo. With me is Toro Cloud CEO and Founder, David Brown. Good day, David!

David Brown

71! Time flies when you're having fun. I had no idea we’d make it up to 71.

Kevin Montalbo: 

Yeah, too fast. Alright. On this edition of Coding Over Cocktails, we're going to have another Tech Smackdown – our third one – putting forth two technologies, concepts or architectural styles in a friendly sparring match. 

Today, we're debating between REST versus GraphQL. Which Web API architectural style should we use? Let me introduce our guest on the REST corner. We have a returning guest from a previous episode. He's currently the OpenAPI Lead at Postman and is known as the “API Handyman,” helping people from executives to developers and everything in between understand what APIs are, why they matter and how to do them. 

He authored the book “The Design of Web APIs” which teaches readers how to get the requirements, balanced 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 Arnaud Lauret. Welcome back to the show!

Arnaud Lauret 

Hi, happy to be here!

David Brown 

Yeah, great to have you back!

Kevin Montalbo 

On the other corner, we have the Technical Lead in Open Technologies also at Postman. She focuses on GraphQL as one of the five API specifications supported by Postman. Before this, she worked on an API project at Telefonica that exposed backend services, including the billing API through their global mobile developer program. 

She has also begun participating in the GraphQL working group which is responsible for developing and releasing the GraphQL specification. She is the working group co-lead of the Rust compiler contributor program she helped create called RustcContributor::new. She is working to bring together and share her knowledge of Rust and GraphQL as more GraphQL tooling is being developed in Rust by Apollo and The Guild. 

Representing the GraphQL 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 

Now, let's get started with REST. Why don't we start with just a couple of definitions and I guess, the origin of these technologies, 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 style. It stands for “representational state transfer” which means absolutely nothing for most people. But if we try to make an actually usable description of what REST is, it's an architectural style that was created to actually define the HTTP protocol. That's it. Roy Fielding needed that thing to rationally explain what the HTTP protocol was, its characteristics and so on. What is interesting with this style is that you can apply the principles that are defined in REST to any other type of API, any other type of communication between pieces of software. 

Nevertheless some people decided to take the REST name and say, “We are building a REST API” in a sense that they are building REST APIs 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 the REST API, it's an API that is composed of GET slash-this and POST slash-that.  That happens if it works within 200 OK responses with some data. If it does not work, maybe 400 or whatever. 

That's the simple definition of what REST API is. There are numerous debates about [an API] being purely REST or not, but basically, it's APIs that try to follow the HTTP protocol.

David Brown 

I might dive into what you're just alluding to there, whether it actually is REST or not. I think the definition of REST has become more loose over time. So, why is that? What is the true definition of a RESTful API as opposed to what we see more often today?

Arnaud Lauret 

Yeah. So, a “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 get me some data and absolutely not delete something. And I've seen people creating sort of REST APIs 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, for 400 when the consumer made a mistake. 

Then you can also take advantage of another constraint of REST which is cacheability, in the sense that when you return some information, you can provide metadata saying, “Okay, what we have just given you, you can cache it for five minutes, one day or do not cache it.” You can then use a conditional request saying, “Okay, I had votes that are identified by something. I want to get the dates,” and the seller can then respond “Okay no, there was no date.” So you don't need to retrieve all of that again. 

There is also a clear separation between the consumer and the provider of the API in a sense that the consumer does not need any information about how it (the API) is implemented. And it seems it's a principle that is often neglected. And too often consumers, especially for internal APIs in big organisations, want to mingle in how we consume early provider developed API. And so on. 

But basically the consumer just has to talk to an interface and they don't care about what is actually happening behind and actually, they do not know if the real system that gave them the answer is the ones that they are directly talking to. They don't care about that. So, there are different constraints. But also, we can talk about it 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, okay. So there are some features of the REST API that I guess have made it all-pervasive. What has led to its success?

Arnaud Lauret

In my opinion, as someone who has written a book about API design and is really in an API design gig, 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 company name, but even if you do not deal with the same topic, for example, an API dealing with telecommunications and an API dealing with banks, if they are true REST APIs, they will work the same because they share the HTTP semantics. So, I already know how they work without having to think about it. 

Also the HTTP protocol made it what it is today. It is accepted by a wide range of equipment and security equipment, routing, whatever. It's easy to implement in any technology. Whatever programming language you will take, there will be the implementation to basically support the HTTP protocol. Now, there are frameworks that allow you to develop REST APIs 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, I think, simple to develop. Even if you don't do them well, you’ll have a uniform interface that makes them somehow easy to use. You can still make terrible REST APIs because we are, well, concerned. But yeah, I think that's why they were successful in the last, let's say, two decades.

David Brown 

Yeah, okay. Well Doc, REST has been incredibly successful and it is simple. The tooling is robust and all pervasive and covers a lot of programming languages as I was just saying. So what caused GraphQL to emerge? What problem was it trying to solve that REST wasn't already solving?

Doc Jones

GraphQL and REST have become incredible technology partners in a number of use cases.

Probably you and many listeners to this program know that GraphQL hasn't been around as long as REST. It was something that was developed as part of Facebook's effort to create an iOS client and 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 just be able to deliver the Facebook UI, which has many, many components. 

And so, the other benefit that they got from creating GraphQL was the decoupling of the client from the server. So if you're building RESTful APIs 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 fairly large object that then they have to handle and parse on the client side. But, with GraphQL you can create a query and only request the data that you need for your service or for your UI component. So let me go back and start where Arnaud did, which is with a definition. And I will say I will caveat all of this by saying that both GraphQL and I are much newer to this API world than RESTful or Arnaud. They've both got a couple of decades on us. I think Arnaud's been telling other people how to build APIs for at least a decade, maybe longer, but he has tremendous expertise and experience. I'm much newer to this. I've been the GraphQL Lead at Postman for two months. 

So, a lot of what you'll see on my blog is me learning in public. I've been encouraged to do that and in fact prodded to do that by Kin Lane, and he's absolutely right about it. The more I do it, the more value I see in it and why it works. But let's start with GraphQL. Graph QL is a query language and a server side runtime for APIs that prioritises giving clients exactly the data that they request. So, you and your listeners probably have heard of “overfetching” 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. And GraphQL alleviates some of that. 

Now, I will say that GraphQL and REST have become incredible technology partners in a number of use cases. It's not unusual to have a variety of either external APIs that are delivering a REST API to then be unified in a GraphQL API. And the purpose of that is to combine various REST APIs in different combinations to create a single service. 

One example of that would be in the commerce space where this is fairly getting more common, using the backend for frontend pattern where you create an endpoint for specific applications as opposed to a single endpoint for everyone in the public. GraphQL is refining as it goes along and the patterns that it uses in the architectural styles that fit with it and unified graphs are definitely becoming more popular. So, whether you have microservices on the backend with GRPC APIs or external APIs, with REST or directly to a database, all of those things can be unified in a GraphQL, basically an API gateway. 

And then again you can provide various endpoints for whatever service you're trying to service or trying to provide data for. For example, shipping is an activity on the frontend that calls various backend services. So inventory, shipping providers, a combination of those various data. And you can combine them in various ways and again be able to unify them into a GraphQL 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 backend services. So, the companies are reporting that they're gaining speed in development and time to market by using GraphQL this way. 

I think, probably the company that has the most responsibility for creating excitement around GraphQL 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 thousands and thousands and thousands of microservices that they run, to then unify those into a single GraphQL API gateway. They have an entire team that does nothing but manage their schema. 

Creating subgraphs allowed them to basically allow domain experts within the different service domains to be responsible for creating their own schemas. And so 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 the schemas are combined at the API Gateway level and not all instances of using a unified graph result in a public GraphQL API. There are a number of instances where the public API is actually a client of the GraphQL API Gateway. So, Twitter is a really good example. Their public API is RESTful but it is a client of the GraphQL API gateway.

David Brown

I mean, we started out by saying REST is simple, it's made actually for the HTTP protocol, there's lots of tooling and programming languages. Now, I feel like I just want to use GraphQL for everything, like I can get the exact data I need, I don't get overloaded with the payload so, how did REST deal with these challenges? Does it have an alternative?

Arnaud Lauret 

It's really important for people to understand that design is important for all types of APIs.

So, I’ll also come back to a few things you said. So, regarding decoupling the client and the server, that's one of the constraints of REST. So, you have that out of the box. And whether you are doing REST, GRPC, GraphQL or subservices, you still have the decoupling between client and server because you can create marks, you have service definition and so on. So, whatever the type of API, you’ll have that. 

You can also do query with REST, which are far less advanced than what you can get with GraphQL. But if you want to restrain the amount of data you will get, you can do that. You can use standard formats like JSON APIs when you call the REST Twitter API which is backed by the GraphQL API. But when you call the REST API, you can tell which are the properties you want when you are retrieving your Twitter data, so it's possible. 

And also, regarding the overfetching, underfetching, whatever, in most cases I've seen where people tell me, “Hey, we want to use GraphQL because we have to choose,” actually the problem was not actually choosing between REST and GraphQL. The problem was designing an API. And before you do a REST API or a GraphQL API, if you do not work on the design, it will not work. 

I made that mistake a long time ago when designing a banking API, resulting in the client, which was a mobile application, always having to do many small requests because the design was wrong. I misidentified the needs from a pure business perspective. And so, I fixed that by creating a bigger operation which will bring more than that. But that was making sense from a pure business perspective. So it's really important for people to understand that design is important for all types of APIs – REST, like any other, and GraphQL also. 

And talking about simplicity, if you can retrieve exactly the data you want, a strict request of exactly what you want, you will get a big bag of data or a small bag of data which is tailor made for you. It’s what you need, which is cool because it is exactly what you want. The problem you can have with that is how you handle cache. So, there are tools that help. Correct me if I'm wrong, but there are tools on the client side that help you sort that problem. But in the very beginning of GraphQL, this was a problem. You cannot cache the data or you can cache them, but you don't know for how long. 

And with REST APIs, you can easily protect the system, exposing the REST API, putting a gateway and throttling. When you create a GraphQL request, the consumer, if there are no boundaries, can do anything they want. So, they can create very complex requests. And I don’t know if you have some info about that, but now, maybe it's embedded in some GraphQL system. You can calculate the complexity of requests to avoid putting the system down behind that.

David Brown

Okay, Doc you're shaking your head there, so tell us.

Doc Jones

Certainly, GraphQL has been able to adapt and adopt a number of tools from our REST brethren and colleagues.

Yeah, so I think I have not done a very good job of sharing with my colleague all the things that I've learned about GraphQL and certainly its modern incarnation. So, caching is common both on the server and the client side. The other thing that's interesting about GraphQL is the tooling. Again, GraphQL has not been around as long as REST, and so the tooling is, 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 Netflix or Twitter are custom. They've developed their own tooling because in most cases, when they started, it just didn't exist. There's a lot of work going on with GraphQL. 

Certainly, GraphQL has been able to adapt and adopt a number of tools from our REST brethren and colleagues. Authorisation is a really key one because it's something that is not at all included in the GraphQL spec. There's nothing about authentication or authorisation in respect. So, most implementations and implementers and even tool builders will use OAuth and other authorisation tools from the REST world. And there are other things that are still sort of an issue that are constantly in development. But the good thing about the way that GraphQL is constructed, especially on the service side – a schema, I should say – is that you have it's very extensible. So, you have a lot of flexibility in terms of creating what are called directives. 

There are some that come along with the spec that are built in. There is introspection alluded to which allows you to submit a special query that will give you the schema for a given GraphQL. But it's been a best practice for quite a while. Unless you're dealing with an internal GraphQL that you really want disabled introspection, you don't want the outside world to be able to get a copy of your schema. And that's a common best practice kind of thing. So, that vulnerability has been addressed. I don't disagree that it was not a problem in the early days when things were new. But I think there's a number of things that 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, at-scale GraphQL implementations or even well-done ones rely heavily on REST APIs. So, you've got GraphQL being successful because REST is so prevalent and ubiquitous. So you can combine multiple REST endpoints and wrap them in a graph and 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 – as we combine new data sources and many, many, many more data sources at scale to get insights, make decisions, all kinds of things –  GraphQL 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 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 also, 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 mapping service. 

David Brown

Is this a case of like, when we talk about REST versus GraphQL, is it a case of horses for courses? And there are some natural use cases for Graph QL versus REST. Are they particularly use cases which suit GraphQL better than REST? Let's dive into those if there are.

Doc Jones

There are. So, Kin Lane does a video podcast called Breaking Changes and he did an episode with a gentleman from Oracle Hospitality. And Oracle Hospitality serves all of these hotel rooms and resorts and that sort of thing. So, the reason that they chose GraphQL 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 a maintenance issue, it's available but in housekeeping. And I'm not going to represent this as well as it would be if somebody went and watched that episode of Breaking Changes, which I highly recommend you do because that gentleman is an expert on this. But there's a lot of state information that lives 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.

David Brown

So there was a natural use case for GraphQL? What are the natural use cases for REST?

Arnaud Lauret

Nowadays, I would say…

Doc Jones

Everything.

Arnaud Lauret

As an architect, everything. Because there are no silver bullets, never in architecture. Nowadays, REST is the default type for many APIs because it works well. You have the uniform interface and it works. You don't have to think about it. And you can easily define a bonded API that will do a specific subdomain of activity. And so most public, if not most, probably 99% of public APIs are REST APIs because everybody knows how to use them. But maybe it will change in the future. I have GraphQL in my toolbox and I usually recommend it as they describe it. Never get back and forth from time. Typically I'm building a mobile application, web app and I know I have different APIs to call, to aggregate and whatever, and using GraphQL can be really useful for that. Basically, GraphQL will probably beat REST API.

Doc Jones

I just realised another aspect of GraphQL 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. Errors are handled automatically for every query in every mutation.

Arnaud Lauret

Speaking of mutation, one thing I really like is the query capacity of GraphQL. It's really amazing. But when it comes to modifying data, I don't like that because I lose the uniform interface. Because with a REST API, you have your address resource. Get your address and if you want to modify it, you just use the same endpoint, change the HTTP method and it works. With GraphQL, we come back to when it comes to modification. We come back to a GRPC world and so you have to define your functions, unless I'm mistaken. 

I think that Netflix and Twitter, if they want to provide a mutation, for example, 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 a schema but it's just a bit, let's say, complicated. I like to put things in a box to be able to go from one thing to another and in GraphQL the query is, in my opinion, too 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.

David Brown

You started off by saying REST is an architectural style. So I'd like to throw a spanner in the works to bring the show to conclusion. Say, the emergence and dominance we're seeing with event-based processing and pubsub architectures, is an API format like Async API going to come along and eat both your breakfast.

Doc Jones

I'm going to start on this one because this is my favourite. This is my favourite thing, it’s when somebody says a technology is going to replace another technology. In my experience in this industry, that never happens, ever. So REST will continue, GraphQL will continue and Async API will take its place and because we have these great fit for purpose technologies, there will be a specialisation. And you know, people will experience more with GraphQL. 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. 

And Async API does a beautiful job of focusing on messages as opposed to the kinds of things that GraphQL and OpenAPI deal with. So the answer is – I am completely convinced and strongly believe – “Yes, and…” And so REST, and GraphQL and AsyncAPI.

Arnaud Lauret

If you want to introduce a completely new technology that nobody can deal with inside your organisation, 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.

Yeah, I totally agree with it. And there is no silver bullet and it's really important that people stop being “fanboys” and I purposely say “fanboys” because let's be honest, many technologies can be a bit tense sometimes. But it's really about what the problem is that you are trying to solve, welcome that technical problem with a business perspective, settle, define the problem that 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 organisation. Because if you want to introduce a completely new technology that nobody can deal with inside your organisation, 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 point to end the program on. Arnaud 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!

David Brown

Pleasure.