SBTB 2015: Jason Swartz, Enterprise APIs With Ease Using Scala
Recording: SBTB 2015: Jason Swartz, Enterprise APIs With Ease Using Scala
hi I'm the other guy i'm jason schwartz and are we really supposed to do this only 20 minutes I mean 15 minutes I mean 14 minutes all right let's see what happens this will be crazy all right so this is talk I've given to a number of user groups before it was well I was at Netflix before about building enterprises API is the easy way so i'm jason schwartz i tweet and github at swartz rock and recently wrote a book on scala called learning scala from o'reilly since you're all scala experts in here at escala conference i don't know if you're my target audience but well just in case i recommend the book anyways oops well that probably doesn't so apply so as a netflix and you probably know netflix as this wonderful place to watch when you don't really want to get any work done the area i worked on was with devices specifically and actually building lot of internal tools so we had lots of websites where we'd manage and help our develop help external developers like sony and samsung get netflix running on their blu-ray players and tvs and all the other devices so we built all kinds of internal api's to support these type of sites so you've probably seen something like this before it's not very challenging you have a your API server and maybe a few data stores and a single sign-on and of course you all have legacy devices to work with legacy servers it's not a it's not a new pattern really but even so even if all you're building is a basic app that's supposed to have internal services may be talking to 42 you know a few databases it's not very it's not super challenging but it's important to be productive I think and I think that you can build quickly and you can fail really quickly and deploy everything automatically these days easily if you follow the right steps so there's six steps I'm going to breeze through because of our limited time for me I think when you have your developing api's want to let the frameworks to allow the work for you make it really easy to work with speed I don't know if speed always the most important for an internal API but it should really come integrated with everything you need for us we use Scola Torah it works wait with great with Scala actually it's very integrated as well it supports Scala test for endpoint testing swagger for built-in documentation I think fenêtre is great that phonography nagel khan yesterday a lot of people were talking about it make sure to choose the framework that gets you as far as you can infinite infinite aura and in Schelotto here it's very simple to get started you don't have to do a lot of setup the code can be very simple and you want to have some help as well you know if you have if you're going to return status codes use things properly actually say let it take care of the status codes for you let the framework do a lot of the work here you know you don't have to remember hey what's a 401 what's a 403 what's a 200 pick a framework that helps you out so that your code can be as small and readable as possible well yeah you will it's hard to write very simple code you do need to make sure when you have a service that you handle all the cases it's important to make sure that you're doing actual valid checking you check your parameters you have your HTTP codes even though it's an enterprise API you want to make sure that it's correct you wanna make sure that anyone who finds it knows that how it's going to work so that you don't have to do a lot of work explaining and maintaining it you all know about breast api's right so again I'm not saying that you should respect the codes because I tell you to respect the codes it makes things very easy because everyone knows what the codes are it's even easy to remember I like the 401 the best but really if you have an enterprise API this is mostly what you're going to deal with either the input is awesome here's your data or bad request you shouldn't really ever have to have a 500 if you're catching things properly you probably don't even have a 300 because it's an enterprise API if you have a problem with it update your code I couldn't think a better thing to say I know it's a little bit silly but you have the idea of in rest we know what it get does and we know about basic crud get put update post what is post do yeah yeah and then yeah right yeah you got that one the point is that use them because then your API is easy to understand you have to write a lot doc you don't have to explain it to people if you follow the standards your rest api is anyone who calls it can pretty much figure out how things work similar way for how you do the endpoints i mix i mix information here in actions which isn't always the best but i have the idea of a noun i have announced bus a specific ID make sure that people can figure figure out even though it's an enterprise api you'll be correct it'll be a lot easier for people to integrate with what you have because you want them to find it you've written this api you want them to get it you want them say hey I like your API this is really helpful to me I'm using it I found your eight behind the net I'm making good use of it I mean the whole point of writing an API is for other people to easily find and use I really get to use dogs like this in slides i find this gets the point across the meaning the the whole thing point is we have lost and just for rest if you use and we let them do the heavy lifting your service will be a lot more obvious to everyone who wants to use it this is a pretty minor point i find if you have a lot of sequel in your service code you're probably doing it wrong you folks already know this right keep things separate if you have a service keep that different from your business code if you want keep your business code separate from your persistence code makes a lot easier means you can be very reusable you can test it a lot easier and testing is one of the most important things i think is important when you do your AP is but you know however you structure i'm sure is fine that's just works well for me so with tests you want to find out if you broke something you don't want to find out you won't don't want to have to put up a broken api that bugs other people have your stuff tell you immediately hey I simply got drunk and rewrote my entire service manager injected in and did a git push and force it into master just to see what would happen you know actually make sure that you're really testing these things what I like to do is to make sure that I have all these interactions comfort i'm checking the the bottom levels I'm taking the interaction between layers I'm making sure that okay if I have a service it's really calling these correctly I'm doing browser testing I'm making sure Wow even if I do this from a browser oh I forgot about korres i forgot about cross-domain after remember to set all these and maybe figure out that your services return the right thing two browsers it's not really hard to do if you test all the different levels and you test them all together and you automate the heck out of this thing you'll really know where you are at ain't time pretty obvious right all right I think it's important to have simple tests you want to keep it readable no one likes to maintain these things but verify that you're doing the right thing make sure you have a very simple test you can test your happy path you're testing in errant conditions properly you have the right code this is three tests in a row if you have a good testing framework like this which is the Scala test integration with Scola Torah you can make it very easy to get your tests out there the big thing I find when you have your tests make sure they block deployment a lot of people like to deploy things easily and quickly I like that to make sure a lot of people I talked to write tests and I asked okay so how do you make sure people run them they say well we just deploy the code well so if you run tests and you ignore the output you know there's no point in really having tests this stuff is not really that hard to do you could set it up you get into Jenkins get into teamcity even better pace owen who actually want to bother with this stuff and set up a good deployment system make sure that you can actually build everything you're going to deploy your whether you're building a docker whether you're building a mi make sure you build everything right there locally you can get this all working properly so that you know exactly what's coming and this for me is the biggest thing this is the whole reason for me for writing tests have your system deploy stuff for you only if all your tests pass actually I like to do a little bit better this worked well for me I like to my apologies to all the Eclipse users in the audience I like to push the dev like Jenkins or team city to pick it up run all the tests if it passes it's the only one who has permission to push to the master branch and then it will go ahead and build everything build out the dockers of the am i and deploy that for you point is you have a single test pass no go nothing gets merged to master nothing gets pushed out to the release this makes it super easy for you of course you might say I'm not going to write any tests and that defeats the whole point but if you set this up and you make sure that you have something like Jenkins or Travis or team city run your tests only take care of merging if you pass all the tests and then deploy your stuff automatically you're taking care of you write some good tests you go ahead and push the dev you go watch a netflix TV show for half an hour and if everything worked all your code sitting there running and staging or production whoever got pushed to this is the best way I find to make sure that your tests mean something and to make sure that you can trust that your code is going to do the right thing in production anywho it's important to know what you have in an production I liked using as guarded netflix netflix is working on a new open source tool that i think should be coming out yet but it's nice to see what you have you should have an idea of what you're running and you should segment things by your build so that you know exactly what you have I hate this animation I'm just going to go past this sorry anyways there's a lot of tools since I wrote this I I was talking about this last fall I didn't even talk about docker at all in talkers everywhere now dockers great make sure you have a good build have your team city or jenkins do a private push up to your docker hub you know after you've run all the tests after you've merged everything pull the same thing down on your server your set just make sure that whatever you're after you run all your tests if everything passes let teamcity let Jenkins take care of merging for you and then running the talker and then pushing it you don't have to once you commit once you do a git push you shouldn't have to do anything else the tools should do all the rest of the work for you all right we're in the gauntlet folks to folks two minutes left is this still exciting yeah even though it says docks you guys are great yeah who likes writing docks all right my man so the big thing with docs I find is like this wonderful joke of this guy's crawling around underneath the streetlight and officer comes up says what are you doing down there buddy he's like I lost my car keys so the officer gets down he's looking all around for the car keys officer says after like five minutes sorry but I don't see your car keys are you sure you left them here and the guy says well no I dropped them a block that way the officer says well what are we searching here for the guys that all the lights much better here so it's relevant if you don't document the Year api's that you have ain't no one ever going to use them no one's going to find them if you have Enterprise api's if you don't document what they do if you don't document how to find them how to use them then you've kind of wasted because no one's going to use them I don't I didn't do any research ahead of time so I'm going to say that 63 and a half percent of all API is written internally are never called because I just made that up point being if you don't make it easy for other people to find and use your api's and read about them they're not going to be used so to that point I think you should find something that will document your AP is don't write a lot of texts do something that documents the input the actions the routes something that documents all the parameters you know make it easy for you in swagger you have and you have this built into Schelotto you could say hey here's my operation hey here's the items that I take in the query the password the name you're great you go ahead and run this you deploy out to your server you have a special access to the docs it actually builds this in all you built it builds in the username and the query or the JSON string converts your case class into equivalent Jason and then shows the Jason here it lets you try it out it becomes a little dashboard for your API apps I know they have plugins for this and Java and Scala and Python and Ruby and node and I think go at this time as well so no matter what you're running makes you make sure it's easy for people to find this stuff because it's far more likely that they're going to use it if they can figure it out anyways as with everything there's great documentation tools like swagger and other ways to automatically document your API so let them do the heavy lifting all right that was six things in way too short of a time the core point is that we have some great tools you can have put out very high quality api's internally externally you can put out web applications you can get a lot of quality work done if you really set things up right learn the tools and let them do all the work for you anyways that's kind of the summary of everything so go and write api's with these folks I'm Jason and thanks for having me here all right