Nate Barbettini – API Throwdown: RPC vs REST vs GraphQL, Iterate 2018

ladies and gentlemen please welcome back Alex Salazar so first I love the music okay so first they thank you all for attending the build track we're really excited about this track I hope you guys enjoy the talks that are coming up but with that I'll introduce you to our first speaker his name our batini nate is on our developer team at octa he is a developer advocate Nate and I've been working together for what three years now three years now he's one of my favorite people he cut his teeth as a c-sharp developer and an angular developer so he has great experience in in that stack he's also the author of the little asp book which i'm probably miss naming but it's a it's a it's a great book if you haven't picked it up and he's gonna be talking today about you know API design and this talk API throwdown so with that Nate hello everybody thank you Alex I'm super excited to kick off the build track here at iterate and talk about API design which is a very fun topic I have a confession I have built some pretty bad API so myself but I'm guessing that some of you have probably built some pretty bad API stew just as a quick show of hands who here has built any type of API big small public private okay that's like it's kind of bright but it's like most hands just give me a shout out what what styles and patterns were using were you building REST API is rebuilding RPC APS what was what was it everybody's building rest okay very cool what's that graph QL somebody works at Facebook that's cool that's very cool so rest graph QL anybody doing anything with G RPC or TWRP RPC okay one soap oh no you got me I actually don't have anything about soap in this talk I'm I apologize what's that so I thought it would be really interesting to talk about some of the big dominant styles of API designed today at a high level and talk about how they compare how they contrast and kind of jump into this debate that's going on so API is in the API economy are hot topics everybody's talking about them it's a big it's a big thing now but we don't always talk about API design and it's not always easy to answer the question of how should I design my API what are the best patterns what what makes sense for my particular needs what for my particular API so this is a hard question to answer and if you pay attention to Twitter and the blogosphere and conference talks I don't know who goes to those you get the idea that there's this huge debate going on between the fans of RPC and the fans of rest and the fans of graph QL and the the few strong so people that are left the this is a debate that's been going on for a long time over ten years it's first between RPC and rest and soap and now Facebook jumped into the ring in the last couple years through graph QL in the mix and now it kind of reignited the debate all over again my favorite tweet I think that I've seen so far is REST API czar now rest in peace api's long live graph QL which makes me think that the author likes graphical a little bit now religious debates and holy wars and arguments are a lot of fun right as developers we love arguing about browsers and Mac versus Linux and and vim versus Emacs and all that stuff the it's fun to debate and the debates can be informative but sometimes those debates can also miss the point I think in this case I think that this debate misses the point a little bit because a lot of the debates especially recently have tried to frame the frame the conversation like this where we have this linear this linear evolution or a linear progression where a long time ago we used RPC but that sucked so we replace it with rest and then that sucked so we replaced it with graph QL and that's like the best thing that you could ever imagine right now the problem with this very tempting way of looking at API design is that I think it misses the point the point is not that graph QL is the best thing for every situation or rest is the best thing for every situation the point is that these are actually different tools for different jobs if I'm building a house I can't only use a saw I have to have a couple other tools in my toolbox so when you're designing an API instead of thinking about it like this what you're really doing is making a ton of different decisions all the time all these different design considerations about what you want to make important or what is important to you and what isn't as important things like do you care about whether your API is tightly coupled to the system underneath sometimes that's fine but other times you don't want tight coupling you want some strong abstraction there sometimes you want ApS that are very high-performance as they communicate and send messages to each other and it's totally fine for them to be very chatty on the wire on the network but other times you don't want that Chad miss you want very low network latency or very low network overhead and we could go down the list I wanted to call this the five C's but see five DV is not as catchy and I couldn't come up with a good acronym for that so there's a lot of design considerations what we really should do and strive to do as API designers or API builders is understand all of the trade-offs that go into various styles of API design that way we can pick the style that's going to fit best for a project that we might build so that's my goal today I'm going to talk about each one of these three major design patterns today RPC rest and graph QL come at it from a very practical point of view and help you understand the trade-offs so that you can at least have a framework for trying to decide how to pick a style or pick a pattern for building your API I'm not myself a rest Afar Ian and I also don't work for Facebook so I try to be a neutral party as I can be in this debate so if that sounds good let's jump in and take a look at these three patterns and then at the end we'll sum it up and talk about some common scenarios where I think I have an opinion on what the right style of the right pattern is to use in particular cases so let's talk about RPC there were a few people who said they were using RPC but the majority of room said rest so I think our PC is a really interesting pattern it's been around for a long time depending on how you count it it's this the 80s or maybe even the 70s that this pattern started started being used a lot of people think that an old pattern means that it's it's bad or outdated but I don't think that's the case I think there are specific cases where our PC is a still a fantastic way of building the API today if you're not familiar with this pattern it's very straightforward and simple with our PC the big idea is that we're calling a function on a remote server so if we take the functions that maybe already exist in our system and put them on top of some transport like HTTP and wrap it with an HTTP endpoint we have arrest our PC API this fits really well with APS that are very command oriented or action oriented because with a function you're calling you're invoking something on another system so let's take a look at what an RPC API might look like let's imagine that we have a system that deals with say threaded conversations and messages it might be a chat system or maybe I'm trying to beat mr. Atwood at his own game and I'm building the next great forum software I don't really know why I would do that it's a bad idea he's done it really well so let's say that in our underlying system we have a couple of functions we have a function that will list all the conversations in the system and we have a function that given and conversation ID we can list all the messages in the conversation and then given a particular conversation ID and a string or some text we can reply to a conversation and add a new message into a conversation if we take those functions that are in the system and then wrap them up into an endpoint we might have an RPC API that looks something like this we have a slash list conversations endpoint a slash list messages endpoint and a slash send message endpoint the thing that's really easy to understand about this is that in every programming language that we use on a day to day basis we have this metaphor of calling a function no matter what if it's a backhand language or a front-end language we have this metaphor of calling a function by name passing some parameters getting response we literally just take that same metaphor and put it on top of HTTP or some other transport we have a rest RPC API I gotta stop saying that RPC so the interaction between a client and the server in an RPC API is very straightforward and simple and easy to understand the client could call that /list conversations endpoint get a response that has all the conversations in the system it might be responding with XML maybe JSON probably nowadays but this is straightforward also straightforward to get all the messages in the conversation and straightforward to send a message or reply to a conversation if if HTTP is our underlying transport then it makes sense to honor all of the HTTP semantics around verbs so getting or retrieving information would be proper to use the get verb but if we're mutating information or changing something we should use put or post because those are unsafe operations so like I said this is simple it's very straightforward it's very easy to understand let's say that this system is running it's already running in production we have a client an app or a JavaScript application that's hitting this API and then we get a new requirement we get a new requirement for pulling down some author information for a particular message we want to see who wrote a message well so far in our API definition we don't have any way of getting those author details but fortunately we can add a new endpoint to our C API very easily we just need to write a new function maybe that's get author details or get author info throw that behind an endpoint and we have an endpoint like slash get author info that the client can hit it's very easy to add new functions to an RPC API and on the downside it's very easy to add new functions to an RPC API so that can be a bit of a problem sometimes I'll talk about that in a second if you think that RPC is old and outdated and not used anymore then there's some actually really interesting things happening in the cutting edge of RPC today you might be surprised to know that companies like Google Netflix Facebook eBay twitch all use RPC internally heavily they use specific high-performance variates variants of RPC like Apache thrift gr PC and twerp to do extremely high performance low overhead messaging when you have a large internal micro-services system that needs to communicate between micro-services maybe millions or billion times per day you don't want a ton of Network overhead for each message you want those messages to be really small you want the communication to be very clear and this is actually a really good fit for RPC and that's why some of these really big companies use it for that reason just to recap RPC is super easy to understand it's very simple RPC clients tend to be very simple in many cases they can be automatically generated just given a list of functions because the interaction is so basic RPC payloads tend to be very lightweight and easy to understand very low on the network low overhead on the network and it can be very high performance so that's the good part the downside of RPC and definitely why it gets a bad rap sometimes is that RPC tends to have very high coupling to the underlying system what I mean by that is with RPC you typically don't have very much of an layer of abstraction between the functions in the system and the external API because in many cases you're just taking functions that already exist and making an API out of them the problem with that is that you it's very easy to leak details implementation details about the underlying system into the API and then the client has to start worrying about how your underlying system is actually designed instead of just worrying about the API they have to worry about if there's going to be any side effects to calling a particular endpoint or even just what endpoint I need to call because I don't understand how you're naming your functions RPC API is typically also have very low discoverability and by discoverability I mean how do I know if I've never used your API before how do I know even how to start how do I know what to call in your API generally RPC API is just have a big bunch of documentation that talks about every function you can call but that's not always helpful either what if I don't know which function I need to call there's not generally a way to introspect the API or send a request and start to understand just based on the API requests what I should call and finally one problem that is a more practical problem with RPC API is that you typically get something called a function explosion there's probably a more technical term for it but that's what I like to call it something like this I've worked on some api's that definitely ended up looking like this and and much worse where it's so easy to create new functions that we just do that all the time so if the list conversations function doesn't quite return everything I need I'll just make a new new function called list conversations v2 or list conversations v3 and we end up with this big huge list of functions some of which overlap but this is hard to understand if you specially if you're coming into this API cold or you're maintaining it so the counter to this function explosion is having a better abstraction between the underlying system and the API in other words we could solve this problem of being too tightly coupled to the underlying system if we force the client on the server to be more decoupled to have a stronger layer layer of abstraction between them and that's exactly the goal of rest so rest is the most common style of API designed today on the internet by far it's been that way for a while it's a very successful pattern and it's not even really a framework or a spec at all it's really just an architectural style it was originally described in a famous thesis a famous paper on internet architecture by dr. Roy fielding and you kind of get the sense that maybe dr. fielding had used some very frustrating tightly coupled api's and then in a rage he wrote this new style called rest because rest is about the as far opposite as you could possibly get from a tightly coupled api rest has a strong goal of decoupling the client of the server as much as possible so in rest instead of modeling functions as endpoints or functions in an API we model resources and collections of resources and links between those resources or relationships between resources and modeling resources instead of functions leads to a very different style of API design it's very very different flavor and done correctly this can lead to a very powerful way of decoupling clients from servers which solve some of the problems that people have with our PC api's I like showing an example just to illustrate so let's take a look at that same domaine that same problem of having threaded conversations messages in those conversations maybe some user information and see how it might be modeled in a REST API in a REST API we don't have a list of functions we have an entry point you can imagine that if I fire up my API client and send a request maybe it's postman or even a browser I send a request to your API just on the root of your API and see what I get back what I should get back is a document that describes what can I do in this API where can I go I need some metadata so I can understand how to use your API in our domain we have a very simple simple structure so maybe the resources we decided to model what we're a conversation and a message that means that I have a conversations resource and an endpoint that represents that conversations resource and a messages resource represented by a messages endpoint now this document that I got back describes that I have this thing called a conversation and it has it lives at this particular endpoint and some other metadata oh by the way it's a collection you can expect that I would get multiple items back or multiple resources back if I send a get request there and so on if we then took our API client and just follow that link to that conversations resource then I'm starting to get some information back about the conversations in the API in the system in this case I have an array that describes that each conversation has its own location its own canonical at Absolute URI in the system and they also have properties of their own so title author a list of messages you can start to see that we are describing a style that's a lot more like how the web works instead of calling functions if you imagine the metaphor of a web page that has links to other web pages and a whole collection of web pages that make up a website that's a lot closer to the style that that an a RESTful API shoots for or aspires to the cool idea here is that without any external documentation at all just by inspecting the requests that are coming back from your API and looking at that rich med I can start to understand how to use your API without any other information without any prior knowledge so I could get all the messages in a particular conversation by following that link and grabbing that messages resource or sub resource in this case and that that metadata is not limited to just describing where to go where to link to in the API I could also describe operations so let's say that creating a new message resource is the equivalent of replying to a message that's how I would reply in my API so I could actually describe in my in my metadata that I'm returning from the API that if I follow this particular link but use the post method instead and pass these particular parameters then I'm creating a new message resource this if the if the metaphor that we were using before was a website made up of web pages that link to each other then this metaphor is like an HTML form an HTML form has a form tag and some input tags and says method equals post and an action somewhere and if I fill out that form or interact with that form I follow those instructions and send off a request of the API to create a new message resource that that new use case that we dealt with in the RPC API of needing to get some author information which in the RPC API just meant we needed to create a new function in a REST API we may already have all the information we need in fact in the REST API if we decided that there was a resource called authors and the message resource linked to the author resource that created that particular message then we don't have to do anything anything else in our REST API we already have all the resources there that we need to be able to support this new use case in the client of getting the author's information let's try adding a more complicated requirement so let's say that maybe in our app that's interacting with this forum software or chat software we have a new requirement that says that we want to have a new widget rendered on the side of the page maybe when you hit the home page that says here are all the top conversations in the network here's the most recent reply by the most recent person who replied to this message for the top three conversations well our PC API would probably have to build a new method that that returned that exact information but in our REST API the client is able to do this already because of the abstraction that's available in the REST API we already decided that though all those resources are available so now it's up to the client to just say oh well I need to get some resources from over here and then I'll follow some of those links and get some of these resources as well all that information is available and the client can just interact in a new way with the API so this is really cool if you're an API designer because it means that you don't have to know every single use case every single thing that a client might want to do in the future you might build your API and then five years later somebody does a new thing builds a new client that does something totally different that you weren't expecting but they're able to do so because you decided which resources you wanted to represent Express in your API built the metadata that described the links between those resources and the client can do whatever they want so that's pretty cool so you might be thinking all right Nate I've used a lot of REST API sand not all of them looked quite like that unfortunately in our industry the term REST API has been like pretty badly overloaded it now means a lot of different things to a lot of different people and that's unfortunate I've seen sometimes people describing the OAuth protocol for example as a REST API but Roth doesn't really have anything to do with resources it's a it's a authorization protocol so a lot of people think that if I have an API that just returns JSON and it uses get put post delete every once in a while then it's a REST API but that's not true a REST API a truly restful api should express a lot more than just i'm using those HTTP verbs another problem that REST API has have sometimes in practice is that we may start out with every every best intention of modeling resources and links between resources and all that good restful stuff but as programmers it's so easy to slip back into that that comfortable metaphor of calling functions invoking an endpoint on a remote server that we end up somewhere in between rest and RPC we end up with something not restful but rest ish kind of like a restful procedure call type of API the the highest ideal or the the nirvana of a rest api is this thing called hideous which is a mouthful it stands for hypertext as the engine of application state this is a really fancy academic way of saying exactly what I've been showing you in these examples which is the client and the server their communication should completely describe everything that's possible in the API another way to say that is there shouldn't be any external documentation required to interact with your API I should be able to point my API client at your arrest API and get back all the information about where I can go what I can do how to use your API this is it's a difficult thing to achieve and even really good REST API eyes today don't always do this it's really it's a really difficult thing but it's also a really cool thing if you have everything in the application state described in the hypertext in the in the responses coming back from the API that gives you the ability to really decoupled the client and the server really well which allows the server to evolve independently if necessary and the client to evolve independently as necessary as long as they agree on the common structure that they're going to communicate this stuff with as an example web servers and web browsers have evolved quite a bit in the last 20 years I think we could agree but because we all agree on this fundamental markup language called HTML we're able to keep everything working we don't have to create new versions of browsers that support a completely different way that server X responds versus server Y responds if you read dr. Fielding's thesis he explains that this idea of decoupling the client on the server and using the hypertext to describe what's happening in the application state as necessary to build systems that are that are stable and have longevity over decades not just weeks or months or years but building something that can be flexible enough to evolve and and and grow over time so that it could be a stable system for 10 years so some of what's happening at the cutting edge of rest today is is making it easier to model that that hypertext those responses that metadata so specs and schemas like hal and json api and ion and siren and there's some others make it a little bit easier to to replace the fact that with web browsers and web servers we have HTML which is a common markup language that we all agreed on but with rest we don't really have a common language unfortunately which makes it a little trickier but schemas like how an ion and json api try to fill that gap and make it a lot easier to decide how to model this stuff in your restful api so to recap the advantages of rest are the big one is that clients and servers can be strongly decoupled we have a good layer of abstraction and that means that the API has the flexibility to evolve over time and one big thing that a lot of people overlook because it's kind of implied and people don't always talk about it is that a REST API is expected to reuse a lot of stuff from HTTP which is nice things like HTTP verbs of course but also HTTP caching semantics and HTTP content negotiation there's all these tools in the HTTP toolbox that are really nice to have and instead of reinventing the wheel rest just says oh yeah you're using those which is really nice some of the problems with rest is well I already mentioned there isn't a single spec that everybody agrees on about how REST API should be built so even within the community of people who love rest and think rest can solve every problem there's still tremendous disagreement about how you should structure a REST API which is a little frustrating it'd be a lot nicer if you could just go out and buy a book that said here's the exact right way to build a RESTful API for your scenario it's a lot of work to kind of take a step back and think about how you should model your resources and which resources to model and all that stuff some of the the specs I mentioned how I on JSON API can definitely help with this the other problem that sometimes people have with rest is that rest payloads can get kind of big so especially if you're doing this this Nirvana of hey Dios where you're returning a lot of rich metadata so the client can understand everything it needs to understand about the state of the application just in your responses well those responses tend to get kind of big they're loaded down with metadata and rest api's can also be a little bit chatty what I mean by chatty is it traded by that last example remember we added a complex use case and the client was able to do it because they could just orchestrate a number of different endpoints hit a number of resources get the information they need what we had to make like five or six maybe ten different calls to the API to get different stuff and that's perfectly fine if you have you know a big network pipe lots of bandwidth coming in that's fine but not everybody has a big network pipe and a lot of bandwidth coming in sometimes you're on a phone and you're in a bad 2g cell area and you have 500 millisecond latency just to make a single request not to mention ten requests so this isn't always a problem but sometimes it's a problem and this was one of the driving factors behind Facebook and their invention or a description of the graph QL style I'll explain why in just a sec so graph QL this is the newest newest and definitely sexiest thing to come around an API design in a while this is what people talk about on Hacker News and stuff graph QL takes some ideas from RPC and some ideas from rest and then throws a lot of new ideas in there and we get this very different style that's really interesting and kind of cool instead of modeling functions and instead of modeling resources in a graph QL API we deal with a query so I can say to the server hey I want information about you know users messages and conversations but I only care about maybe two of the fields on those objects I don't care about all twenty other fields you have and I can do that I can say here's exactly the things I'm interested in here's exactly the fields and subfields and linked objects that I want go get them for me bring them back and leave out everything else and the server will go do that and and return exactly what you want which is kind of cool the reason that graph QL can do this is because graph QL starts with a strongly typed schema so this is a description of all the queries that you can possibly make in the graph QL API and all the types that they return so everything is strongly typed kind of like if you're in the JavaScript world this is kind of like typescript for your API you describe all the types all those linked object types and everything in the API and then the graph QL client can say all right I'm gonna start with this query and I want the title from one thing and I want the author from a different thing and go out and get it for me you can almost think of this as like sending a sequel query to your API instead of calling a function or going and get some resources so let's use that same exact domain one more time and look at how we might model that in a graph QL API we would start with a query in this case we have one query available called list conversations and it returns a conversation object that conversation object has some properties and we can say in this particular instance in this particular query we only care about the title and the we only care about the title of each conversation and then Plus in each linked message just the text of that so we're able to kind of traverse down this object graph and say from the parent I want this stuff from the children I want this other stuff and so on we send that off in one single request to the server and that comes back with a JSON response with exactly the shape of the data that we asked for and then if we want to go deeper we can we can say also I don't want just the title from each conversation and the message text from each message I also want from each author of each message I just want their name and that's what we would get back so same use case as the REST API we look before they can both solve the same problem in this case this is one call instead of like 10 calls this if you look under the hood of an app like the Facebook app for example the Facebook app when you open it up it sends this big massive query off to the server all in one fell swoop it sends a big query that pulls down all this stuff about your newsfeed what your friends are up to which other friends liked your friends stuff all this very graph like data pulls it all back in one single request and and uses that to populate the UI and render all the widgets in the Facebook app and this is really nice if you're on a spotty connection bad connection because instead of making tons of different requests we just made one and that's easier for the network to handle in some cases graph QL can also do mutations it can also change data so we can declare something called a mutation where for example I'm replying to a message provide some parameters and then that response is also strongly typed so I have a strong type coming back like a message typing I can say well in this case I'm only interested in the ID of the message coming back for example so graph QL has some very cool advantages it was built originally for a very nice problem to solve this like network latency overhead doing everything in one message type of problem and then eventually it became a little bit larger in scope solving some bigger problems as well but low network overhead is still one of those big advantages and it has a type schema which is kind of nice because we can get some discoverability from the fact that the graph QL API in advance publishes exactly what it can do so I can take my graph QL client pointed at the graph QL API and send a request to just find out what queries available which is nice and of course it goes without saying hence the name it fits graph light data really well so if you have data that you need to go really far into linked relations or or a graph in this fits really well if you have very flat data probably wouldn't fit very well some problems at the moment with graph QL is that graph QL is definitely the most complex of these styles we looked at RPC being really simple rest is kind of like simple in theory sometimes difficult in practice graph QL is more complex it trades off some complexity for some power more powerful a little bit more complex some things like caching can be really tricky in a graph QL API because we aren't reusing those HTTP caching semantics the way a REST API does so graph QL API is almost always use the post verb which has some very specific meanings in HTTP one of which is don't ever cache this so you have to do a lot of custom caching stuff in a graph QL API and if you're using kind of the normal patterns in react react and redux a lot of this can be done for you but it does it does get complex to do things like caching there are also still some best practices that are still kind of being worked on or solidified by the graph grill community one of which is versioning which is currently in a little bit of an awkward state I think in graph QL currently the best practice seems to be that you don't version your API at all queries can change over time and that's just fine I'm not sure exactly yet how that's going to work in practice because a lot of times you need some stability over time that old clients won't break but we'll see what happens so returning to our original discussion of all the design considerations that go into an API each one of these styles are BC rest and graphic ul make different decisions different assumptions about which one of these design considerations is most important rest trades off some great abstraction and great modeling of your API as resources for the fact that it tends to be a little bit heavier on the wire and a little bit chattier that may not matter for your case but it may depends on if you're working on mobile or not I guess our PC is very simple very straightforward can be very high performance but it tends to have very tight coupling so maybe not great for a strong external API or an API service the question that we started off with which is which API style is best I think is actually not quite as good of a question as who uses my API what is my API for what is my PA API going to be used for so let's look at a couple of common scenarios and I'll give you my opinion which you're welcome to decide whether you agree with or not but this is my opinion on a couple of common Styles let's talk about a management API or a cruddy pie this is a lot of times what people mean when they just say I have an API so most of these management API such as the Twilio API the stripe API the Stack Exchange API the octa API these are all ApS that are focused on managing objects in some system so in the case of the Twilio api you're managing subscriptions or or messages or things like that in the stripe api or obviously managing transactions and and payments and orders but in general we have some objects that we're modeling and it's important especially in the case of public API services it's really important to have strong discoverability good documentation there's going to be lots of different clients hitting my API so in this case I think rest is a really good fit it fits that object model or resource model really well and specs like eye on how JSON API that I mentioned before make it a little bit easier to make decisions on how to model this and return good rich restful metadata now not all API is that our public API services not api's our management api's some ApS are really just focused on sending commands to a remote system so and a good example of this if anybody here has built a slack a Pia slack bot the slack API is very command focused it's all about join a channel leave a channel send a message and the designers of the slack API decided to model in a very RPC like style which I think was the right decision because to model this as a REST API we would have had to try to kind of force in some idea of having a channel resource and that would end up just getting like a lot more over bloated for what this particular API needed to be they just wanted it really small really tight really easy to use so like a command or action focused API can fit really well with RPC another thing that does fit really well with RPC is that I mentioned before was internal micro services so in a lot of internal micro services we have a situation where we would need to have very high message rate very high message performance high network performance and we don't want to spend a lot of time transmitting a ton of metadata over the wire like a REST API does so things like gee our PC and TWRP are a really good strong strong case for micro services because in the case of G RPC for example G RPC actually uses HTTP 2 under the hood so that it can even optimize the network layer and make that as efficient as possible when you're sending millions or billions of messages per day between different services sometimes depending on your particular use case sometimes rest makes sense for internal micro services too if your goal is not as much high network performance but having a stable API contract between teams that may be published totally different micro services and you need to make sure that they don't break the communication between them sometimes rest might be a good choice here as well and finally if you're building api's that are heavily used on mobile clients or they're very graft data focused you should definitely check out graph QL it's really interesting I think it's still a little bit early but it's starting to gain a lot of traction even for example github started using it as their the new version of their public API - which is a really interesting experiment I'm really excited to see how that works over time but this is a really good choice especially if network performance and single message payload optimization I guess you could say is really important for your API it is obviously important to say it goes without saying that there's no silver bullet here I think this is why a lot of the debates can miss the point so the point is not rest sucks RPC rocks or graph QL rocks rest sucks whatever the case may be the point is that for every API project there's going to be different requirements different needs and I think my personal opinion is that the best way to approach this is to start with a very use case based style try a few small use cases with a particular style and see if it works see if it fits you use case and and solves your problems if it does try expanding the use cases and see if it fits more use cases if it doesn't try something else the goal should always be understand what patterns fit my particular use case best so I'm just about out of time but I wanted to leave you with a couple of things that you can use if you want to learn more so if you're interested in digging into the rest side of things my coworker les Hazelwood is a much much better expert on REST API design than I will ever be he's a fantastic expert on REST API design and he has some great videos up on YouTube where he just discusses REST API design for like an hour and a half so I would definitely recommend looking at blessed Hazelwood on REST API design if you are interested in that and if you're interested in kind of a cutting edge of graph QL stuff check out my friend Erik Bayer also on YouTube he has some great talks about best practices in graph QL how that community is starting to like shape up around a lot of best practices another thing I really like reading is Phil sturgeons blog at Phil Sturgeon UK he talks about all three styles of API design and when it makes sense to use one when it makes sense to use another and what I really appreciate is that he busts a lot of myths that a lot of people kind of tend to repeat about API design he also has a book called api's you won't hate at api's you won't hate com which is a fantastic read if you're interested in this so that's about all I have today we have just a little bit of time for Q&A if anybody has any questions but other than that thank you so much for your time enjoy the rest of the build track here at iterate throw your hand up if you do have a question we have time for like maybe one sorry uh what would you like to recommend for like API documentation for API documentation interesting well I'll I'll respond to your question with a question is it important to you for the API documentation to be written by a human or by a machine human by human okay well the reason I ask is because there's some cool stuff that you can do with things like swagger to try to auto generate some API Doc's but I don't the benefit of that is you get lots of Doc's but we all know that sometimes auto-generated Doc's like don't quite go all the way I don't have a strong opinion on human human written Doc's I think I've seen some like really good API Doc's from from Twilio for sure from stripe from PayPal and a lot of a lot of places use lycra structured text they use tools like that to write API Docs but are you asking more about like how to format them or what tools to use what tools I would definitely look at restructure text I like I personally like writing in markdown but rst markdown pretty similar let me think sphynx actually is one one thing that we used a lot building our own API Docs because it has just enough power to be able to handle a lot of scenarios where you want to have rich Docs but not quite so much that it's like overwhelming amount of complexity so I would probably start with something like read the docs dot IO as a simple case or like github pages and then when you feel like you need a little bit more power graduate to something like Sphinx awesome how about one more we have time for a little more one of the most common challenges when making the API which I really hate is to define the schema okay do you have any recommendations like on something that would make it go faster especially for like graph QL seems exciting but then I got a do that scheme over specification again yeah yeah were you defining schemas for like a restful api no I was using I was using sales jeaious which does the rest api itself but i have to do all that all the javascript files for each data table i'm using yeah it was interesting i was having a conversation with a friend of mine talking about graph QL and he said he was really excited about graphic UL because because of the fact that it forces you to write a schema it gives you like a path to how like a clear path on how to create your API and get to some like finish point whereas with rest it's like a little bit more fuzzy I don't know if I have hit the finish point yet but on the flip side what you said it's a lot of work to build that schema - I don't have any recommendations on tools per se I think that I think that's a definitely a situation where you can over engineer it I think it's I would personally start out with with something really small if you're using a tool like sails or something that makes sense but a lot of times you can start really small and just start with like swagger or even nothing like I've I've sketched out api's in like notepad first before I went and build it I don't know if that answers your question but schema building is hard unfortunately all right I know I said this like three times one more question and then and then we're done do you have any tips for switching from let's say arrest to craft QL or would you ever recommend it is it more work more work than it's worth that's a great question I don't have like a perfect answer for it I think there's with any time you have a system that is already built there's like a strong if it ain't broke don't fix the type of thing where it's it's a lot of work to rebuild something from scratch and then you have to like justify that you're gonna have that much marginal benefit after you're done right but on the flip side there are situations where it's like this is so bad it just doesn't fit so strongly that we want to rebuild it there's a really interesting video I cannot remember the name but if you google it or search it on YouTube there's a really interesting video where someone did a talk about how to you have let's say you have an existing REST API or any type of API and you want to put graph QL on top of it you could do you remember what the name of that video was it was it's like if you just search for like our graph QL on top of rest talk you'll find it and Eric Bayer did this talk well I should know that the cool thing there is that you could actually kind of think of it as another layer so you could say that maybe you have like your experimental layer and all all your thin like graph QL layer does is really just call your old API but then over time you could start moving people to your new one so that instead of having to rebuild it all at once you start you kind of do it incrementally which I thought was a really cool idea I'd really recommend that talk if you are interested in that all right that is actually all the time I have so stick around if you want to see the next talk it's going to be really cool it's going to be on JavaScript so we have like a five minute break go get some coffee water all that good stuff and then if you want to learn about JavaScript and what's happening on the cutting edge of JavaScript coming right back here in like five minutes thanks a lot

Channel: OktaDev

Views: 63,722

Rating: 4.9467955 out of 5

Keywords: rest, rpc, graphql, nate barbettini, api architecture, api design

Id: IvsANO0qZEg

Length: 45min 41sec (2741 seconds)

Published: Fri Mar 09 2018