GraphQL, gRPC or REST? Resolving the API Developer's Dilemma - Rob Crowley

to noon I feel a word of congratulations is in order your last breakout session for it for this year so well Doug you've made it right so this would be a fairly leisurely session so I'll try to keep a quiet high level we'll run to about 4550 minutes so I'll leave plenty of time for questions at the end but the major question we'll look to answer today is how do we as API developers choose between grukk UL g PRC and rest so to get to that answer we're actually going to do quite a few things so we're going to go through first of all a tour of API styles and we'll look at them over time due to do if my clicker was working so API Styles overtime and what we're going to do from here is get an idea of how the thinking in our industry has evolved we're actually gonna stare at about 20-30 years ago and then look at all the major technologies that we've seen along the time we're gonna see where they're different and actually quite where there's a lot of similarity between them and we're then gonna take a bit of a pivot and we're going to look at how we actually make architectural decisions so we're gonna look at the properties with rural water systems to exposure a beer and then we'll look at how we make decisions or implement constraints which will then yield those properties as well so very much an outside-in view to it so with that context set within going to look at a few the conversations that are happening in the API industry today and take some of their rather blankets black-and-white statements and peel back the covers and then see how they actually really way up so add a little bit of nuance to each one of those points so we're gonna allowing us to make a more informed decision such that if you look to choose one of these API still Styles maybe in your company or I gave maybe in your own time that you'll be able to make a more informed decision and finally with that knowledge where they gonna look at some sample scenarios and then choose based on that maybe what's the simplest of the most appropriate one to choose so before all that a little bit about myself so my name is Rob Crowley I am the head of engineering for a company called Vista Technology so automated fare collections very similar to the oyster care that you might be aware of in London and previous till as I was a principal consultant for Telstra purple in Australia so pretty much my entire career has been in designing operating and running distributed system so API is are very close to my hat I'm also the co-organizers for DDD Perth the largest IT conference in Western Australia so about 800 attendees every year so that's grown beautifully and I'm also available on the socials at Rob D Crowley so if there's any questions that come up throughout this session or if you'd like to get in contact maybe you've taken one of the ideas in love with it please reach out I'd be absolutely delighted to help so I'd like to share a little bit about why I'm giving this talk today and I really have to confess it's a slightly selfish motivation because my Twitter timeline is an absolute tire fire you see what I joined Twitter I'm I started reading about the same time when my interest in rest started and I followed my caimans in Eric wild and I'll host of other luminaries in the API space and it was very much all this rest orientated content that I was getting it everything was going grand for about four or five years until 2015 and graphic you all got released I started following a whole host of new people it turns out these groups don't agree a lot so suddenly I would have one tweet that would come out and say you should really do this and then 17 18 different rebuttals that would come out and say don't touch it and in fact there's many of the conversations that we'll look at today as well so maybe one little example so back in 25th of May last year my birthday I saw this tweet it's 2019 you should learn grati well I said absolutely why don't I share the love so they're ago retweeted 15 seconds later Aaron Powell he's actually one of my good friends came back it's just fancy OData well this is a little bit of a playful exchange often the ones that I see are quite close-minded and again as a as a community I really want us to be able to learn and keep our minds open and it's not actually it's not just on Twitter but it's also blog posts so this came out in 2017 and it's basically declaring rest as being defunct it's calling it the new soak that it's obsolete but at the same time we have other blog posts that are saying rest api czar rest in peace and everything you know that building from now on should be great q well which is it little bit confronting for me because i've spent 10 years of my life building rest api there's suddenly old and information defunct and not valuable anymore surely not but there's also this I got a strange sense of deja vu when I was reading some of these these articles and history has a strange way of repeating itself and I actually think we've been here before so if you're a 2017 there let's wind the clock back a little bit more back to 2010 and in this case Roy fielding had just released his dissertation rest was really on vogue and we were calling so to date and that rest was gonna replace everything about soap another article from about the same time so soap is officially dead long live arrests so there's very many similarities here so what can we draw from this so if soap is dead and rest is the new soap does that make graph QL the new rest surely not but yes you see graph QL is indeed the new rest paraquad I've never actually seen pair two but I'm sure it'll be fantastic but the probable a lot of these articles have is they're very Pro one side and they're not balanced so again when we want to take it to where companies or make a decision ourselves I often feel we can end up making a choice of the technology itself and not the properties or the characteristics that is imbibes and how it then matches to the problem that we have at hand so I guess what can we learn from that so we could be rather whimsically just say maybe we just don't like XML and we get on with us but I think we'd be missing a rather large point there because really I feel the the issue is deeper seeded I feel many of our API consumers so the people consuming our API s using them every day reading our documentation calling them are unsatisfied and frustrated and I think that's a far deeper seeded problem so how can we build products that truly give the experience we wish and I repeat our community is small so again let's not get hung up on one technology or another let's work together and see of all the tools that we have available to us how can we work and choose the most effective one so it's all sounds of a dreamy doesn't it so imagine if there were no protocols no hypermedia Hills to die on no media types wouldn't that be a wonderful world we wouldn't have to argue about technology at all we'd all just get on beautifully unfortunately that's not the way that API is work API is we need to have a contract between two parties we need to have protocols and specifications such the two parties that are otherwise separated can have a conversation and understand the semantics and the syntax of the messages passed across the wire there's no escape for this so we will always be locked and looking at wire formats semantic constructs have our messages so we need to do a way that we can understand them better and actually see some of the similarities between them so to that let's look at API technologies over time and we'll start back in 1991 with a middleware called core map and this was an RPC framework so remote procedure calls so that's a phrase coined by Bruce Nelson and one of the oldest styles of distributed computing interactions and in fact this was actually deemed at the time going to be the future of e-commerce on the web however it soon fell out of favor for XML of all things then in 1993 remote data access got released and that's a way of querying data from a database over a network interface so if you're thinking from there it kind of sounds like a query interface and it absolutely is so the client thin defining the shape of the data that it was you got sent to the server the server would then process it pass the query retrieve the data send it back to the client in 1998 we got a formal specification for RPC released by Microsoft and that was based on XML sapphire we had a strug contract for how to build these distributed systems however one year later again from Microsoft so Doug box one of the authors of the four tenets of SOA released soap and soap again very much at RPC based and we had wisdom as the interface of the contract force and this really formed the vast majority of the api's that would built in this early 2000 phase so in 2000 we did have Roy fielding released his rest dissertation which imagine if we could build a POS that were in harmony with the web and we had this little bit of two and fourth for the next three to four years whirling around pretty much in parallel sometimes soap starting to fade a little bit into the background and rest API is becoming a bit more popular mainly by companies like Twitter or Facebook that were released public api's at the time in 2005 we see Jason starting to take over from XML and in 2007 we see Oh data so under the moniker of a better way to rest so released by Microsoft again touching the same style as remote data access so allowing clients a huge amount of flexibility in the queries that they shaped so instead of a canonical URI as the uniform interface in rest would define we could have clients defining any shape of data they want so incredibly flexible so empowering the client rather than having it defined by the server and that's a paradigm that was really embraced by graph tol in 2015 as well where they very much have mutations for the rights which are actually very much like our PC and then query api's for the read side so it's actually not that different to many of the other techniques that we've been using before and then in 2016 we got the latest incarnation of an RPC framework so G RPC and very much a focus on performance and code generation but again very much building on what we saw with JSON RPC and XML RPC before us so that's the technologies itself let's have a look at what was happening in the industry at that point in time so when we were building API is back in the 230 mm s it was very much for one provider and one consumer and they were very direct stovepipe integrations and this changed quite a bit with web 2.0 in 2010 when we were started to build api's for many consumers so instead of specialized for one consumer one partner you could then have many consumers so falling more into a conformist model if you follow Eric Evans and that was really a massive change so instead of trying to optimize for one use case we actually wanted very flexible api's and I think we'll see that continuing to evolve as we build richer more complex systems as well and truly embrace cloud native I think we'll see many too many interactions so far more service server-to-server lattices of api's building and again if you I mentioned a couple of names as we go through like zenyk Zdenek who talks quite a lot about this next eva loose of api's so across all this time and different techniques men still classify all of these technologies and we put them in buckets like this so query API is where we want to empower our clients to retrieve the data that want or we're favoring flexibility we have flat file API was very popular in the early 2000 so EDI or electronic data interchange so still absolutely perfect maybe if you have a flat file extract from your financial system and you need to do month end report again it doesn't need to be real-time it is absolutely still a valid form of API and if this is batch and a synchronous that this is the streaming api's are absolutely real time so you can think about serving video or maybe stop price updates but you think a lot of very rapid potentially bi-directional communication across the wire as well we have RPC api's so again G RPC XML RPC with very much calls and again with the RPC paradigm it's one component calling another component across a distributed network but almost pretending that that distributed network is not there so we're treating that as a facade across it whereas what web api is we spit up a HTTP client we embrace the web and this web api is really where the majority of our REST API or HTTP endpoint api's would land so I guess if the the overall angle of this talk is to say which is the best API style I think I have to confess now and it might be difficult to last talk and the last day to suddenly be told that there is no single best API style computing has had right so there is always a best style for your problem at hand and that's the key thing that I want to take away from today don't choose a technology and fit a problem to it let's look at the shape of the characteristics of your system and then we could work backwards what would that process look like so we can get some guidance here again from Roy fielding the man behind rest and he says the properties of this obvious system are induced by the set of constraints within an architecture so rest itself defines a set of constraint some one of them is the uniform interface constraint so with that it says that any resource in a restful api can be accessed through a canonical you arrived and then what you can do with it is denn defined by the HTTP method the HTTP methods or verbs that are that are associated with that particular resource and what we get as a property of that constraint is simplicity that you have a uniform interface and irrespective of the API you know how to interact with it however there's a trade-off to it because we're putting in an abstraction that could potentially cost us efficiency or performance so again there's not always pluses to these we have to trade off some of the constraints but it's not just about the architecture themselves there's many other types of constraints that we need to factor into the systems that we're building so there's business constraints so who are you building for are you building to a customer who has their own release schedule that you can't align to maybe you don't have controller influence over us maybe there's specific capabilities so if your customer is only capable of consuming flat files well good luck building a G RPC API for them so again you might have certain constraints that are defined by that or performance constraint scalability constraints that we can also have technical constraints so again how is this system going to operate how is it going to be robust or resilience where do you trade-off between the two so again looking ass viii fallacies of distributed computing thinking again how do we build that characteristics potentially looks out native architecture into the api's we build so again very different if you were deploying to your own data centers and then finally we have the most interesting ones all the human factors around our systems so if we're building products then how do we keep these products healthy and sustainable over time so we have to factor in things like the knowledge and expertise of the teams so unless your teams know HTTP really well then it can be challenging to build a truly effective restful api because what it does leverage all of the semantics of the underlying protocol there's the rub you need to understand it inside and out and could be quite a steep learning curve you also have to think about how you own those systems so Conway's law an observation that says the systems we build with mirror them in communication patterns within an organization so how do we build our teams that align them to the products that we build so once we take all of those constraints be it business technical or socio technical we can then see all of the properties that will be imbued in the system both around the ecosystem so all of the operational concerns but also then of the software system itself and what I do whenever I'm designing a new system I always start here I always that what are the properties that my system needs to have how is it going to need to be security scalability what are other features that I need to do and then once you have a clear idea of the characteristics of your system they're looking at what constraints you can apply that will yield those properties so how might we be able to do that in a broader sense so again we have a bit of guidance here that says well there's no best architectural style that's suitable for every problem we can compare architectural stars by looking at the properties and again looking at the constraints the particular architectural style will apply and this was actually my original premise for today's talk so I was a little bit disappointed to find out about ten minutes into my research that someone's actually already done it so this gentleman called Zdenek Nemec who gave the keynote at Nordic API is at the end of 2018 has done a very good comparison between rest and graph QL in a low level of detail that takes all of the of the constraints that are defined by rest itself and then additional operational constraints and now also then complies it and contrast it with graph UL and this is graph UL of the ecosystem about 18 months ago so some things have changed but you're still going to broad viewer a comparison between the two so again from that I will share this and all of the slides and resources afterwards so no need to take photos as we go through but we're going to do something a little bit different then and we're going to go back and look at some of the conversations that are happening the industry we're going to take these myths or blanket statements then we're actually gonna ask a little bit more questions and we're gonna go that little bit deeper and see is this actually true or to what degree so first of all let's go back to this article that I referenced in the first couple of slides that declared rest api is a rest in peace api's long live graph QL so clearly the author here saw no more value in rest api's and we have another article at the same time that said graph UL would do to rest what Jason did to XML is it really that clear-cut so again let's look at the thinking of the paradigms on the pinning graph QL so on the query side it is very much remote data access and on the right side it is RPC so actually really nothing incredibly revolutionary there and it's actually got a fair amount of HTTP or or rest semantics thrown in as well and then let's have a look at G RPC itself so again a little bit different but G RPC ties itself specifically to HTTP 2 while graph QL declares itself as protocol agnostic in a similar way to graph QL G RPC always uses HTTP 2 as the transport and he HTTP 2 is actually very specific here so I'd hate you to be what dot X it has to be 2 as a minimum and the reason for that is that it leverages a lot of the streaming capabilities of HT db2 for its functionality on the transport and schema side it uses protocol buffers or protobuf and that is both for the schema so the wisdom you could think in a soap API or an open API ramble or API blueprints contract in a restful api and then also as the data exchange format over the wire and g RPC is incredibly flexible for the types of interaction that support between a client and the server so it supports traditional request response so one request from the client of one response back also known as a unary operation but also more complex interactions such as service streaming so one request from the client can yield multiple responses from the server we also have the inverse that the client could stream multiple updates to the server and then be only get a single response back or we could have bi-directional streaming as well so again G RPC is wonderful for real-time interactions between api's where you have data changing very quickly you need to have synchronous interactions or integrations between them but if we look at rest it's quite different again so if G RPC and graph QL are really data over HTTP or data over the wire rest is a state machine over HTTP or a workflow and this is a really key point and when I talk about a state machine what I'm really looking at is that word hypermedia so again the bit of always kind of throws people out if you're looking at the Richardson maturity model it's this thing up at layer 3 but it's actually not that far at a concept if we where it's actually Everywhere's the underlying paradigm of the web so if you just look at this really basic HTML page we have hyper media controls here and the fact we have three of them first of all we have an image tag and the semantics of an image tag so whatever resource is referenced by this URL when we dereference it it will take the contents of that and put it in the align space we have an anchor tag that says when you dereference that link you will then be navigated to that page we have a form which says when we submit it it will take the data that we've captured in that form is send it to the server so are these these are all affordances which have been sent by the server which then have well-understood semantics of the client so in the same way we could have a a restful response where we can provide links to the client and the client could then use the link relation that would follow that linked is a terrible where could it go next so if you have an approval process so you might put in an order and I might then go to a pending State invite them be approved when you've taken payment and finally shipped and at any point you control the next navigations of valid state transitions for us so anywhere where I'm thinking that there is a flow and I want to be able to then tie down the transitions between that rest is a wonderful choice for that and since as I mentioned quite a bit about hypermedia I really have to say this next line is that rest does require hate EOS so hypermedia is the engine of application state and I feel that this is quite an important point and I don't mean it to be confrontational apologize if it does but I feel a lot of the pain a lot of the backlash that we're seeing about restful api is our rest dish api's is that we've taken some of the parts of arrest and then other parts are a bit difficult or maybe we haven't been able to implement adequately for a number of reasons and it delivers a suboptimal experience and I feel that's a lot of the tension that we sort of see you the community right there so I would really implore you don't build rest assure I'm firmly of the opinion that from many api's if for whatever reason you can't make the use case force or the knowledge within the team or the client you could actually get a much better result by either building it in an RPC style or a graph QL style so for our less effort and get a better outcome for us and that's actually okay because again it's not we shouldn't start by saying I want to build a G RPC API and work backwards it's just saying okay with all the constraints that I have what's the best outcome that could have so and if your API is mostly actions so an example of this could be the slack API it's an RPC API it's heavily action based and a lot again the tension with REST API zhe's where we have an action orientated interface and we're trying to squidge it into a restful URL so we end up with this resource slash increment or those sort of actions that you spend a lot of time bytes chellie about URL structures and yeah I don't really feel as that valuable but if however your API is mostly prod and you're manipulating related resources or there is a workflow then rest is a wonderful choice and in fact if there is one person you should read a lot of content from one effects someone who I've taken quite a bit of content for their blog post is actually Phil sturgeon so he could take a lot from he he writes a blog post called a Piz won't hate and why he's got a lot of very strong opinions and a lot of things there's a lot of experience behind it so I thoroughly encouraged you to follow Phil and this is a again just a proving that there's even the creators of these of these technologies don't see those being perfect for all use cases this is lee byron i like what are the creations of graph QL and he says that graph QL is a wonderful choice for Clyde to server interactions but he doesn't really see the value of it for server-to-server communications so very much where you have a client that has or maybe multiple clients with different data needs that's wonderful cuz we're empowering the client to select the data that it needs but for server-to-server calls gr pc or even rest to be a fair better choice so API Styles they address different problem spaces if we're building rest dish api's whether it be for internally within your team or two customers consider whether you could get a better outcome for less effort with exploring graph QL or RPC and I'm not saying that they are better I'm just saying that to build a REST API requires a high level of experience a dedication and you often don't see the payoff in a short time but it's really being able to evolve over decades is where the power of rests comes in and that might not be the shape of your problem at all so consider that and G OPC is wonderful for synchronous communications between internal services this to sports many different interaction bottles you get a huge amount of flexibility there so with other statement I saw that was being passed around quite a bit and this one still comes up is graph QL breaks caching but what kind of caging surely not all caching because if we look at caching there's actually many kinds we can either cash in the client so that could be your browser cache we could cache on the server side also known as application casing or we can have Network Asian or intermediary caging so again case boxes that might sit between the client and the server so let's take a look at that so with HTTP caching we can have these intermediate casing proxies so you can think squid our varnish however with graph QL and G RPC while we absolutely can still do service education so retrieve something from the database may be sticking in Redis and then send it back to the client or on the client side we can still have in the case of graph QL a denormalize client cache or you could store it in the browser cache but you cannot do the intermediary caching proxy and that's for a number of reasons not only in graft you're generally uses posts which are cashable but why are intermediate asian proxies important that if we could still get a lot of the benefit from the server side of the client and it really comes down to proximity to the client so what the speed of light is fast about 300,000 kilometers per second it is not infinitely fast particularly if you're going over copper wire so we're going with the refractive index jobs Wally so again if you can get your data closer to the client they will get it more quickly so again from a performance perspective very valuable you could also then localize the data for a number of clients prevent more expensive calls coming back into your network as well so how are we start trying to achieve this support for intermediary proxy caches with graph QL Lin and there's been a bit of a shift in the community over the last year about it and instead of using posts and pretty much using HTTP as a as a dumb pipe there's no kind of champion by Apollo in the in the node space or one of the providers they're allowing you to use queries with an HTTP GET request and also using persisted queries which are again queries precomputed and exists on the server so instead of having to pass large queries over the wire you can send it ID then have a hydration of the server but this is not part of a standard so this is still very much things that have emerged from various area of the community which is a bit of a shame because that's actually one of the big power of graph UL that you had a specification for graph QL which removed a lot of the ambiguity or the challenges that people were building with rest which was more of an architectural style and there was no specification which we could implement there is however no graph Q well specification for HTTP so again there's still a big lack there's still a big gap there so many of the cases for problems that have actually been solved by the rest community number of years ago decades ago we're still solving them today in graph QL so there's still a lot of bite shedding that's happening in the community another thing to consider as well is whether your API is authenticated so whether it's open or whether against you will have an authorization header with either a session cookie or a bearer token or some other form of identity or personalized data in there because what we should be aware of there is that intermediary caches will not cache authenticated traffic by default so again if all of your content is fairly real-time and tied to a specific identity then that changes your landscape particularly as well and actually intermediary occasions might be a concern for you at all okay so we've already got a little bit of nuance so breaks caching but there's three different types of caching do all of them apply to me maybe not and there's another thing that you should be aware of as well is they're more customizable your API is generally the less cashable it will be so in the case of a REST API where we have a uniform interface we might have slash users slash one and we'll get a very good case record for that because the second we retrieved that record there's nothing else I could do with it so the cased version whether it be for expiration based or etags you can generally be served to other users as well as other clients however the second we start adding query parameters to it so maybe being able to select a subset of fields or put an order or audit again we're creating a unique identity there and we're reducing the number or the likelihood of someone else making that same request and now imagine with graphically well where every client can make any query that they want so that's a huge level of level of power that you're giving to your clients so again the Keysha bility of that will decline so the more customizable you make your API again just consider that you will actually be losing or complicating your life on the caching side again so everything's a trade-off so actually you might be thinking actually for the API building no Casey is it that important for me at all so maybe I actually dead veer towards one option or the other so the takeaways are occasionally is that there are many different types of caching and they apply to different scenarios so highly customizable API is where the clients are afforded a huge amount of flexibility in the data they request they benefit less if Network ation is valuable to you that absolutely looking at a restful api could be a really good choice because you will be able to get data more easily to the age and best practices are absolutely still emerging for graph QL and G RPC in this space as I mentioned before there still a lot of the communities are still relatively immature in comparison to rest so there is still quite a lot of bike sharing that happens in the area this is one of my favorites REST API czar inefficient what do we do with this like how can you respond to it and I think what we really have to start looking at is what was rest for like rest was never about efficiency there was never its goal so we were looking to build systems that could evolve over decades so the client-server architecture where each could evolve independently so we were looking for longevity and reduced quite coupling and in fact many of the decisions that were the architectural constraints of arrest absolutely went against short-term efficiency right so that's a very deliberate choice for long-term flexibility and evolution but that's not to say that when we say they're inefficient that that we should be conflated with that they're not performance because there's absolutely things that we could do with this and in fact http/2 has removed a lot of the pain that might have been associated with previous rest api is usually htb would not X but what are some of the major issues that we could see what rest api is so we can either over fetch so if we have many different types of clients maybe a web client or a wearable or watch those clients can generally display varying amounts of data but if you only have one representation then you might be sending way too much data to one client and then just sending slower requests maybe using up their available bad with maybe their data allowance on the other side we could be under fetching which could typically result in I'm gonna retrieve the master record and then for each one of its children I have to dereference the children independently often known as the M plus one problem but there are techniques that we could do to tackle these so for over fetching we can use sparse field sets so allow the client to specify the individual fields that at once or maybe feel groupings so again while there's no standard around this there's a number of options that you have but effectively allowing the clients to say I don't what all of us just give me a subset of the representation and to avoid many road trips we can look at compare documents and compound documents are really the main aspect of some of the hyper media types such as JSON API or how hyper-v the application language that were quite popular like five six years ago as well and they were really looking to mitigate a lot of the issues that we had with HTTP what Onix api's and this was really one of the first things where graph Kewell came to the community and says irrespective of the shape of the data that your client requires you could retrieve all of it at exactly one round-trip to the server and this was seen as a massive boon so instead of all these individual Quest's we can now create one request have a process on the server and go back to the client doesn't that sound brilliant what we have inadvertently done though is now tied a response to the client to the slowest piece of data we've coupled all of those individual requests so if we have some data that could be retrieved really quickly for the client maybe just the domaine layout data elements and then we have some more expensive computed fields all of that data will need to be available on the server before the client sees anything so as people actually started building api's and I got stuck this myself with graph QL and we started getting them into production we actually saw there was a lot of effort needs to be invested in tuning your queries and actually then moving some of the computed items out from larger queries and actually making them separate items themselves so that we were reducing the volatility of those requests and again where there's a will there's a way the community thought okay well what happens if I could then mark certain elements as being deferred which could then be sent back to the client as a HTTP patch and then the servic then look at all of those items have finally stitch them up it adds a lot of complexity and what we should really be thinking at this stage is shouldn't really be this complicated where's that simplicity that we really want is irrelevant thinking about that simple customer experience and if we really look at all of these compound documents it was really a result of hahdve 1x where to establish a connection at the TCP level was very expensive so we had window scaling we had handshakes likewise at the TLS level we had to establish a new connection so we had to have the server hello again and that takes a lot of time to not only establish the connection but also to scale up the bandwidth on that connection so establishing a new connection for every request was very expensive and then you could also look at techniques like the main sharing as well but we were generally looking to get around the hacks or the miss or the limitations of the underlying protocol well if I'd hate you to be result resolves a huge amount of these because we can multiplex streams over a single connection so you can have one long libs connection and then many requests that go over it so you avoid all of the hassles of again having to create the TCP connection and scariest and again doing the TLS handshake as well it's not only that there's also another feature called server push and what this allows the server to do is to push resources or representations to the client without actually having the client ask for them so what you could do from here is if the client was requesting users maybe from there that you could also proactively push a number of the child records to the server as well and from here you allowing this you're allowing the server to take a lot more control over how it can optimize the sending of traffic to the clients out of fact one of the big goals of this was actually to have service optimize the loading of web pages but we found their preload or pre fresh links were actually a lot more effective on the browser space but there's open source libraries such as volcano which has been released last year that now allows clients to send additional link headers in the request which the server will then push back to the client asynchronously sort when it needs and it will be available in the server in the cache or the HTTP connection so it sounds wonderful this is something that I do expect will become more popular over time but there's still a fair amount of profiling that we need to do on server push I in the links as well I have included a link to that library called volcano but it's an interesting way where as API developers we can then look at different ways of serving resources to the client so performance so with HTTP one the cost of a handshake was really high and in fact it was multiple had shakes that we were doing them very frequently and we created a lot of a lot of hacks or workarounds for that typically compound documents but when we made compound documents we ruined the case ability of those requests again because again they were only as cacheable as the most volatile piece of data Noah HTTP - we can send all those individual requests back to the client without having to create new connections so we can do it a lot more effectively and because we can still do it in a more granular sense we still get a very high case ability from it so it's actually a win-win it's beautiful and server push creates new possibilities again toward potentially profiling the use of our API so we're seeing traffic patterns where clients generally have the set of interactions and again having that data ready for when they use them and in fact gar PC heavily uses HTTP to full stop and in fact we will talk a little bit about G RPC web which you might have heard in some of the Blazer talks this this conference as well and that's for streaming methods again so one too many requests either originated from the server or the client or in some cases both directions this is another great one so graph UL eliminates the need for versioning so graph view or we don't need a version or a POS anymore it's a bit odd because we never had to version our api's it was always a strategy it was never a requirement so why we would version our api's it was a strategy to handle breaking changes where you would change the contract on the server and you wanted to insulate a client from that effect so then you have make a breaking change create a new version that the client could decide when they want to adopt that new version so absolutely a strategy but there's other ways of handing of handling evolving capabilities and from there it's graceful evolution and this is really what has been promoted in the rest space for quite a number of years in the web as well that web page is gracefully evolved in the same way we can build our api's with non breaking changes and in my opinion graceful evolution should always be the goal so where possible supporting multiple different versions of an API as a provider can get very expensive very quickly and complicates the landscape so not only from a client perspective but also from a server perspective you could simplify your life a lot if you choose graceful evolution as your strategy however it does take discipline so some of the implications of it is that we can't add new required inputs to an operation we can't remove outputs or make them optional because again we could be breaking your dependency from the client we can change the type of a field so if it was a string we can turn it to a number and we should also be following the robustness principle or pastels law so being incredibly broad in what we accept but incredibly suspect with what we send so again being well-behaved citizens and this takes discipline but what it takes discipline on the server side you can not treat it in isolation and another massive call out is you cannot over communicate with your users so even if you are going to make a change don't rely on at sunset or at deprecation headers on your API responses and expect your clients to understand that change is gonna be coming send a bulletin update them with change requests let them know a number of buds out particularly that works where we build a lot of partner a POS so for system integrators but also internally as well and having a regular caters where we could discuss API changes has reduced a lot of the friction around timing those so if I spoke about the server previously there's a lot that the clients can do as well to be well-behaved citizens as well so if you're consuming an API and you only need three of those fields don't break if the server includes an additional fields that you're not interested in don't break if the server sends the fields at a slightly different order so don't take that response and serialize it directly into a class and this tolerant reader pattern is actually defined American Fowler's book enterprise integration patterns and it provides a lot of guidance about when you're consuming api's how do you make sure that you can do it in a robust way and in fact there's a number of other patterns of that book as well that can provide great insight into building resilient integrations between systems but if we do need to make a change and you want to deprecate a certain feature how we communicate that so I've already mentioned about deprecation and sunset headers on the response graph QL actually comes with an inbuilt feature around this and it's called deprecations where I can mark a certain field as saying this will soon be removed and because graph QL you know exactly what fields or what data every client needs you can create a map of who would be interested or who's in this field and who should I inform if I'm going to change it and that sounds wonderful in fact this was something that was really excited about because I kind of expected I'd be able to then have really targeted conversations with a subset of my my users and say this fields gonna be removed are you ok with that can we work out with the timing but unfortunately when your API use reaches a certain level of scale or a certain number of users it's kind of observed in Hiram's law everybody depends on something so you're always have uses that require at least one of the fields but there's also implicit dependencies as well so behavioral systems as well or behavioral functions in it and that's not always something that you might document in your API so you have to be really careful when you're thinking about evolving your API that were not just thinking about contractual changes but there could also be behavioral changes in your API switch clients have a dependency on as well so it becomes a lot more complicated than simply looking for a deprecation tag and in fact in many cases if you're looking to do a migration to a new service or a new version sometimes you have to deal with bug for bug compatibility because you can control for those clients even if it doesn't behave exactly as it was a rigid documented that was the expectation the client now has so if you're doing any refactoring of existing systems so again dealing with legacy codes by by Michael feathers provides a lot of guidance around how to deal with these integrations and breaking out separate components but the biggest thing we can do about Libre engine we're leveraging this is about defining the interfaces so making systems available starts by getting the inter faces right and if we don't do a fair amount of upfront design that we aired a lot of those change requests sort of landscapes we were making breaking changes for clients so the biggest thing that I could advise around this is using a contract first design approach so what might that look like so in graph QL that's your schema in GRP see that's a protocol buffer and in a REST API you have a whole plethora of choices so you can have swagger now known as open API ramble blueprints and number of others but starting with a common contract that can then be developed in parallel maybe by different teams of building a client maybe actually building out the API implementation and because you have a contract is very easy to mock against that contract as well because you have that shared interface and then when both of them are ready that could be integrated and then the loop can continue again and we found again by starting with the contract it was very easy to evolve that I'll have shared design sessions between the consumers and the producers rather than having to write code and that feedback loop BK blog or a Bo odorous so again be able to create a vibe but where it's really easy to change and update that behavior quickly we felt a door for the long run so versioning it is a technique to manage breaking changes it should be a last resource it shouldn't be your first option only use it where absolutely necessary prefer gracefully evolution absolutely not a substitute for the communicate with your users that is the absolute biggest thing about managing changes in your API and it doesn't protect users from depending on app listed behavior as well so sometimes it's not just about the interface changes another one we came across was domain modeling is purely a rest concern so if I'm using any other style I don't really have to worry about it and that's so not true if you do that you're gonna have design issues from day one so always start with your users in mind so both G RPC and rest start with an outside-in approach the server defines the shape of the operations or the queries and then you start building the mouth graph QL allows you to take a slightly different approach to this so if you were bill you weren't quite sure about the interaction patterns of your clients you could actually get a little bit of a benefit with graph gol at this because graph QL delays the responsible moment of identifying your query needs to actually profiling those queries so with graph to you well I don't actually define individual endpoints or operations to call rather I define a graph of data and each query then maps to a subsection or tree of that graph so we're not optimizing for an individual use case but the risk you pay for not putting that approach is again having a higher cost or complexity about profiling those queries later but again it's a good tactic to deal with uncertainty or if you've got to have multiple consumers each with very different needs so API design is absolutely table stakes irrespective of the style both rest and G are PCP follow it outside an approach where you have to defy the operations of the interface graph QL is different and lesson can let you deal with uncertainty in a slightly different way and it really allows you to then see how users are actually executing against the graph at runtime but again there's a hair at risk in there too so if that's all the myths that we looked at let's now take a quick look in the eight or so minutes that we have left across some sample scenarios and given what we've seen about architectural decisions and a few of the blanket statements that we've got made let's see if we can land on appropriate technologies just think it's so you're thinking in terms of some of the use cases when you go back to your offices next week okay so first up we might have the absolute simplest thing we could do just at the application webform so it might be for applied to buy a ticket or something like that or buy a ticket for an event I don't see personally why you would use anything other than rest for this I see many teams building restful building graph QL api's from very simple things like this but here all we're doing is taking a certain amount of data it's a right operation and they're sending it back to the client unless you have wildly varying data querying requirements I think there's simpler options forward as well and in fact again I thought I think we'll see this is the year that a lot of malcontents will start growing with graph gol API is where we've built them maybe not for the appropriate use cases that were being burned by trying to cheat or operate them or the overhead of the inherent complexity of them so really understand about what's the simplest API approach that you could have here problem at hand another case that comes up quite a bit particularly what being worth of a client's who have built highly granular services sometimes called micro services and then looking at how do you actually take that impedance mismatch a very granular set of api's here that versus what a client needs an SBA and this is typically where we were put in and a aggregate API or maybe a back-end for front-end where we can aggregate a lot of the calls and then send it back to the client and in fact this is a place where graph QL absolutely shines because it allows you to connect data from many different data sources so it could be a relational database could be a graph could be a file graph URL is absolutely agnostic of the data source and that allows each one of the clients to then query the data that it needs and it gets optimized over the wire so in many cases we see putting in graph QR as a layer over the existing set of services to optimize the delivery to different digital channels as being a very sweet spot for graph QL and typically graph QL can be brought in after teams have felt pain with an endpoint driven approach where maybe we didn't profile or define those endpoints appropriately so we're having a lot of over/under fetching happening with those clients and that's actually a pattern that we follow did quite a number of our consulting engagements as well and that also allows you to then create an abstraction point where you can start refactoring some of these implementations I get without affecting the client so we go decoupling change so if that was web what about mobile so if we want to have a BFF so again a back-end for front-end and in this architecture the API is actually owned by the client team and this is something I've been playing with quite a bit myself and I'm actually thinking that G RPC is actually a wonderful fit for this particularly in the native space which I'll explain it a little bit because what this guy lets you do is get one protocol end-to-end in your stack so you can have one place where you share all of your proto files and then be able to do all of the code generation off all those files themselves and the beauty with a native mobile app as well as they can you can use HTTP to end to end whereas there's an issue with G RPC and that's in the browser space where the browser's don't expose an API to the sufficient level of granularity to ensure that you use HTTP 2 so we can't actually use pure G RPC in a browser or if you're in a web component or a blazer app as well so there's a couple of techniques we could do but particularly in the native space G RPC is are really those fit so for micro services so again I'm not going to say in this particular case any event-based micro services so if you're looking for synchronous coupling so again more orchestration style then again I see a huge amount of value in G RPC and the co jet particularly if you haven't standardized your runtimes so if you're looking at having maybe some of your API was written to java summin summin c share some in c++ any other language having approached having a protocol file a pro tip off the fighter there'd be able to co-chaired the client to the server side and keep them in sync that way is a very powerful pattern but what can we do then about G RPC in a web app and there's actually a companion protocol to GRP see it's called G RPC web and it is actually quite different because the purpose of G RPC web is to enable you to create compatible G RPC traffic's over HTTP 1x so that's really the goal so for environments where you can't guarantee HTTP 2 then you can use G RPC web so what does this look like so typically you would have a browser or in fact it could be a service side like like an app service in a zoo because that doesn't let you support HTTP - yes either so you can actually think of it as an outbound call from an app service as well and then you could start with the RPC traffic do your a geo PC web traffic go - 1 . XO then typically you would wrote that through a proxy so it could be Envoy which is the data plane side care in sto and that will then convert the HTTP 1 dot x gr PC web traffic to true G RPC traffic but you are looking at introducing a separate G RPC proxy so two days ago James Luton King released quite an exciting post saying that in dotnet they've actually supported actually no created an experimental package that allows you to issue G RPC web requests directly and have them host and have them served by a server without an intermediary proxy so that means that you could have at SBA or you could have a blazer web component app make a call to an azure app service over G RPC compliant traffic or b8g RPC web traffic and what this lets us do is get the common protocol buff driven workflow and then when the work to complete G RPC supports for app services become available it could be transparent to change so it allows you to adopt some of these techniques now this is absolutely still an experiment but I'm quite excited about the separate piece of infrastructure being removed there is a got Schuette RPC web though is that you lose a couple of the interaction types so bi-directional streaming and client streaming and no longer options you can still do you two recalls or you can still do service streaming but you don't get the bit of options ok so what have we covered in today's talk so we started by looking at API technologies over time and we actually saw there's a huge amount of similarities between them where a lot of it is remote data access and then some form of RPC on the right so they're actually a lot of the arguments are a lot of the discussions that are happening in the industry are actually about what's different not what's the same from there we dug into a norm of the conversations that are happening in the industry and we peeled back a little bit more data so that if you're looking to choose one of these technologies that you can get past that first it will never work because and be able to have better conversations around this finally we took a very brief view at some of the major use cases that I could see in my experience where I used what are these technologies or not but please I really see a successful talk as being a sales pitch for your future time so if I've encouraged you to look into one of these technologies or learn a little bit more or have an effective conversation with your teammates that that would absolutely be a wonderful outcome for me so thank you so much for your time I do realize there was a a lot of competition as for all slots so I really appreciate your attendance thank you

Channel: NDC Conferences

Views: 79,469

Rating: 4.8859973 out of 5

Keywords: Rob Crowley, Tools, Architecture, Testing, GraphQL, gRPC, REST, WebHooks, API, HTTP/2, NDC, London, 2020

Id: l_P6m3JTyp0

Length: 59min 25sec (3565 seconds)

Published: Fri Feb 28 2020

Reddit Comments

[u/trashbuged]

Interesting contalk but misleading title.

The talk is about history of APIs, and a bunch of best practices for handling changes in your API, improving your API performance with HTTP/2, managing mobile clients... Nice but a little too "all over the place"