Delight Driven Development of APIs with RAML

brought to you by mule soft provider the industry-leading any point platform for api’s all right good morning everyone my name is Laurie Surrey and I am a rama work group member I’m also CTO at a company called mule soft and one of the companies behind Ram old is actually a whole rama work group that’s set up to guide the development of rama and what i want to talk to you about today is what I call delight driven development so you’ve heard of test-driven development and so on this is really about developing api’s with the delight of the end consumer of the api’s in mind and that was one of the prime motivations why we developed ramble and so that’s my subject today you guys want to tweak all the appropriate twitter handles are up there I’ve been interested in Web API is for a while out of a very basic primal characteristic that I probably shared with a bunch of you I’m pretty lazy I want to always get to see how much I can get away with doing as little work as possible I guess that’s why we’re all in software because and the more you can leverage the more powerful you feel so I really loved web api is in general I’ve loved them for many many years but for many years there was nothing to actually do web api is against there was Google Maps and Google Maps and more Google Maps and people did all sorts of mashups around the home apps where they would do scraping of web pages in order to kind of have for for creatively lazy developers I guess is how I’d like to call it and now there’s a lot of work to actually go and build upon so borrowing this famous slide for programmable web there are thousands and thousands of open API is out there and if you work inside of enterprises there are probably thousands of thousands of API is inside your own enterprise whether or not to actually know about them is something else and if you look across all enterprises there’s probably millions of API is out there so there’s lots of stuff to go and build upon another question is how do you actually leverage all of that kind of stuff ok so the other interesting thing is not just the number of API but the breadth of these API so you can pretty much do anything you can imagine through an API somewhere right regardless of your domain regardless of how nichy the thing is or how broad it is there’s probably multiple providers which provides you the kind of competition that you’d like this to see out there and that’s led to a very broad and rich set of capabilities not just for for sass in general but for anything that actually has explicit api’s all right so with all of that good stuff in place we’ve got one other thing that I think is really powering this excitement around api s– and that is business right so just the technical way of you achieving something in a in business context or in a personal context and now things have actually changed to where api’s are actually seen as business drivers themselves and that’s actually a huge change it’s funding a lot of this stuff it’s funding a lot of development and it’s finding a lot of companies and startups and so on so why is it taking front stage in business well what’s starting to happen is that if you look at big initiatives that are inside of business they themselves are powered by api’s mobile is huge there’s a tremendous amount of spend on mobile initiatives right whether it’s business to consumer or business-to-business business to partner a lot of stuff is being driven by mobile and mobile requires api’s to be there for many customers it’s also a new channel of revenues one of our customers for example at mule soft is New Zealand Post and like most kind of postal offices their normal traditional revenue stream is going down but they’ve found ways of Romana Tizen their assets they’re addressing service and billing service and they partner with banks and so on to create new revenue channels just based on their core capabilities and api’s are driving all of that kind of stuff and the other is innovation there are a lot of places that a lot of companies that have realized that if you open up your API is either internally or externally you’re gonna get a lot of people building or finding uses for these capabilities that you didn’t think of yourself and they’re starting to be more comfortable with that and they’re starting to discover that there’s new uses for the stuff that they’ve done themselves so rather than building the third instance of exactly the same API why don’t you let one group build the API is and everybody else actually leverage those things so those are some of the big things that are powering it the other is that now these are tied to business objectives so somebody may be in a marketing group actually says if

