REST vs. GraphQL: Critical Look

Thank You Suresh good afternoon everybody thank you for coming just to correct Travis a little bit it was not just me last last year it was also uh original whack the enterprise architect afforded us we had a talk together but today we are going to talk about popular topic these days rest and graph QL and this will be a critical review so my name is Zdenek Amazon o1z and I help companies to build api's I have been at the start of the company or almost from the start of the company called APA which has been acquired by Oracle some two years ago and we had the pleasure to work with many amazing clients begin small ones I left the puree to start my own consulting company called good API because I've seen the opportunity to help people with their API journey not just telling them the software but really be there with them and work with them to to make their API program success and I was super lucky to have really interesting customers and people working with so far I'm also the author of a super model IO which is a data modelling tool which is for modeling data for api's and not only API so it works really well with the graph QL and rest which is the topic today so popular topic I'm not going to discuss what rest or graph QL is it's not all that important what these things are in UN's however I'm going to make few things clear here and that one is architectural style that is the rest the other is of language and framework both can be used to build distributed systems to build the services and API for this to be the system's so I think of these all they they are slightly different things as API paradigms and for the purpose of this review I'll be thinking about the ball rest and graph QL as a implementation on top of HTTP protocol because both rest and graph QL can be in theory used without HTTP using some other protocol but for today let's stick with HTTP word of warning this is a critical review this is based on what I learned what I've seen with my clients what I've seen with my friends what I learned running API is rest or graphical API is in production and with that let's look a little bit at the reviews up to date there are many of these articles about what is rest what is graph QL how they differentiate and many of them are saying something along the lines rest in peace rest you know hooray graph QL but if you look not that you know long ago in the past there were similar articles just with the you know different words in the headlines it was a rest and so up and it was pretty much the rest was the same people were angry about web services and they were hoping that rest will solve all the problems right and I really like this one which says rest is the new soap right so then graph gives the new rest if you want to think about like that the bottom line is there are and happy people with the current or predominant styles and they have some problems they those programs were not heard by rest providers or soap web services providers so the history is repeating and we are at another iteration of it what I would like to stress though is that this community is still relatively small I would like to rather see what you know think of us as an API community not as a graph QL community or REST API community we are in a one community and we should work together to deliver you know good technology to the mankind but you came for blood right so we want to know which one which one is the best so let's let's let's look at it as you would probably expect I'm not going to give you the answer however what I'm going to do is I'm going to try to give you the framework so you make can make the answer for yourself based on your specific environment so I said architectural style what is an architectural style an architectural style is a set of constraints which upon applying will imply a system with certain properties let me explain for example a dekapwink constraint so a constraint where you say the components in my system they have to be the coupled client has to be decoupled from the server that implies if that that constraint holds that you can independently evolved client or the server right I had a constraint decoupling implies independent evolution of the both components similarly stateless if I have a constraint that requires you know my communication is stateless the state is not stored on the server that simply implies reliability scalability because I can repeat the call idempotency I can make the many call as many calls as I want because the the requests are unimportant and also enables me to scale it might be a little bit more you know country for complicated with with these constraints for example you need four interface in uniform interface might imply decorated efficiency because you are building interface on top of something right so it's extra milliseconds in the processing however it also implies simplicity because we have the same interface two different components in the system so constraints properties this is the main and on topic for today if you are an API architect so somebody looking at this architectural style your main role is to understand these styles these paradigms API programs and to be able to pick the right one for a given task so the question really is not which one is the best but which one is the best for a given task so to give you the answer I would of course need to know the task now before we move forward into constraints and properties let's talk about these paradigms that we have today so I think these are some five API paradigms that every architect every aspiring person who is building P I should understand more or less at the minimum so we have a Web API this is represented by rest query api's now this is the represented by mainly graph QL a flat file that's also an API sharing a file with somebody I'll get to that streaming API and RPC API slides the RPC API what I've noted but I noticed over the time is that there were actually waves of these you know API programs being used first when we started with api's 2008 we had this point-to-point integrations one to one there are specific integrations for specific partners or specific customers usually over large enterprise and as you know the popularity grew we started you know hitting the ESB problems and all that web services and then then we got a lot of angry front-end developers and then we got rest or graphical this is the generic ap is this is one API provider one API being consumed by many clients all right now we are slowly getting to the next stage where we will have you know a client consuming not one API but probably many behind and many of you are already probably consuming more than one API in your application right so we are slowly getting to this scenario where there will be this many to many you know API communication and that's getting really complex and we need to automate and later make it autonomous I'll be talking about this later this this year at the API days in Paree however the main thing is that resident graph QL are not the main paradigms these days if you order you know if you make a booking if you order something and it's fulfilled by a logistic company if you make a payment if you buy you know fly ticket the reality is there is very little rest or graph QL API sits all running on Web Services and most often also on the FTP CDIs and things like this so if you are living in a bubble that the rest is you know the main for a time today well you know it is not really the choice of the paradigm should be always function of your constraints so this is going back to the constraints I've been talking about and this is probably the most important slide of this talk so I'll be talking about the colonial architecture in colonial homes you know back when when the colonists Oerlikons in 18th century vulcanizing america and they were building this this kind of buildings and they were in an environment where they have a lot of constraints around them they didn't have the technology they were like fishing bad weather right they couldn't build a big glass window they would probably like to have that one big piece of glass right but simply they were constrained by the technology they had and even if they would be able to create a big panel of a glass they would probably break it you know transporting it on a horse right so they were similarly for the you know window fellers they had to be operational not decoration like wooden shutters that will close the the roof had to be steep and all that they were building colonial homes because they were colonists and they had corneal constraints they were not like hmm I really like this colonial homes I'm thinking I'm going to build one right well guess what what we are doing today I really like REST API for graph QL api's and think I'm going to build one right that's probably not what we want to be doing we have some constraints around us that we have to listen to so what are these constraints first I think about like four hours of the constraints so first the business constraints this is when you think about your product what your product is what it has to fulfill what are the tasks is it like for for you know this trade show or is it supposed to be around for 20 years you know what are the use cases business requirements and also custom related requirements if your customers all they know they can process a CSV file well good luck on reaching them consuming graph QL right like you can try you can try to educate them and you either lose the customers or maybe you will be successful right it's it's up to your decision but if they don't understand rest or HTTP or graph QL then you might have a hard time to you know moving them to death so that that also constrains you in what you can do next complexity constraints so how complex is to do something in the API how you know there are different different types of a complexity related to this task structure related to the size how many components you have in your system if you have a lot of clients making a lot of calls you're probably facing some science related complexity issues what is the cognitive algorithmic complexity how hard it is to understand it you know the algorithms in that system so these imply and other properties these are another constraints then there are domain-specific constraints so constraints of your domain where you are what might be some you know government or business regulations so those may also imply some properties and finally my favorite cultural constraints and here's this Conway law right which is amazing rule which basically says that you are destined as an organization to create systems that are just copies or that are mimicking your communication patterns if you have two teams in one organization that don't talk to each other and both of these teams are building some api's chances are they are using different paradigms they are really implementing you know the same same things over and over but a little bit differently and it will be hard for you you know to make some use of this this ap are just reflecting the relativity and the company between the you know the communication a lot lack of communication between the teams there are other cultural constraints like the knowledge simply if you don't have a knowledge if you don't understand rest how can you build the rest API it's not understanding rest constraints you to build to not build rest API right human resources peer pressure trendiness all these constraints are coming here what is important these constraints are implying some properties of a distributed system of the product that you are building so it's not just the distributed system but actually there is a broader ecosystem around it and we'll get to that in a few so what are this property so we had this constraint now on the other side if you apply certain constraints you might get some properties so let's go through some of the properties of a distributed system of the product that you might be getting based on what constraints you will select first the performance there are at least three ways to think about the performance there is a actual network performance there is a network efficiency and there is a user perceived performance right scalability this has to do with the complexity in the science how my system scales well or not well with many components and its many clients making the cause simplicity another tricky property because you might not be saying I'm just I'm just I just want a simplicity you have to ask like what kind of simplicity you want what what do you want to be simple in your API product in your API space modify ability evolvability how easy or not is to evolve the system to make a change in the system you know some API has minded this property some ApS might need other properties right visibility this is how how well you can see in between the communication between a different components so this visibility gives us the possibility to let's say put a API gateway a reverse proxy and between two components so it can you know do some security things there working etc caching of course possibility moving your code with data deploying in different environments reliability these are some properties and actually those problems are just blast through those are promised to be induced by rest architectural style there are other properties that are relevant these days that are not necessarily covered by rest like discoverability how easy it is to discover the actions available in the API but not only the action within the API but how can you find that API hope navigating the API landscape type safety ease of development those are some of the properties that you might want to be interested or you might not care depends and of course the cost efficiency there is this ecosystem around the system that you are building which you might be interested in and its properties how active the community is how good is the to link but is the majority of the whole ecosystem and the systems actually and including the resources articles books presentation onboarding and tutorials and last but not least how ready it is for for deployment in the enterprise so these are some of the properties I care about generally not for every API if you've come to me and say hey I want to build product for this and this I might not need all these properties right to deliver that product this properties are too broad to be needed by every API chances are if you are building an API that is here for you know next few weeks only then you don't need availability you don't need to modify it right your constraints will result in different properties so we always to think about what is constraining me in what I'm doing what is my team capable of if I have you know only Java developers using certain framework am I going to teach them something different or you know do it in that framework and make it quick what is more important to me time to market or you know using benefiting from some other properties of the system but you have to pick based on your choice regardless I'm trying to now go and do the critical review look at these architectural styles based on you know what properties you are getting in general if you employ these so first rest it's super hard to get started with rest if you don't know what rest is and it's here 2018 there's maybe too many resources or maybe too few resources that are concisely you know talking about what the rest is there are some groups that are trying to fix it API Academy here having nice tutorials but still I would argue that the rest is hard to learn and even harder to master it took me a long long time to to get it at least you know some what's right and this api's are rare to find there are super super hard to find outside of World Wide Web because World Wide Web is the the biggest and the most successful implementation of a REST API however if you pull the rest API correctly you will get scalability and ability to evolve and discoverability like no other architectural style and you can tell this this is proven by World Wide Web right so here you have the original listing of constraints that comes with this architectural style we call rest I'm not going to read to them the promise is if you follow these constraints you will get those properties on the distributed system on the right hand that's the promise and that's all the rest is it doesn't give you anything else it doesn't give you framework it doesn't give you formats anything it just tells you these constraints you follow you will get that so rest comes with benefits as I said it's scales indefinitely at least to our knowledge so far it's quite performant especially if you use HTTP 2 for the call and it's proven for decades it works with any representation with any media type that's which is also nice and it's a foreign centric so it has a high design maturity because rest api is designed around the actions that you can take there and it's driven by the application state and allows for this evolution over the time it comes with cost hard to learn it is a big paradigm shift in environment when you have web services it's it's hard to explain you know web service is moving to rest it's a quite big mental step it requires the clients to play along which is also one of the sort of drawbacks and it has arguably not so good to link challenging to do some governance with risk then we have this main group what I call so-called rest api's so now if you were like asking like what what are you talking is it there is a lot of rest api's well the truth is there is very few of them the rest I call so called rest api is like let's not go there it's the most common style of api's that we have these days and usually these api's are following the HTTP constraints so what you're getting from HTTP protocol if you follow the HTTP protocol you get those constraints therefore those benefits however not all the api's are even following the HTTP protocol so things like you know using proper verbs concern separation metadata data etc these are the things that I'm talking about and and there are actually very nice described in Amazon's and Richardson maturity models this so-called API still require quite extensive understanding of HTTP to be full of chrome properly and they give you scalability so these are the original constraints from rest but this API usually do not come with the so descriptive messages and high gos which is stands for Hyper media which implies that you are not getting those properties you are not getting the simplicity of the Uniform interface and you know you are getting you are not getting the modify ability in other words it's super hard to evolve this API so if you were ever thinking about versioning and all this if you were at the conference listening to some versioning told this was because you did not flow all these constraints you are not getting modify ability so I already went through this so again it might be still quite performant but it needs some some learning too especially on the HTTP protocol level and they are pretty much impossible to develop sorry evolved over the time all right so graph QL ap is again graph goes language and framework a lot of nice libraries and tooling and this is making more specific much more specific than rest and then Wiseman said that the more specific you make something you know likely it will be accepted or a lot by people this is what we are actually seeing here and for good graph QL is super easy to get started with it is essentially remove data access it's things that we've seen before it's like SQL over you know over distributed network but it's better its vendor agnostic so far and it's quite simplify of course to SQL but it's good because it can offer unparalleled onboarding developer experience and time to market it's blowing two things few things away because it's tunneling through post usually and it right now has a lot of back shedding so things that were already invented for the other architectural stash you they need to be reinvent in here doesn't mind and hopefully will eventually happen but right now if you jump into that you won't be getting things like you know the tile authorization authentication content negotiation things like this you have to basically arrangement on your own and there also are scalability issues because graph QL is not supporting or taking the advantage of the caches that we have for the internet and worldwide web so again comes with benefits user experience time to market really really nice things I'd love to work with graph QL api's but it's also amazing it's naturally contract driven with rest or so called REST API we are advocating please please start with the contract first write the API description first before the development with graph QL you have to do it so that's very nice but again it comes with some costs client-server are coupled together hard to do evolve independently a lot of bike shooting problems with scaling I try to put this in the into big table which is a lot of columns so it didn't didn't fit here I'm going to share it I would love to hear you know your comments and thoughts and maybe you know what what is what is what do you think should be differently but this is like a scoring table on different different of these properties comparing the Stars I'm going to post it later on Twitter one other thing I want to mention there is no escaping to API design with rest you had to think up front about the use cases for what you are designing you have to understand what people want to do with your API design with graph QL you seemingly don't have to do it you just basically provide the generic access to a data set and everybody will pick up what they want right well the reality is that that's not so true because then you have then somebody starts making really with graph gross molesters to make really complicated queries blowing your system or making it really slow or you know service will be inflames so you have to start optimizing for queries not allow certain queries things like this so you have to at the end of the day understand what are the actually user doings or what they want to do the difference is with rest you have to do it first to have a good design with graph QL you can defer it to later but you will still have to sort of think about it so there is no escaping to do you know design a good API is you know understanding these cases of the users so you have to make a design choices so I would like to finish with a few examples and this is my favorite and one company we were too successful with our API evangelism we made even HR team coming to us and say like hey we heard there are these API s we want to have a REST API right let's build one so ok ok so we started and and it design very nice REST API and then I was asking more and more pushing to the use cases and we figure out that basically what they wanted to do they had this external payroll processing vendor company right and what they wanted to do is really to just once a month give them all the employees records they will batch process it and they do something with the payrolls right this is super bad example for real-time API so you probably want to just hand them that big fat file and you know every once a month right so all that I'm saying is that still sharing a file might be a viable options depends on what is the use case and you have to think about it like it doesn't make sense to make a REST API a good case for a graph QL API though is when you when you are talking to yourself I really like you know what Gatsby Jas is doing which is a static site generator but it still really gives you very nice access to the static data via a graph QL API and if you don't need the cash in there then this is just amazing what I would say you want to use rest is what we are doing in our data we had a lot of api's there let's say there is a product API and you learn about you know what about your shoe what are the information about that particular product but then you want to link into other API and figure out what is the availability in inventory b2c b2b inventory how does it relate to you know reference data API so if you have if you are having this API landscape where you have multiple API then I think rest is actually very very good choice because you can link between the API and you know follow the links from home this is a product was the availability etc etc and also I think the rest in general is a very good thing for micro services because you know those are naturally bounded context and you are navigating and mapping between those so conclusion use rest if you want to build a system that lasts if you need the content negotiation if you want to some precise authorization out indication rate limiting or interlink api's together or use mixed media types or care about scaling if you are building system there will be a lot of components then please use rest use graphic well if you are talking to yourself back in front in scenarios that's that's a very good one use it instead of so-called rest please don't do that anymore we luckily now have graph QL short term projects uncertain use cases when you need to iterate on the enero product and you need to figure out what actually is that user ones or just your going to provide the data access without the need for infrastructure education or lolly wolly this case is amazing developer experience with very little effort don't do this to both the so called REST API but always pick based on your constraints not somebody else's because you are unique thank you [Applause] excellent Z don't go too far because we've got five minutes so I could actually take a moment to ask the audience for questions yeah we got some super hazy hey Ted wanted to ask about contracts because you said that contract is a natural part of the graph QL design paradigm can you explain that a little bit absolutely thank you so the contract is being like or how I define it the description of an API what the API is a map for the API and graph QL you have to have it because that's a graph your schema it it says what the API offers what are the actions what are maybe the mutations or potentially what queries you might take and what are the data so contract here means and that applies both to API graphical and REST API is a contract is a basically API description swagger for REST API or graph your schema for graphical api's and once you define that hopefully at the start of development and the graph QL you have to do it that's the beauty of it at the start of the development or before the development then it should be binding the parties in that API lifecycle so clients knows what they can expect once the things is implemented stakeholders know what the what what is being implemented it can be tested or it's driven this the concept of contract works in both worlds but with graph QL you absolutely have to have it there is no graph QL API without graph your schema yeah so the graph protocol is the contract in a way graph your schema is the contract once once it's approved like it's Recker is a contract if it's approved you know you write the swagger right the graph QL people look at it say hey this is what we want to consume what we want to build yes let's do it that moment it becomes the contract oh thank you sure great question I think we have time for one more any takers yep way over there sir so really just think about the constraints of the environment you're in and what properties you went again so I have a question about linking yeah that's a bit of a challenge sometimes when you have like distributed micro services that aren't really supposed to know about each other huh do you have a strategy yeah so well strategy so first there have to be a will like understanding that if I have this let's use this a little example probably the API with the informations about the article shoes then you have another API which might have information about that dot product availability right normally you would have to no idea of this article in this API I put it in some you know request another API and I'll get the availability what I'm arguing here with the REST API is you can link from this probably the API to this to this inventory API and there has to be with micro services this micro service discovery the URL has to be of course resolved and it has to be a known host so it depends there are there are some you know micro services discovery tools that can help you with that but first it starts with really this determination that you want to link in between the api's and this is what made actually web and Google possible because web pages were linking not within the site but through the different sites all right super Zee even without a co-presenter well done thank you give one more round of applause thank you you

Channel: Nordic APIs

Views: 51,861

Rating: 4.7038894 out of 5

Keywords: Zdenek “Z” Nemec, Good API, GraphQL, RESTful APIs, Hypermedia APIs

Id: yLf0rIaRtRc

Length: 33min 5sec (1985 seconds)

Published: Fri Nov 02 2018