eSign Pet Adoption Contract Made Easy

Esign pet adoption contract

my name is John skinny and I worked for epon technologies out of the Richmond USA office and today I'm going to talk about API documentation languages and contract first design so I'll go over what documentation languages are and why you'd want to use them we'll do a demo of one of them and then we'll do talk a little bit about contract first design where we refactor the demo with contract first design in mind and then I'll go over a list of some of the cool tools that I have found so to set up the context here's an example of an API that we might need to document we have a product resource so here defining the location of the collection of products we support HTTP methods get in post to get all the products and add a new product to the collection and we have a URL parameter ID to get a product by ID so that is an example of an API that we might want to document there are several ways to document your API API documentation languages is one of them so what an API documentation language is is it defines a specification so specifications are machine readable the cool thing about that is that parcels and tools that understand your specification in which your documentation is written in can parse your API documentation and give you some cool features now go over examples in there so the specifications the best specifications there's a number of them out there are open source and then that enables third-party developers to build on top build parsers and build tools to give you that the added value so some of the examples of the tools that are out there our interactive documentation cogeneration postman collections mock servers traffic it does there's a long list here so and and there's more so when I first started looking into API documentation languages I started to realize that there's two ways to go about using them the first way is where you write your documentation language first and you use your documentation to generate your server-side code or your implementation this approach is called the top-down or contract first approach the other approach is when you write your code first or maybe you have your code already written at this point and you need to have documentation well there's tools out there where you add a few annotations in that then you hit a button and they will automatically generate documentation that follow a specification and once you have that documentation you can apply a number of other tools and parsers to that so there's three kind of major languages out there that's I kind of noticed that in the open source community swagger ramble an API blueprint Swire is the oldest and it did a really good job at the code first approach within the last year or so there's been more of a trend for contract first or or having more value on making sure your contract is right before you write any server-side code so ramble and ABI pluie print address this need and they design their specification from scratch with that in mind and if you go down to the format's you'll notice that rambling about blueprint use human readable and writeable formats swagger the bait the cord swagger is written in JSON and but there's Apogee wrote a editor on top of swagger that's written in yam oh so that's why I happy with yam will comment there and that's what swagger 2.0 which has come out to address some of the things that Ram won't API blueprint have done well so community support here is is really where the value comes comes from and swagger has been out the longest and it has a really powerful lead on the number of tools a number of parsers and generators that are out there this number here at the bottom is the number of stars on their most favorite github post or app github repository but if you look at things like Stack Overflow questions you'll find similar numbers or similar ratios so too kind of place to constraint here I'm only interested in documenting rest API is right now all three of these support the core of rest and the core of HTTP authentication all three support major security flows file inclusions are really useful for organizing your large API for a writer for someone riding the API so ramble does a really good job at that swagger kind of supports it but it's not the main use case it's not very well supported sample representations is very interesting because not only does it help with the documentation for people to help understand here's an example of something that you could pass or something an example of something that you might receive in a response it also helps because it provides input for mock servers so basically you can click a button and start a mock server based on a ram or api blueprint documentation and then it will return sample response sample representations as the body of the responses and this is without even having any server-side code written this is the the number of the language integration swagger has a very good support for both server-side and client-side so now I'm going to go into the demo for the demo I'm going to use Ram ole to document this a pet store API we're in the support getting all the paths adding a new pet to the pet store getting a pep ID we're also going to look at how to solve paging and security so a cool thing about ramble is that it has this it has this little tool box that tells me what I can do first I need to specify a title and then at the at the root context these are all the things that I can do so I can do a base URI and immersion I can also define protocols and then that's all I want to do for now I can do a couple of things like to find external documentation but I'm gonna go ahead and add a new resource and our new resource is going to be pets displayname pets and now that the context has changed it's giving me a bunch of other options for defining HTTP methods so I'm going to do a get and the descriptions support markdown so I can do some markdown get all pets and then I'm going to find a response it's going to be a 200 with a body application JSON an example here and this is going to return an array pets so our pet object is going to have two properties and named them 90 so now that I'll I'll shift tab all the way back here to get back to my methods I'm going to define posts so we can add a new pets to the collection and I'm gonna define a body for this which is gonna take application JSON and we define a schema here and I externally define this schema already and you can see here's the file file support with Rama and so here's my schema it's define a JSON schema they also have support for XS d so here I have two properties and with a name and an ID both required so I'm just gonna go ahead and pull that in e to my oops into my API pet store tack that schema and okay so for this I'm going to define a response 200 response with a body that's gonna be application JSON with an example that's going to be a simple JSON object that just returns a message that says your pet has been added all right so I list all the pets and I add a new pet to the collection so now I'm going to define a sub resource for the URL parameter and I'm just going to put an ID here a variable pets by ID will do it get with the responses will be 200 with the body and application JSON hello example example will be your I don't know it's gonna return a pet and we're also going to find a 404 here because we could be passing an idea for a pet that doesn't exist so application JSON with an example and we're going to do SH the assume simple message or patent I found okay there's my get pet by D expand that so one thing I wanted to find for my get is is paging so to do paging we're gonna implement two career parameters an offset and a limit and this will control the the size of the payload that comes back okay so our pet store is really huge and we have a lot of pets so we'll define some query parameters here we'll have a limit and an offset and then for each of these will define defaults required field an example and a type and the default for limit zero doesn't make sense let's change that okay so there's our paging we support it with query parameters to query parameters limit and offset and with those we showed up you should have a good paging support so before I go into defining security I want to take a look at what our specification has generated so far in the preview mode so before we weren't so far zoomed in for the purpose of this demonstration you could use the editor in the preview embedded side-by-side and this screen would update in real time so we have our pets collection resource here and we were pets by ID two methods post and get so opposed for example we have a request add a pet to the collection our body a response 200 with the example that we provided and a content type so one of the cool things about ramble is that you can hook up a mock server within the editor itself so by default if you don't turn on the mocking service it will if you have a server deployed at the endpoint that you specify you can it will actually send HT requests and you can interact with your server but if you might not have a server implementation especially if you're doing contract first design so we turn on this mocking service and mule socks will deploy mock service in their cloud that this is a public URL anyone can access it right now and that acts for a serving point for my API so now I can do this try it and I can pass in a new pet that I want to create and so I add the schema defined and I need to have the name of the ID so the mock servers smart enough to return 400 your ID is not required or your ID is required so we'll go ahead and fix that and add an ID post now that we have our schemas we conform to our schema we get a 200 response with your pet has been added which is the example that we defined in our documentation so a little history about these API documentation languages that I picked out swagger is the oldest of the three and came out 2011 and it addressed the problem of a code first approach and automatically generating your documentation from annotations that you put in your code but within the last year or so there's been more of a push for contract first design and ramble an API blueprint have been created to address that need ramble has quoted here to talk about swagger as was best suited for documenting an existing API not for designing an API from scratch swagger 2.0 it has addressed some of the problems that it has faced and it came out recently in September 2014 to address some of its deficiency in a contract first design approach so why contract first design the contract first design came about because we realized that our API as and our contracts are valuable our API is enabled internal developers and third-party developers to do good things with the data that we expose and a clean API and a well-thought-of contract that is designed per the consumer use cases will result in cleaner code and higher adoption rates which ultimately drives value back to our service so here's an example of where we didn't think about the contract before we expose our API to our consumer here we have an application and with any application there's a complicated data model and wonky business logic that acts on that data and we decide we're going draw a line and expose an API and we're going to expose those things to the consumers obviously this is not the optimal approach we don't consider the needs of the consumers in this case and we expose to them the complicated models in the unfriendly business logic that we shouldn't have to expose to them directly also consumers might have a different view of the world than what's defined by our data so here's a better approach introduce a facade or protection layer between your application and the consumers and the facade will hide the complexity of your application and it will basically want to define the user facing API - something that the users want to use and then you adapt that to talk to your application and the API is going to have simple models and consistent interfaces that are great to use for the consumers so one great way of building a contract first design is to get feedback from your consumers because you're building it for them so you want them to tell you how to do it so here you can you can create an API and collect feedback from your consumers and then you iterate on that design so with a strong emphasis on contract versus I I went back and I looked at some of the specific things in each of the three documentation languages that I looked at about contract first design so first one is language right ability all three of them are really good especially with the amel editor now provided by Apogee that works on top of swagger mock server is really important I think because when you want to iterate and provide an intern your design and collect feedback from your consumers a mock server can do that so you can build quickly build prototypes without spending time actually creating a server application so one thing I want to look at here is reusable patterns there's a lot of patterns that we use over and over again in rests interfaces we use for example get my collection will return the list of items in the collection posts to my collection will post a new item to the collection and we solve filtering ordering and paging with similar patterns as well so there's there's got to be a way to kind of make it so that we don't have to redefine these things over and over again and this is one of the things that ramble does really well they have definitions for resource types and traits resource types define common behaviors for resource and traits define common behaviors for methods so here's an example of our resource of pets we define it as a type collection and then in that resource type collection we will define the things that that apply universally to every collection all right so now let's take a look at how these key features in ramble can affect our demo so first thing I have global resource types that ya know where I define a collection and a collection item in the collection I have a git and a post and the get in the post is is we've already implemented it already so to get lists get a list of all the resources post add a new resource of the collection resource types takes parameters the resource path name parameter is a reserve parameter that just pulls in whatever the resources that you're applying it to you can also define user defined parameters so example collection well is something that you want to pass in as well as collection schema also global traits I defined a page to create paged trait which defines the two query parameters offset and luma offset and limit that we never used earlier so let's refactor the first thing I want to do is I want first thing I want to do is I want to pull in the resource types so I can use them in this file and then I want to define the traits so now I can use these resource types and traits in my in my there on my API so we have about it's about 35 lines of code for this pets collection resource we're gonna delete all of it we'll define as a tight collection and I need an example collection parameter which will be include pet store store - pets stock example and I also need a collection schema which I also have externally defined okay can't spell pet store pet store - pets that schema ok and then so this the get on this collection is going to be paged so if I specify get here it will combine with a get that I defined in the resource site so I just need to add is paged to pull in the trip for I get pet by ID we can delete all this and say specify the type as a collection item and then we need to provide an example item which will be pulled in pet store - Peppa example alright so we went from it was actually about 60 lines total to about 10 50 lines about 50 lines total to about 10 and by externalizing these traits and resources and a global file we can apply these to several of our different API definition so my takeaway of the three API documentation languages is that swagger has a overwhelming hold on community and has extensive language support for both client side and server side but with the new Rambo has better addresses contract first design and especially those reuse patterns which will prevent you from redefining those patterns over and over again it also has better support for multiple files and it's just better in general for designing api's where you're writing the contract first api blueprint has kind of the best of both worlds it has a lot of community support a lot more than ramble and it also has good contract first design where you're writing your API documentation z' and markdown instead of Y Amal so keep an eye out for community growth and ramble as well as more of a contract first design approach and swagger and I highly encourage everyone to follow them even if you're not ready to adopt these languages today keep an eye out because I think this is definitely going to be something that you will want to do in the future when these technologies are a little bit more mature so last part of my presentation I want to talk about some of the tools that I found Client SDK generator this is the swagger github project to automatically generate code for all of your client projects and it has a at least six seven different languages that it supports right now Ramo API designer with MongoDB this is for if you wanted to deploy ramble stand-alone a chatter that I showed you today you'll want to look into this project for a persistence layer enterprise solutions ramen API blueprint have their own enterprise solutions so look into that for kind of API management / console verify code so you're going to want to make sure that your code is the same as your documentation this is especially important in a contract first design approach so there's command-line tools Ebola and dread for ramalon API blueprint respectively that you can integrate into your continuous integration and it will fail your build if your documentation is not up-to-date API mashups this is a really cool project that ramela's done where it is basically a live JavaScript app and you can quickly create prototypes as a client you can quickly create prototypes using multiple api's and create applications so an API mashup and all of your workers save as a github gist postman supports both ramble and swagger you can get sublime plugins for API blueprint ramble and there's a HTML generator for ramble and that is it