this API works my business objectives for the year maybe my P&L is actually going to be successful and that means that there’s somebody actually worried to making sure that these things actually are successful they’re not just done by some back-end IT group but they’re actually launched in some particular way okay because there’s usually a budget for this thing and because it’s owned that business person or that business owner is going to make sure that this stuff is funded but it’s on a well-defined schedule that there’s developers behind it that it gets tested it gets rolled out to production in some way maybe with documentation and so on so again that drives up the quality and the timeliness of a lot of these API initiatives and finally people are – actually regard api’s as products if you look at box comm over the last year they’ve gone from a primarily web-based business to a primarily API based business where now they’re saying you know our API is are likely to drive as much of our business as our web-based products are if you look at Salesforce for a long time they’ve actually had more most of their revenue actually come through their API s rather than directly through their UI so that’s pretty powerful stuff people are looking at api’s as products that need to be packaged and delivered and document it and they have product managers and so on that’s a huge change for api’s over the last few years alright so with all that in mind there’s pretty much two flavors of api’s out there one is practically restful api s– and the other is is soap api so soap is still very prevalent out there I don’t know maybe it’s about half of enterprise api’s are still on soap but regardless of that it is still seen or it is now being seen as as pretty much yesterday’s technology I don’t see a lot of innovation I look don’t see a lot of people getting excited about creating new soap based api’s for public api’s for mobile api’s and certainly for most new api’s rest seems to be the direction that pretty much everybody’s taken inside of enterprises and certainly outside of enterprises now there’s still areas where where soap based api’s are doing well b2b is a primary example where there’s a lot of complexity that’s seen as necessary inside those ecosystems but largely everyone else is looking very much at rest and the interesting thing about rest is that even though it’s actually simpler it’s less familiar to a lot of enterprises so you know many of us who are selling into the enterprise space have felt the need to help out enterprises discover that the beauty and the simplicity that a lot of us have seen in rest for many years now okay so with that in mind I’m gonna obviously concentrate here on practically restful api and explain what what I mean by practical in a moment so first little primer on rest probably most of you know this song I’ll go through this pretty quickly one of the things that that these api’s are characterized by is when you’re modeling your domain it’s the set of nouns are the resource is the things that you’re going to be dealing with you model as resources and usually they’re described by URI paths so you’ll say slash users or slash groups or you know slash items is going to be the thing that you are dealing with for your particular domain right if it’s an insurance it could be slash policies or whatever but that’s how you’re modeling your domain you start with your nouns and then the verbs are pretty much given to you because the verbs the things that you do on these nouns are characterized by the HTTP methods now the number of methods is completely limited the semantics that you give those methods what does it mean to actually do a post or a put or a catch is something that you get to to put into your model the metadata is usually encoded in HTTP headers some of it can also be in the payload but to a large extent HTTP headers are a well-developed way of encoding metadata right and obviously with practically restful api you’re always talking at the HTTP layer and finally the responses are the HTTP status codes again this stuff has been codified thought through so highly encouraged you’ve just used the status codes that are established for HTTP and then finally the actual representations of the data right and that’s inside of the body of the request sometimes it’s also inside of the query parameters forget requests and using the appropriate media types is important which brings us to the last point here which is hyper medium right so to be restful right there are several pieces to that and the last important piece is to actually use the appropriate hyper media that describes not only the data itself but the relationships between the data now the reality is that today the vast majority of API is out there don’t actually use hyper media they use effectively static content JSON or XML and so even though they called they’re called restful api technically it’s not rest until you actually put hyper media in there but I like the vast majority of our industry will continue to use the term rest even though most of the time we’re not actually dealing with with hyper media and that’s what I mean

practically restful api is usually I’ll just shorten it to restful api so okay so a few Maxim’s about about this space that will kind of set up why I’m interested in design first approaches towards api’s so what you need to actually succeed in API initiatives and again we’ve seen this over and over again with customers so we try to kind of codify this one is the need for speed right especially when you’re driven by business objectives especially when you’re driven by mobile and so on it’s amazing how much enterprises have now actually accepted the the necessity of bringing new things out to the market every few months it’s not every few years anymore sometimes it’s even every few weeks and we actually see that in in remarkably large enterprises so there is this need for speed that’s been that’s been recognized now the other is that developers rule again a huge change ten years ago you know you were just selling to the CIO you were going top down your whole approach approach was that and whatever approach the guy thought that you were supposed to be using well that’s what developers had to use these days it’s just flipped we’re seeing that developers adopt certain technologies and by the time the CIO finds out about it say oh yeah of course that’s the way to go but to a large extent developers have the upper hand in this thing you get to choose the technologies that make sense for you as a developer simplicity is a huge deal right so the pendulum has swung from soap and wisdom all the way over to rest and nothing well we’ll see what that nothing is it’s starting to actually swing back a little bit to put some order into it but to a large extent what people have said is I don’t want all of that complex stuff that there used to be right I want something very straightforward I’m already using HTTP let me just use HTTP that’s the driver for s what other pieces can I add into that that keep that same level of simplicity and then agile development right so the other thing is I don’t want to do big waterfall projects I don’t want to spend two years when my app needs to be out in six months how can I do this in a very agile way and that’s where things actually get interesting with API is because if you’re constantly tweaking your API it’s actually pretty hard to build things on top of that API so how do you reconcile agile development cycles with API first development and we’ll talk about that a little bit here as well those are kind of some interesting imperatives for success now an assumption I’m going to make here and something that we’ve seen born out and that’s driving a lot of the rest stocke is that if you get the core of the API right if you get the API specification or the design of the API correct a lot of success will flow out of that and I’ll tell you in what sense so the first thing is we’ll find a way to actually embody the API source code not the implementation source code but the API itself the interface alright so you’re gonna define at the beginning what is that API actually going to look like what capabilities will it have if you’ve got that source code code nailed down the documentation should be automatically generated for it right because why have to repeat yourself you may have to add some some human things to help humans along but to a large extent from the API spec you should be able to auto generate your documentation and if you can do that and you know exactly what your API is going to look like you should be able to mock it up before you implement it right because you know exactly how it’s going to behave you should be able to create a mock automatically and once you’ve got that then you should be able to create a very useful tool to make requests against that API even before you’ve actually implemented anything and if that’s the case then you should be able to actually work through entire use cases and see how that API will actually be used and tweak that API without implementing everything because you’ve already said how the API will behave and if you’ve got that then you should also be able to automatically generate clients for that API that we’ll know how to hit that API in specific ways for iOS or Android or web your your web clients all automatically and in fact why don’t you also generate the server part out of this thing now you won’t be able to generate the full logic of the implementation humans have to come in at some point but you should be able to at least stub out the pieces that guarantee that you’re implementing that API and after that you should be able to also create tests automatically because again your API is a great testing interface the API is pretty much the perfect testing interface it’s an automated way to access all the functionality what’s in the API should all be accessible what’s not in the API doesn’t exist so it’s the perfect testing surface unlike the user interface for making sure that that all of your application underneath that actually works couple of other things one is lifecycle management becomes a lot easier right because if you know your API spec you can always tell hey do I need to change it or do I not need to change or it has it actually changed and I conversion it as well right so I can compare the speck of the new one from and the old one and I can tell is it backwards compatible or not so there’s a lot of things you can do around API lifecycle and in general product life cycle once you’ve nailed down the API spec itself right it gives you a thing

