SBTB 2014, Tony Tam: Fastest to mobile with Scalatra and Swagger
Recording: SBTB 2014, Tony Tam: Fastest to mobile with Scalatra and Swagger
all right good afternoon we did lose some people from the walk so um hopefully they're okay uh Lexi what did you do to them okay all right my name's Tony I'm the CEO of Reverb don't worry I still write software um and Reverb super quick I know there's a lightning talk Reaver builds a platform a system for understanding content we apply it for users we understand very well what people are interested in and in the process of building this um platform which has taken 5 years of time and Venture money um we ran into a challenge of connecting computers right so this whole idea of how do you get computers to talk to each other really efficiently and really fast so that you can develop faster was something that we had to solve so that's what we created this thing called Swagger so let me give you a very brief background on what it is um the basic Philosophy for what Swagger is is we say that um Serv services are like the new jar so in the sense of uh web services or cloud services if this is news to anyone then you might be in co co Bell programmer or using ant for build system right this is not breakthrough we just say that um services are like the new jars the functionality is in microservices and um you need to connect to them really well and there are other languages than just schala out there there are things like well python Ruby um Objective C there's different things that you might need to connect to so you don't want to just say uh the only way that you can use our system with lots of services is if you use uh the same language the same Frameworks that sort of thing we want to say that everything can be deployed independently and as long as they can speak to each other everyone is happy right another thing is that we say that service documentation typically sucks right so you can say um Java docs do a good job describing an interface uh the r dos for Ruby might be okay but when you talk about Services which were in different languages and documented different ways they almost always suck and if you disagree with that raise your hand okay good I'm in the right place thank you okay so lastly we say that communicating between them is too much work and if you are a Ruby programmer you probably suck at writing go and in order to communicate very well you need you need a contract between your service and your clients right you don't want the the the front-end guide to have to make decisions based on your business Logic on how your backend works you want things to be understandable with a contract that doesn't change and if it does you're a bad person right so the consumers want that um service logic does not belong in the SDK meaning if I if I am consuming your service and you say well if you pass a limit peram you might get an array but if you don't you're going to get one item then you're making me think too hard and I'm a developer and I have no time to do that and so I won't use your service I'll go to some place else so let's make contract let's make it easy to understand and services how you communicate should be Plumbing right we all don't need to be plumbers right so if I can make it so that you can call the services really easily you will have better adoption and everyone's happy right so what Swagger does is it creates this machine readable contract it's discoverable by default which means I can find it on the web you can go find the Swagger documentation for Marvel's API Comics right you can find it for the US government because they're available and once they're available you can do what you want with them including generate clients and that sort of thing so we're going to talk about how you connect a mobile service or mobile application to a scolar based server with scalatra um and you don't need to have external Services you can so if you need an API management system or whatever that's fine but Swagger by default does not require ire that sort of thing right I feel like I just said this same thing it is an interface to your API and it is a contract and when I say bigotry free move the Mouse um what I'm saying is that many people like there is no such thing as a perfectly restful API everyone has a different opinion on how it restful it needs to be and what it looks like you can delete a pet with a get a put a post a delete or a patch right in your API you can argue over what's good and what's not I don't think a get is a good idea for deleting something but you can but Swagger doesn't care it says look you you work that out on your own time let's just describe it so people can use it right no no server in okay this is how it works we produce a piece of Json once you read it you can do different things with it um you can describe an API that you don't even own so um someone wrote one for Facebook Graph API someone wrote one for GitHub you can you can just refer to it and then uh it's a description all right so now we have something that is machine readable um it's everything the server can do and it doesn't care what language or framework you're using and now we can do things like uh document which is uh really important we can do code generation and client generation uh I'm going to jump to here okay okay so let's talk about Swagger and scalatra so scalatra is a amazing lightweight framework for Scala it's a micro microweb framework uh it's written by some very passionate developers um and it's has a what I consider to be the best DSL for um writing Rest apis uh coincidentally it also has first class support for Swagger which makes it incredibly easy to add Swagger to a scalatra based API um and has been tested and proven at scale if we look at what scalatra looks like as a rest API um you can see a very simple example here uh this is a get request for something for an event service a pretend a uh API service that I put together you see at the top here we have the content negotiation which is injected before the request runs um there's simple routing which is rail style syntax and if you can't tell what this is this is a get request against uh an API which takes a path parameter called a vent ID and then there's simple extraction for those parameters right it doesn't get simpler than this there's no routes file there's not a bunch of magic that happens it's it's a a very clean and like I said a very concise API and it's so light that I've I've run for um uh several years now a scalatra API on an embedded um single board computer under 48 Megs of ram right so you can't do that with even a Java API for Jack RS so scalatra is very light and um and simple to use um scalatra also will do the par uh the model or response rendering automatically uses Json for S you can see on the left hand side uh the the request that came in it's doing a fine by ID uh it's returning a single model it's going to render it using Jackson under the hood uh into Json and in the on the right hand side we're see we're calling a uh find all which is a going to return an array adding Swagger to scalatra is simple you can see the top the top block shows what the code looks like before there's a Swagger support and the bottom shows what it looks like with a little decoration for adding parameter descriptions and um uh some some other um summary information once that's added the generation of the Swagger uh Json is automatic it looks something like this it's very simple notice the type extraction from a long value to an integer format in 64 which is Json schema is no ugly Java annotations in this process so this is what our framework actually looks like in Java um there's circled in red all kinds of ugly stuff and for and scalatra will extract the models so that means that from the case classes here we're going to not only understand that things are options which means that optional in the response model you can see on the right hand side whether they're required or not but notice that the type information here start date which is a date time it's formatted properly so Json uh for us takes care of all of that and now we have a Swagger UI for free which basically means that anyone can try out your API including your boss or if you're the boss then your wife can try out your API right so now I know I have to go fast because I got the hand from Jason back there um if you don't know how to write Objective C you can still help out your clients your internal or external by using a code generator so the code generator is going to read the specification apply some templates and their mustache templates um it will do type safe conversion between the specification into Objective C for example right templates you can tweak which is important we've all seen the world of wisle and waddle and that sort of thing making these awful client Generations these are mustache templates you can do whatever you want with them for example here I you can see the the mustache um syntax in there and what we say is it's like Burger King you can have it your way make your own templates make them however you want make them for go and and everyone will be happy um once you have those you can share your libraries easily everyone has seen something like this boss wants this crap tonight I need an SDK it swaggers so what it's already done there are other mobile Frameworks Believe It or Not other than uh Objective C and iOS there's Android for some of us um same thing generate a client use a template that is made for Android and as you can see it is very simple very familiar call to make uh a request here I'm calling my API and I'm going to get some articles um with a uh an ID input some people do JavaScript too for mobile JavaScript is very simple with swagger as well it's built at runtime that's what it looks like if you're running inside of node it's the same thing inside of browser and in summary that was very fast but um I would say that scalatra provides the simplest DSL for rest apis in Scala I'll say that um was very lightweight minimal dependencies and once you have um Swagger embedded in it then you will make your applications available to lots of other people for example all of the API providers uh API management providers except for two support Swagger as first class citizens which means if you write something that produces Swagger lots of people can use your services and if people can use your services you can probably make more money questions yes how do I compare spray and and scalatra spring spray spray so uh I think spray is really interesting it's very fast I think that it's very hard to read for myself but I'm also quite old so I know that there's a Swagger support for spray and people love it and and it's very it's actively developed but not by Reverb yes in the blue 2.0 of specification yes so Swagger is coming out with a second version of of the specification uh we've had a 1.0 1.1 1.2 for the last two years we've been on 1.2 2.0 is going to come out in about four weeks is and there's some amazing things that have happened um we have probably 2,000 different developers making Frameworks for for Swagger most of them are moving into 2.0 support and big uh companies such as Microsoft uh AP IBM uh I could go through a long list of companies who are supporting and helping get Swagger into their industry into their applications and making it first class so expect that to be um a couple of the goals were to to um make it more available and simpler to add extensions um we're having um like the strong Loop the nodejs providers um they're implementing 2.0 support as well so we've had a a closed but but very large community of people who have been contributing to the 2.0 spec about four weeks yes uh have you had any experience with using swagger documents to generate uh acceptance tests for apis you know there's a um we have there's a Swagger plugin for soap UI I know soap is a dirty word around here probably but but that's a very good way to to to use uh automatic testing yes so when I think of design by contract I usually think of variance conditions and po conditions is there anything Swagger that capture that kind of yeah so one of the things Swagger doesn't do is is try to describe workflow right so meaning like there's it's it's not a a sequence driven type specification it's it's very much a um request response type specification I don't know if that helps any other questions going once it's all open source Apache 2 and uh hope you enjoy it oh yes uh how would you compare the adoption to API Blueprints and RAM so uh I would say if you go and look at either GitHub stars or if you go Google and look at the results then we're at least 10 times sometimes some people think that there's 100 times more to option and there's there's two there's two points to it one is Swagger does not try to Define your workflow and if and if there's one thing that I'm opinionated about is that I don't know your workflow for your so Swagger is open whether you do design first or code first where uh raml is design first only ap's discussion first only so we're not trying to do that um and I think also because it's been open sourced and we're not trying to own the stack we're not a service provider for a a a Swagger as a service um it's made people like Microsoft comfortable to embed us in their next generation of tools for example so I think that says it anything else all right thank you very much