to actually version and the last aspect is consistency so once you’ve looked at your API as a formal document you can look at it and say look am i giving a consistent development experience across my API to the various pieces of this API actually act consistently right and we’re gonna see that that in large enterprises where you have hundreds or thousands of api’s this is actually a big problem encouraging that consistency all these kinds of things are what drove the development of rama okay so one more thing before we actually dive into ramble itself API first development and I say this because I’m still amazed even in our own company how many misunderstandings there are what it means to do API first development and I’ll just give you an example you know one of the one of the misconceptions was okay API first development but that means I need to go and develop my API fully and then I can build on top of it that’s actually not what API first development means at all it means you start with your API but it doesn’t mean you have to actually implement your API first so I want to just spell this out very explicitly right API first development basically says I’m gonna tell the consumer developers the ones who will consume my API is what it is that they’ll be getting and at that point I will effectively let’s say that you’re building a house I will effectively tell you how the top part and the bottom part of the house are actually going to meet the infrastructure for the house and the actual say in this mobile application in this case the top part of the house are actually going to meet so I’ll define the interface between them now once I’ve defined that the guys who are building the infrastructure can go and start implementing the bottom part of the house the part that the house will actually live on and in parallel with that the guys who are building the top part of the house can start implementing that and they know that at the end the two pieces will actually fit because I’ve defined my interface first that’s what API first development means right start with the interface make sure that’s really going to work for you and then build on both sides of it okay the steps are as follows right first what are you trying to achieve this is actually really important why are you even building an API what’s the purpose of this thing right think through that quite a bit and then you need to design now when I say design and validate you know some people are thinking well this takes months I have to go through know this can take hours right this can take a few days but there does need to be some aspect of design to make sure that it’s actually going to fit your plan and you should be able to validate at that point very very quickly I’ll actually show you a demo without having to implement everything you lock down your spec yes okay this is what I’m going to deliver at least for the next I don’t know month or so this is gonna be my API spec and then both sides can start to implement you need to deploy it somewhere you need to operate engage I won’t concentrate on that in this talk and then you need to lifecycle the thing so look to the next version look to applying the learnings that you’ve had from that okay I’m going to concentrate obviously in the design and validation part in here so the number one imperative to an API success from those various things that we saw before absolutely delight your users and by your users I mean the people who will consume the API because that’s the whole purpose of building this thing so how do you guarantee that this API is actually going to work for its purpose you design for your users first and foremost so understand how they want to be looking at your system now how you’re gonna implement it not all of the crud you have to put behind it to actually make it come to life understand what they need and design it from that backwards I’ve started to call it sort of an app backwards approach right start from that and then work backwards from it model it very cleanly model it consistently so that they have an easy time ramping up on your API iterate very quickly and iterate before you’ve implemented all the API make sure it’s actually gonna work for them I’ll show you how to do that and then you do various things behind the scenes and eventually you’re going to engage them right so you’re going to give them various tools to discover your API to play with your API to validate to access sandboxes all of that other good stuff right so we’re looking for that experience of saying yeah this is the API I’ve been looking for that’s literally the expression that you want to have on your users face all right there is a quick analogy that I want to make that I keep in the back of my mind when we’re going through this user interfaces right the whole discipline of UI has evolved into UX right give me take into account the entire user experience from beginning to end and make sure it all hangs together not just the visual aspect but the whole experience and similarly for API is you can consider something called a px the whole application programming experience how do I validate this stuff how do I actually work through my use cases how do I do that very quickly it’s the same kind of design life cycle for api’s as you have for user interfaces ok with all of that in mind the API spec is at the

middle of it and that’s where we came up with Rama as a way to actually describe those api’s now API spec that I’ll be talking about here is ramble it’s not the only API spec out there it’s just the newest of the major API specs that people use and Laura will have a talk later comparing this with with other specs just a quick intro to the ramble workgroup so it’s a it’s a cross company initiative several vendors several companies that have been thinking API is for for for many years have lent their brains into this thing and will continue to move this thing forward and if you go to rhema.org you can discover lots of stuff that website continues to iterate so a lot of stuff that I’ll be talking about there are leads from there lots and lots of projects on this I’m absolutely amazed by how much the community is just creating projects on this if you go to github search for Amal filter by which ones are the latest because you know five years ago people still had things called ramble but they weren’t this and you’ll see just tens and tens of projects that people are just developing on their own so it’s really cool to see all of it okay the whole goal of Rama was to keep the spirit of rest that simplicity that were at the HTTP level and turn and create a spec that has that same aspect so the the the guiding light that’s going to be in front of the Rama workgroup you know indefinitely is to make sure we never stray from that and we never go back to wisdom and we never go about WS star and create things that are big and hairy and complex even as requirements built so we have to keep asking ourselves are we there yet and there’s a ram l1 dot o initiative going on now we’re trying to nail down the spec for one dot Oh feel free to jump on on github and there’s a bunch of candidates out there for rama 1.0 but whenever we look at these candidates we’re always asking ourselves have we stuck to that fundamental principle that’s what we think is the most important part for adoption so this is literally the way that Rama was conceived if I needed to send an email to someone to describe what my API is I would probably send them something like this here’s a collection of users identified by slash users like do I get I do a post within that collection of users identify an individual user by its user ID and what can I do I can get them I can update them I can delete them that’s the way I’m kind of thinking my spec should be able to describe that same API in exactly the same way and so when you encode this in ramble it looks like this pretty much the same why should it be any different right if we can teach machines to read that we might as well just communicate in this great way and so we’ve adopted the Amal for that right which means that the whitespace is significant and allows you to construct the document it looks exactly like what you would have probably typed to someone else as your spec okay now we can probably lose the descriptions because very quickly you get into into conventions right so guests always do the same thing posts always do the same thing and so on and so having lost descriptions we can now start to fill out other aspects of the API for example the query parameters it’s just called query parameters and you give them a name in this case the name of the query parameter is name because I’m going to actually filter by name and so you go on and you just kind of flesh out your API and you take kind of an iterative approach at least that’s what I always do kind of start from the resources then you add the nouns then you add the the specifics around query parameters and bodies and responses and it starts to flesh out that way and so here’s a little bit of that now Rommel has something else that’s quite interesting about it which is that it allows you to refactor your api’s into reusable pieces right so what you find out is that very quickly after you model out a relatively large API you start to repeat yourself you want to repeat yourself right the whole point is to do it consistently so you have users and groups and and permissions and so on and they all start to feel the same you want to be able to capture those patterns and express your API in terms of those patterns and that’s where we’ve introduced resource types traits and of course schemas so putting schemas aside that’s kind of the the known part I’ll get back to it in a moment you can define something called a resource type right the kind of resource that this is and use that over and over again in this case we’ve defined a resource type called a collection and we can say that slash users is a collection slash groups is a collection slash permissions is a collection and define collection once and then apply it over and over again you can even give these patterns parameters in this case it has a parameter called the schema so it’s a collection of what it’s a collection of things where the schema whose value is user and the other thing is is trait so these are behavior level patterns right this thing behaves like a secured thing or this thing behaves like a page thing or this thing behaves like a tracked thing and you can mix in these traits and again it’s up to you to define what

those traits are but you can apply them over and over again you can say all of my collections are paged in exactly the same way and there’s security schemes in the same way so all of my resources are secured in the same way define at once apply it over and over again okay this basically just goes to show you covers the full HTTP so every part of HTTP the headers and the response and the request and so on are all covered inside of that including examples and I’ll walk through detailed examples here in a moment so I’ll just kind of flash this up for now you can see the the the version if you’d like to actually encode the version inside your URI you can do that some people put it in the header instead query parameters the headers that we talked about the responses you can find different responses for different status codes not just at 200 and you can give examples and schemas as well and of course we support multiple media types okay here are some patterns and our flash goes pretty quickly because again I’ll come back to that in the demo so you’ll see that one one of the important things is to be able to actually externalise these types so in this case I’ve defined a base type that isn’t included here but is actually sitting somewhere else and you can point to it through its URL and say pull that in and the good thing about that not only is it uncluttered your your amyl definition it allows you to publish libraries of these resource types and traits and schemas that you can reuse over and over again so again that encourages people to become consistent not only inside of an API but across various api’s okay the other thing that resource types allow is to inherit things so you can say all my resource types are this way and then this specific resource type is like that but it has some different characteristics to it you can pull in traits this is one of the coolest things so you can define these traits then you can pull the traits into the resource types and just apply the resource types you don’t have to apply the traits again later on and then you can parametrize and we’ve tried again in the spirit of simplicity to keep the number of things that you can do on parameters as simple as possible the only thing you can do right now is singular eyes and plural eyes because that’s just makes things a little bit easier to read so in this case there’s a parameter called schema that you can pass in to this particular resource type and then this PluralEyes is it before it applies it so there’s that very simple syntax okay here are the traits so here’s what a page trait is nothing is built into Ramo it’s up to you to go and define these things or to find a library that has this but in this case it makes sense to define something called paged it has to query parameters a start parameter and the number of pages and it’s defined this simply I’ll show you how this applies in a moment and another trait called searchable which you’re probably only going to apply on gate on get requests where we define that the query ammeter is called cute right and if you’ve looked at lots of api’s they define their own query parameters differently in different places this is a great way to just standardize on one thing when you apply it you can say that the collection of books is both paged and searchable and automatically the ramble parser will combine all that information and give you all that property all those behaviors on the books collection we’ll see that in action in a moment okay so that’s the mixed int as far as actual body schemas go Rama supports out-of-the-box XML schema JSON schema there’s nothing to restrict it if you have your own schema language it just doesn’t have any built-in support for that but you can extend this as much as possible and you can also just kind of use form data right so this there’s nothing to say that you can’t just submit effectively name value pairs through this particular media type and just say you know name is required and email is required and things of that sort alright so very very simple ways if you don’t want to deal with actual schema to still put in validation constraints on your inputs and actually on your outputs as well the convention being that if something is required on an input you actually have to submit it if something is required on the output you can expect to always get it back okay so we’ve clicked through XML schema JSON schema Oh examples really really important this is something that we learned in the development of the ramble spec so we started with you know codification of the schema so you put in their schemas and then kind of realize that what really developers look for is examples right we say yeah yeah the schemas are there show me an example and that’s how I’m going to learn so Rama has built in examples and you’ll see how we make use of those examples when it comes to the mocking service later so make sure you include examples in your schemas in your in your RAM inspection okay let’s actually do stuff right so I’ll get off with PowerPoint and let’s start actual coding all right here is without

further ado a blank rommel spec inside of a tool called API designer that just helps you actually write this so you can use this you can use whatever you want there’s plug-ins for sublime and there’s there’s plug-ins for a variety of editors I like this web-based one because it’s so was available to me and it gives some some hints as well so I’m going to start typing up a Rommel spec for a particular application the application that I’ve chosen to do here a little bit fanciful but we’ve all been hearing about drones right there’s a drone being given away out there we hear drones used in all sorts of ways and there are rumors apparently not just rumors about companies like Amazon starting to make deliveries by drones we shall see but in this case what I want to do is to model an API for a drone delivery company that is trying to challenge Amazon by naming itself after the second largest river in the world Congo and creating a delivery service where you can just order things online and they will just be dropped into your backyard at a particular time well let’s see how I would actually lay out the API for such a company what I’m gonna do here is start by giving it a title that’s a pretty good beginning and what will happen here is as I type in the rommel spec there’s an API console on the right that’s just responding to my keystrokes and starting to build out the live API console if you like the documentation for that spec as I type it up okay now the first thing that I told you I do when I design API spec is I start to lay out what are the resources what are the nouns and the first attempt that I had at this was okay I’m going to give you a full API on the actual drums I’m gonna tell you how to actually control drums you can be sure that that’s not how a successful drone delivery company will start because what they’d like to do is you should be scheduling the deliveries you should be creating deliveries and let the company deal with how to actually schedule the drones you know picking them up and dropping it off right so again it’s more about starting from the end-user experience and working backwards so the API that I’ll define is actually an API for deliveries and then there’ll be an API for drones that comes on top of that and says okay you schedule this delivery please expect this drone to appear in your back yard on this at such-and-such a time okay so to do this I’m gonna start by saying I’m gonna have a collection of deliveries so here I’ve defined a collection of deliveries or at least the resource called deliveries and I can identify an individual to by its delivery ID right and now I’ve got two of the big nouns and given deliveries now I can ask about the various drones so I’m gonna go back here and define a collection of drones and inside of that collection I can address an individual drone by its drone ID and for a given drone I can ask it about the deliveries that it’s scheduled to make so I can ask it for its list of deliveries now I don’t actually want to copy/paste whatever I have above so instead what I’ll do is I’ll use a llamo anchor and define this thing as deliveries and then here I’ll just point to it okay that’s my API spec at this point right so pretty simple just a few lines here you can see that the console is starting to flush out pretty nicely it’s actually telling me the full list of resources that I’m able to to address through this thing okay and usually that’s kind of the iterative way I start with the nouns start to flesh them out so if I flesh them out a little bit more they start to look like this now with the verbs so let me let me show you how the verbs work right so the verbs is something that the UI can actually predict right so the way that this is gonna work is I’m gonna go on deliveries and I’m asked myself what can I do with a collection of deliveries right so the first thing I should be able to do is get that one right and so as I start to type in the UI is helping me to actually complete the get what else should I be able to do with a collection of deliveries I should be able to add something to it usually do that through a post so here it is with a post and I have two colons there now what can I do with an individual delivery I should be able to again read it fetch it get it I should be able to update it now if you do partial updates the right method to use is actually patch relatively new method that was added to HTTP and I should be able to delete the deleted livery basically cancel it and the us kind of helping me to complete this if you if you’d like even more help there’s a handy-dandy thing at the bottom of this which you can see here a little

shelf that actually tells you at any given point this is contextual you can add this and you can add that but having done this for about a year now I don’t need that shelf anymore so as I flush out the the methods here you can see that the console is starting to reflect those now I haven’t added query parameters I have intended examples you can see that the spec is starting to build out and when I do flush them all out it starts to look more like that right and now it really tells me the surface area of my API right here are the resources and here are the methods I can actually apply to those things okay what’s the next thing to do is probably some query parameters right I don’t want to get literally all of the deliveries I want to get some of the deliveries so I want to filter them out so on this get I should be able to add some query parameters as I type in quue tells me the rest the query parameters I can delete I can add that and so on right and let me again just for the sake of time show you some of those things already fleshed out so here’s more of the query parameters I’ve added for the get as State and a through date so I’d like all of my deliveries that are within a certain boundary of time very simple to go in and create that kind of stuff you notice that it supports a type the date can also have number string you can have enumerations and things of that sort very simple to create these things and I like to put in examples as well query parameters for the collection of drones well I’d like to see all my drones around my area so I can build a mobile app to tell me all the drones that are actually nearby or is this particular drone actually nearby and so on so here’s some query parameters that have added to that and again if I had time here and I typed this all out you can see it all appearing in the console I’ll show you more about the console in just a moment okay actually you know what let me let me show you a little bit more about the console right now so you can open this up and you can see that all the stuff that’s here in the spec is starting to appear in your documentation and you can start to preview that when you show this to your developers the documentation will just be the bigger version of this so at any given time you can see the end-user experience in both the requests and the responses right now I haven’t actually defined their responses here let me go and flesh that out a little bit so to do that I’ve added now a few specific responses so here’s the responses keyword right what would I expect is the responses to getting a collection of deliveries well one of the responses is going to be a 200 HTTP status and inside that 200 I’m gonna have a body and inside that body I’ll give you an example and here’s the example of this thing it’s going to be JSON in this case because that’s how we define our media type and so I can just flesh out the example right and you just type all of this stuff in it’s validated for you and here’s your example for the correction of of deliveries and similarly I can flesh out all the rest of these examples here so here’s a full list of examples right you just kind of work them out in a way that you think that your your payloads will be haven’t implemented anything I’m just kind of specking out what the API should be like and at this point I can go back here and I can say okay let’s say that I want to say I don’t know update some information about a drone alright now this one actually has an example I guess I’ve gone a little bit too far forward because I wanted to actually show you something that’s pretty cool on these guys and that is the mocking service okay so I’ve fleshed out a bunch of these examples the idea is this that as I’ve typed out the the API spec right I should be able to just go ahead and create a mocking service automatically for for it because I’ve given all already all the information about this API to the service and so all you need to do in order to actually start mocking it is you just click a button it sends the API spec to the back end and gives you an actual instance of a mocking service that acts exactly like this API but no matter what you send it it’ll come back with the example response which is actually good enough for implementing a lot of applications and again I haven’t had to actually implement anything on the back end in order to get this done yeah so there’s a there’s a back-end service that we’ve created you can create your own service or some open source packages out there and literally what it does is it takes the the ramen spec and it says okay this is how you want it to behave let me create an actual endpoint instance for you with a gooood on it and just start to pair it all of their responses and it actually does validation as well so if you submit incorrect parameters to it something that’s outside of your schema it’ll come back with error codes as well so the more information you give the API the more faithful is that mocking

service to that API now I can actually start to issue requests here so for example I can start to let’s say get the list of deliveries right so I can try it here I could in enter some parameters I haven’t put any authentication and when I issue a get request sure enough it comes back with all this information so I’ve actually made an API request an API that doesn’t exist yet or at least outside of mocked form right I can even try to create an application let me try it here I’m gonna pre fill this with an example you can do whatever you want and then submit the post and you get a 201 created and you see the body comes back and to show you that this is real I’m going to attempt to get demo gods here by actually issuing a curl request against this don’t have time to type all of that but here’s the curl request against that same mocked service that we saw before I hit you issue the HTTP request and it comes back with that data so you can give this endpoint to your mobile developer you can publish that inside of an API portal and have them start building their mobile app without doing anything behind the scenes and that’s kind of that design first approach you can do both of them and if you attach a schema then there’ll be validation server-side for that isn’t of course you can do client-side validation as well which is why you’ll see in some of these things that there will be some client-side validation I’ll give you an example of that let’s say that I I go here and I try to delete a particular drone let’s say that that was a reasonable thing to do probably isn’t from an API design perspective if I try to actually issue a delete it will tell me you know you actually need to have one of these because there’s actually a validation attached to that right so once I do this it will say okay you wanted to delete that no problem here’s a two or four response for you so you’re literally modeling this thing okay now I want to show you one other thing which is the refactoring of these api’s right so I’ve got an API here that’s you know nice and and full it’s got a lot of pieces to it but it’s getting to be a little bit longer so I want to be able to refactor this and collapse it down into something that’s much more efficient and to do that I’m going to define some traits and resource types okay and I’m running short on time so I’m going to start flying even faster here are some let’s see some traits that I’ve defined so here’s the paged traits that I’ve defined before right the query parameters that we saw before here’s another trait that folks in enterprise would love who is actually using my API I’d like them to actually submit an accounting code on all these things so I can start tracking to which internal payment account should actually charge your API usage so I can encode that in this way and then I’ve gone to define some resource types so I’m gonna use inheritance right I’m gonna say that all resources should be accountable and then I’m going to define a collection a collection for me is going to inherit from base resource and only has it get in a post right I don’t need anything else in my collections the get requests for any kind of resource are going to have a description get a list of and then whatever the resource path name is I’m gonna say that all my collections are paged and I’m going to say that the response of a get is it 200 and has a body and that body has a schema and an example that are always driven by convention over configuration so the convention here is you must name your schema according to your resources path and you must name your example according to a parameter that you pass in called example collection ok the post is going to be a similar kind of thing it’s going to require a body and it’s going to have a response it’s a 201 with the location header and a body and so on and so forth and you can just flush this stuff out and put it in some library for your entire company or entire department to go and use over and over again alright with that in mind you can start to refactor your API and all you need to do is to give it a type of collection and you see immediately that it has all of these behaviors of the collection right so it has a post the post has a request in response to request the response comes back with a 201 and location and so on but I didn’t have to type that in my API I could just refer to that collection that I had before because I’ve included those collections in here so my API becomes a lot simpler if I actually flush out these examples here’s what they look like right it’s the same example that I had before except now that’s the only part of the API that actually to pass it everything else is actually inherited this is the part that’s

different so API becomes the generic API plus the differences that apply in this case the example is specific the query parameters are specific against some specific examples and if I look at this thing it just collapse the examples down so you can see it all together so I should ask I should add I did one more thing without talking about it I also defined schemas so I went back by the way most API is out there don’t bother to define the schemas but it’s really important that you do so you understand the sort of the validation and the range of your parameters so I’ve gone ahead and defined some schemas here these are the schemas they’re not particularly interesting and JSON schema in general are a little bit of a pain to write and most people don’t know how to write them properly because they are a pain and we’re working in some tools to make it a little bit easier to write json schema so with that in mind this is what your api ends up looking like it’s actually pretty simple it ends down here so the entire api that we saw before is what 129 lines are so including all of the examples and that gives you this fully fleshed out api that’s kind of fully functioned in fact i’ll show you how fully functional it is in a moment so that’s the power of being able to do this I don’t know that they look quite like hypermedia they do give behavioral aspects to this thing and but they don’t really give you the full semantics that hypermedia would give you so exactly exactly so if you wanted to invest and kind of take it to the next step then hypermedia is definitely a great way to go hypermedia has has its own issues if you like with with describing some of this stuff because even that level of consistency often you need you need a different way to actually model the the hypermedia itself the actual media type and you’d want to actually reuse things in that as well so you’d need something like traits in order to define the bodies right now we’re using the traits too not so much find the the payloads themselves but rather attributes like the query parameters and and response and status codes and things of that sort so it’s it’s going after a different place in HTTP if you like but and we can talk more about hypermedia as we invest more in hypermedia there may be trait like and type like capabilities actually type like definitely that can be applied to hyper media as well okay so I want in there what minute-and-a-half that I have left here I want to just show you some a couple of things really quickly one is I’ve defined exact with exactly the same resource types and traits also an ordering API and the reason I did that is I want to work out a full-on use case of this API that we had so the full-on use case is is going to be to actually use this thing to actually make some orders and place some deliveries right I’m not gonna have drones flying around because I haven’t implemented that API but I will show you how valid eight that this use case actually works and the way that I do that is with something called API notebook so if you go to API notebook comm it’ll redirect you to this funny URL but it’s actually all sitting on API notebook comm API notebook is a way inside your browser to model out entire use cases of your API just by typing in a few lines and the way that this is done is is as follows I’m gonna create a notebook and I’m going to create that notebook and just point it to the ramble description of this API that I have so to get the ramble description it’s or there Rama location I’m gonna just copy this address I’m going to create a new API notebook it’s writing inside my browser and inside of this I’m going to type one line I’m going to ask it to create a client called deliveries API and just give it the location of the Ramo file okay that just gave me a full-on SDK for this API because if I type this it knows my full API as a JavaScript client and there’s stuff being created now for Python and for other things but in this case javascript is the right thing because I’m running it inside my browser and I can ask for the list of deliveries it knows that there’s a get on those and if I issue a get it actually makes the get request and comes back with a body and headers if I look inside the body I see three objects if I look at the objects here are my examples so I can now script out full use cases of this API and match them up with other api’s right there in my browser and work out the use case now in this case here’s a fully worked out use case I’m gonna just refresh this thing because I won’t have time to actually type all of this stuff

what we can see is I create a client for the delivery’s API right here and then I create a client for an order’s API the other one that I showed you here it is the same kind of thing I can get a list of orders and now I’m gonna start walking through this use case so first I’m gonna actually place an order okay I don’t have time to go through all of this thing but you’ll have access to this later I’m just gonna fake an order item and I’ve placed this and here it is here’s a particular order that I’ve just done I haven’t actually implemented anything but I have enough of the mock to actually start walking through this use case I should be able to retrieve its order items I take one of these order items and I scheduled it for delivery just arbitrarily pick the first one and scheduling it for a delivery means I post it to the deliveries API that we developed before this so there goes post it to this thing and again the the API notebook because it knows these api’s will help me actually autocomplete all of these things and show me the results of these and at the end I should be able because I’ve got the full API here to tell the user exactly what to expect right so I’ve created this message expect this drone called Camelot to the liver this particular item the propeller assembly on this particular date right just walking through the API and letting the API notebook do the heavy lifting okay last thing I want to do is just to show you this is all live I’m going to tweet that result so to do that I’m going to create an SDK also for Twitter because there’s a ramen spec for it it’s really easy to do it’ll ask me to authenticate so óthe authentication is built into API notebook I’ll say go ahead and do that and that point I’ll use the Twitter API statuses update JSON post and it tells me sure enough I’ve posted it and let me go over to my Twitter feed and refresh that and see that it’s actually posted on Twitter so what I’ve done is I’ve pulled in from my fake API deliveries one and the drone ones and send it to the real Twitter API and and it all works so now I can publish and share that notebook and tell people this is how you’re actually supposed to use my API alright and with that I’m completely out of time thanks to you by meal soft provider the industry-leading any point platform for api’s you