From zero to OpenAPI 3.0: Postman live stream on Twitch

[Music] hello hello everyone good morning good afternoon good evening hey kin doing good what about you on this fine day yeah i'm good i didn't have a bunch of calls this morning so i'm getting some work done and i was enjoying myself so this is good this is my first call of the day a conversation with another human being so you you're saying you had a good day and then i came in and i was like kim you need to get on a call and we'd have like people watching us you'd have to talk to people i'm sorry oh wait i'm hearing from the public that they can't hear you let's see that should be better can you hear me now [Music] hello let's see yeah okay awesome so not gonna lie we spent like ten minutes before that it was just keen talking to himself and me trying to like play with all the settings to make sure that we would go live at the right place at the right time and i messed it up somehow but um but with that said let's let's uh let's go with the flow and say welcome uh to the nth twitch stream or youtube stream because now we on both platforms i'm alani the republican postman and i'm with kim who i'll let introduce himself i'm the chief evangelist at postman so arla me and i work together as part of the devrel team and you know getting the word out about what's going on with postman so this is my first uh one actually being on the twitch stream so i'm pretty excited yeah we usually like we always try to get different people so it's good to know that we still have first timers actually apart from joyce and i don't think we've had like people coming like back and back to the stream yet so we could we have we have schedule we have like people that we can line up yet and if anyone in the chat feels like joining or has something that they want to like build with us on the chat on the twitch let us know as well this can be done okay um so today we're going to talk about open api specifically the the stream is going to be speaking two parts we're going to start with building or like designing authoring an open api from the start what's the right word here yeah i would say authoring um i think you know we'd have to up to to design you know we are designing an api but i would say there's there's more skill that goes into the design so we're going to start by just just defining and creating an open api definition for uh a make believe api um and once we've done that um we'll try i think document it probably write some tests right and we move to a more advanced part to open api where we explore and we'll ask for you all like if there's any open api that you want us to explore and we'd go into like like deeper levels of uh of open api basically um what does that sound yeah i think i think for for viewers you know this is going to push you guys into new territory you know a lot of developers uh postman is a http client so it's for working with existing apis and we're gonna i think we're gonna peel back you know use api builder primarily but we're going to show you how you know you can design define and and mock and document apis uh but still using postman as a client to kind of work with that api okay so i'm hearing from the chat that my mic is low so i need to i need to talk really like right close to my mic yes so i'll do that uh restarting by doing in case with this thing so in case you missed it is the section we do at every start of the stream when there's something that you may have missed um we're lucky enough that there was a there was a release this week so um i'll go ahead and share that with you do you know what was out this weekend yeah yeah you were uh you you didn't you still seem like you were there though because i saw you on slack and whatnot so yeah i did so um i was i was actually off when we had the release um the choice uh took to daddy and release uh or posted that post that says what was up uh the main thing was so we have this text editor like throughout postman whether it is to write like descriptions of um of what your collection is or the code and we've had like requests for a while around like personalizing that so whether you want it to have like disabling or like automatically closing brackets the phone that you could use whether you wanted to use spaces or tabs which is always like a question that comes up um so now all of these settings uh you can change it yourself you can go in the settings of the of the app and change uh what i've listed plus like all the ones so i don't know if they're all listed here probably not but yeah there's there's plenty so go there if you've always wanted to change stuff in the in the text editors you can now change them so that's the first one i have to spend time in the settings a lot more just to keep up with things i recommend as a user just popping in there regularly to see what's in there what you can configure because i'm always learning from our settings that's what i do usually uh so we have these postman on ones webinar and i'll go ahead and just show the the dark theme because that's what people want to know about but then obviously you have all these other tabs that you need to go through and like to just to tailor like the up to you how you that you would like it to be i guess um which leads me to actually the second one which is the requested response one so we've made that changes that changed a month ago probably where now you have pans within the app so you have like the request and the response and you can't like scroll them both they're both independent so you can scroll within one or scroll within the other um but we see that request that some people like to be able to just scroll to like maximize one or the other um so it's no it's not visible basically so you hold out on windows or option mac and you can scroll down all the way to see only the response or all the way up to see only the request and i think that's about it for this one it was a short one obviously there's like bug fixes or like small improvements that we don't like put there and if you wanna if you wanna really like look into what was completely released you can click on the full release notes and that's it for in case you missed it yeah i think you'll probably see me fumbling with the scroll uh as part of the the work today i'm always kind of fumbling with them and so trying to find that smoother action to actually mostly part of demos like this when i'm presenting something but also when i'm just working you know try to the the the pains the ui pins are getting much more powerful and flexible so i like it actually i think we published a blog post around uh this whole like change of plans etc right yep yep we did and i would say additional things like the console the consoles moved in recently into in in the app is part of the pane structure and then you'll see a little bit today with the open api there's validation uh in line validation and it's a pane at the bottom of the api builder so i think the pains are just getting the ui pains are getting much more flexible and you're able to do a lot more and fit a lot more into the screen yeah i'm just going to say hi to uh alan and danny look that are watching us from youtube um so unfortunately on the chat that you see on the screen there's only people that are talking to us on twitch so lucky you people on twitch you can be you can be on tv i guess but uh but if you're on youtube uh promise from next week or the week after uh we'll get everyone on the screen and uh we'll be able to see you all but i'm reading all the other messages so if you have any questions or anything that you wanna let us know uh yeah post it on etherchat and we'll read it okay um i'm gonna start sharing your screen tim if you confirm that i can that you have nothing that shouldn't be seen on your screen i think we're good i just got my postman open go for it okay here we go yeah lukma i'm famous that's me every week when i go online before we go live and i'm like my mom's gonna watch me exciting yeah so go ahead uh yeah i was gonna say lead us through it uh where do we get started when we want to do so the title is from zero to open api right so you're on an empty postman uh there's no apis there's nothing just a nice good morning message somehow oh yeah this morning for you it is morning for me it is 11 o'clock here yeah time zones are beautiful that way um and yeah twit uh postman gives you that little different little messages depending on what time of day it is so pretty cool uh yeah i got an empty workspace here i don't have any environments uh i don't have any collections i don't have any apis i just kind of have an empty workspace here so we can start from zero um zero to open api though so let's let's just kind of maybe prime the pump and and educate people about what open api is because i think uh this is our destination and it helps to know where we're going and and kind of uh why it matters i guess so um starting with an empty tab here uh browser tab let me um i didn't do the good uh hide my bookmarks so you guys don't see what i'm uh working on each day huh why didn't it work my bookmark's still there that's funny and you right click on it yeah it removed it from my other browser tab so oh actually he's deactivated yeah it is deactivated but it didn't from this window well two that you learned works on github and aws well and and partners and devrel very important to me and jira controls my life so so yeah so what is open api so uh the first rule of open api club is it's not called swagger so just to many people who are tuning in uh we'll we'll call it swagger when swagger is version two of the specification so back in 2010 2011 tony tam created swagger uh which was a way you could uh document your api and then around 2015 it was put into the linux foundation and the open api initiative was created and the uh the specification moved from 2.0 to 3.0 and was renamed as open api so if you're saying swagger you're talking about a set of tools uh documentation swagger hub which is a kind of marketplace we're talking about open api the specification here and this is the next generation and where we're going with open api so this is the open api initiatives website there's lots of information you ways you can get involved you can go to the api specifications conference but we're going to focus on the specification which you can just uh choose from the top nav click on the latest and we're looking at the api specifications so i wanted to have this open because um as we're working with api spec uh i want to be able to to look back here and use the documentation to help kind of guide us that's hopefully it's going to be helpful for some people on the chat that's definitely going to be helpful for me because as much as i like try to do open api postman i know like most of my time is to spend helping people and i just like they'll send me a whole thing and i just need to look into it and see what's not working i've never i don't think i've actually ever started from zero that's gonna be a a good good thing to know where to where to get all that information yeah and i mean i i would definitely consider myself an advanced user i've been using it since 2010-11 um been active role in in moving it forward and i still struggle very much with some many of the objects getting parts and pieces and then just how do you do it well kind of what i was saying about the design part is as all right i i kind of know the vocabulary of how to use the specification but how do i use it well and and and craft a really good well-designed api and so i think this exercise is is really good for me in that sense as well so let's go back to postman so this is our destination is is having a usable meaningful open api because we're going to show you why that matters why why having an open api even even matters to you so back to xero good morning we're in postman so uh let's create an api and uh using the postman api builder so if you're you're in a workspace um and you know many of you are very familiar with the collections tab i would say venture into the apis tab because this is where you can actually build apis so we're going to create a new api um what what kind of api are we going to make arlemy so i was wondering so i think there's a default one that is kind of a marketplace but that we see so if there's anyone in the chat that has an idea of an api so we want an api that does they create like the cred hey yeah yeah we're going to create one resource in a kind of restful api sense that we can create read update and delete that that resource so we you know is this a a user an image a product api there's many different types of resources that we could build we have a jetty zone that i've been told i'm not allowed to say who's behind the the name who says create cat okay so we want with cat or cats being our resource because we probably want to create many cats and i suspect you know whoever is behind that uh yeah i'm i'm you know cats run the internet so this i think is a pretty logical place to begin so we're going to call this cats and then we're going to this is going to be version one of our cats api and um oh and i didn't shut my door and so if my dog comes in and jumps on my lap during this um you know why because we're making a cat's api i was gonna say because we are talking about cats in the air so is it um just a quick question would it be like a normal thing to start from 1.0 point oh are you just giving that as a no normally you would you would want to start start right here you know and i think some people are an argument whether you should start here but i would say our first incarnation is going to be uh right here i when you're building a first api and getting that iteration i don't think uh in my opinion in a semantic versioning world uh 1-0 is like when it's the first fully baked version and and everything before that is is just cooking in the kitchen so yeah thank you for that so um and then we're not gonna do once we do a patch we can once we break something and we have to go fix it um we can do a another minor there um all right so schema details so when you're using postman api builder you can use a variety of of schema to to define your api so you can use open api three you can use the swagger 200 or 100 version you can use raml1o or point a or it could be a graphql api as we talked about our destination is open api three so we're going to choose that then you can choose your schema format whether you love json or love well i have to admit um so yaml reminds reminds me very much of json i was very much an xml lover i come from the soho world i really believed in xml um i hated json when it first came out and i i hated yaml when it first came out too so um both have warmed my heart um and i've learned to love them both i would say i'm going with yaml mostly because for demo purposes it's it's easier to read you can comment and and put spaces or line breaks in your yaml and it it's not it doesn't seem to scare the the muggles or the normal people uh as much when when they're looking at it so i can show a yamal uh open api contract to uh some business folk and they don't crank if immediately if i convert it to json and show them they'll be like oh i don't i i'm not a programmer i don't know and they start changing their behavior so so i like yammel what do you think yeah no i think agreed even though like i would have the different position where um like i hated xml the day i could start using like rest apis and like json i was so happy but i think to the same point like xml was very descriptive and you had your tags and you know like in that tag i have this etc but then that obviously as soon as you wanted to get into complicated scenarios especially with like like so uh and like loops and et cetera et cetera that that was getting like very complicated yeah so yeah like i'd go jason but personal opinion uh and i do agree that he's much more readable yaml so let's let's go with let's go with yammer yeah so we had someone on on youtube worried that we would have to delete a cat well um so we'll we'll address that i think that's actually a really interesting one though that'll make for a good conversation in a little bit so let's let's hold on that one and there will be no cats deleted as part of this i guarantee it all right so um we're going to open api three we're choosing yaml and we could import an existing schema maybe we can look at that later if anybody has a another api an existing api they wanted us to look at the open api but for right now we're going to start from zero so i'm going to say create api and it gives me a little instruction instructions here kind of on the next steps my cats api is created and i can hit close and now um in the left-hand side here i've got one api called cats and i think i can zoom one more yeah probably right there um and then i've got my dashboard my api builder dashboard the overview of what's going on here um gives me some details that we already talked about it's open api through yaml i'm an editor i can invite arlemy and other team members to work on this and we've got this nice dashboard that helps us uh manage this cats api but we're going to look at define the define tab because this is actually our open api and uh this we we we made the commitment to start from zero and postman when it when it starts you off here it uh gives you kind of a boilerplate template uh open api to kind of give you at least the basics of a of an api and we don't want that we're gonna actually start and go back to zero and see delete so uh we're gonna we're gonna just walk through this and again the open api specification is going to be our guide um you can click down here to the schema and all of the major moving parts here of how we define the open api are available here and there's examples with each of these so we're gonna try to use these to copy and paste and and hand type and actually start from zero so with that said um we're gonna we're gonna start out and our our open api contract here for our cats api is uh starts line one is always open api it's the first property of what we're doing um i'm only fluent in 3-0 um we we're up to 3-1 now there are some uh uh the the spec has evolved over the last couple months um so we have a 3-1 available i'm not totally fluent in it yet so um i'm gonna stick with what i know and what i can actually have so what's the red cross for is it like checking your your syntax yeah so this is um it's missing other other properties so it's basically giving me uh inline feedback on whether my my api is open api compliant and so a little behind the scenes this is using the json schema for the open api specification to tell me what's missing what's wrong and give me that feedback in line so this is not a complete open api document even if i've got the beginnings here so next um as it was yelling at me we need an info block so the info block gives me uh just basic information about what this api is and what it does and so we're going to and this is this is yaml so we're going to tab in to kind of uh start fleshing out our info block and the first property is title what is the title of our api so i saw in the in the slack in the twitch stream there adopt a cat so rather than just making this a uh a cats api we're gonna call it our uh cat adoption api and give it a a pretty basic name you know you wanna keep your your names your api is pretty simple and and describing what's going on right and then from there we can um go to the next line and let's give it a little description what this api does and you know we want it to be a little bit more informative than the title whoops and autocomplete sucks sometimes i really hate autocomplete sometimes when i'm not paying attention so i auto-completed my api um so this is just a simple api for helping and my keyboard is not working very well today helping adopt cats all right so we got a title and a description um we also want our like is there rules as to like the length of the description or can you just go like as long as you want you can go as long as you want i mean within reason i see there's quite a few apis that will put uh you can put markdown in here um so they'll put like a full robust set of documentation descriptions here i recommend keeping it pretty short and sweet and then rely on your docs to kind of wrap that so this this is our contract we want to keep it the language pretty precise like other link language or legal contracts but this is a an api contract so let's keep it short and sweet and then we'll we'll farm out the the doc the explaining of it and the verboseness to the documentation because this is going to be used in other places like code gen mocking and we won't need though you know a verbose description in all those locations so so next uh we're looking at version so when we first created this it uh put the version uh in for us um but we're gonna have to put it back here so this is the version of our cat adoption api this is not the version of the open api so we're um just to clarify so we're oops we're at 0.1 um yeah we actually did a stream with uh lorna jane from phonage and we were trying to remove stuff so the open api i mean we were i was trying to remove stuff that would make it not to validate and i think like playing with that version i would not find a way to write it that we would not work or would not validate they kept kept on trying kept on trying but we ended up just removing the open api at the top interesting yeah no i will have to explore that a little bit more and see what what what's the cause of that and why um so let's look at our little red x up here and see what it's yep so it stopped yelling at us about paths or info the info block excuse me so um it was saying hey we need info uh and paths and so um now we got our info block we got kind of the basic building blocks we've got a name we've got a description and we've got a version for our api so there's we can go several different directions here and how you know what you you define next um it's telling excuse me it's telling me i need uh path excuse me which is uh starting to get to our api paths um in a in a resource in a restful kind of way so but for me i mean maybe this is different for people different people i always start with the schema i always start with uh the data that's being made available by this api because it's a little hard to provide you know apis are about access so it's it's pretty hard to provide access to something that doesn't exist so for me i like creating the schema first and then i provide access to that create read update delete to that uh to the to that schema that i'm making available so let's the schema would be like the cat object right yeah yes and we'll have to figure out what that is and what you know um in a little bit but that's using uh json schema to describe it and in open api 3.0 um your schemas are managed through your oops components object which is think of it as a it's kind of your toolbox for this open api it's going to have all the parts and pieces of the of the api and then we can reuse those parts and pieces throughout our api design and this helps you be a little bit more modular and reusable and how you're you're building your api so this one is not a required it's just you can use it to make it like easier to use and like more to reuse but you can just have them at each level in the path yeah yeah you could exactly so you could just build out your paths and put the objects that get returned in line in those uh paths but then you're gonna you know we're gonna create a cat object which we're going to use in multiple places so it's this is one of the things that open api 3 forces you to do is think about reuse down the road because in swagger2o there's a lot of redundancy you're doing a lot of copying and pasting and uh this is just a lot easier look it's a lot more organized and you'll see it's it's just makes a lot more sense it's a lot more logical so the components object has a variety of uh of objects you can put you can store it in it one of them is your schemas so you can start organizing different schemas and this is i think the beauty of api specifications or just open specifications is open api has adopted json schema as par as its schema model for modeling and so i guess let's let's actually just look real quick um let's open up that tab for json schema i think it helps to pull that up so json schema is a uh is a way uh it's a vocabulary that allows you to define those objects that that you're going to be passing back and forth as part of your api and it's this pretty standardized way and as you'll see in a little bit if we can get to the testing portion of this uh we can we can use this json schema to validate and test our contracts so that's just a quick look at json schema so let's um let's define a json schema object for our cat so let's uh click down here let's go cat is going to be our object the object type is it's a it's an object this could be an array it could be different types but our cat is a is an object that we're using and then um what are the properties what are the properties of this object uh we've got these are the fields these are the fields if the chats on both platforms can help us obviously an obvious one with the name i guess yeah i guess i mean for me i actually always try to start uh and this is another reason i start with schemas is i go to schema.org because i tend to not try to reinvent the wheel when it comes to these things um and you're better off again this is why we're using open api and json schema is to use things that already exist so i just go see if uh if they have a cat they have a cat object uh okay so cat's gonna be pretty difficult to find because cat could be cattle you know there's many different ways but you know in schema.org world a thing is kind of the base level schema object that you can uh start with and with anything it starts with the name so yes you were correct ireland and then suggestions are what is fluffy some guess i guess [Laughter] or maybe can you have like a type of fur like fur type yeah then well then we have owner bridge and so the oh nice tail made he's saying owner and then isn't saying no one actually owns a cup the cat owns you as everyone knows well what what you put in the owner field i guess is up to probably up to the cat because yeah so he you know and yeah so it might be the cat you know might be the cat's name i guess it depends on the household right yeah and then we have breed yeah breed so let's go for something that wouldn't be a string uh can we get h in there probably yeah yeah yeah so i've been uh putting uh what type of these properties are and these are all all strings so uh yeah let's go age and the type is so let's go with integer on that what other fields or properties can we get a boolean from the chat so let's see i caller we have that would be a string from youtube what is it what is it again the eye color oh yeah okay that could be that could be an array as well some they could have different headquarters oh so that's not really a boolean that could be an array um interesting um so one other question here are how do we type our properties you have eye color is that snake case is it camel case what do you what do you prefer ireland um i actually don't have a preference it's some often i just go with what i have in my head at the time i would go like i would actually go with a dash on this one which is probably not recommended maybe recommended so so one warning i would give that is you're not gonna want properties that have dashes in the url if these if these properties end up in the url my recommendation is always start here with snape or camel case or go this route for i prefer uh camel case for object properties but that's just me and i don't know where you check in with me each season and i'll change my tune on that next next year i'll be hey no it's all snake case this year kids so uh joseph is asking if eye color can be a minim uh yeah yeah you could uh you could have a a list of enumerators that allow uh kind of define what goes into those oh neutering is a boolean yes it is we have we we're crawling through uh like under suggestions now let me let me go through a few more ones uh dimensions weight um castrated could be one as well there would be a william yeah and fluffy so let's put fluffy because otherwise i know i'm gonna get told off by my boss so that's let's add fluffy in there all right and so fluffy and fluffy is a boolean right yeah yep all right so i think we've got a pretty good mix here of uh different types we've got some strings integers array and a boolean sorry if we didn't get your suggestions for the sake of the of the cut i guess so for his privacy so now we've got a basic object uh we've got a cat object that is uh has a handful of properties now are any of these properties required so like this is json schema and this is one of the reasons we can we use it is it helps us kind of enforce the integrity of these objects and making sure they follow a certain set of rules so we can say required and we can put uh whatever fields we we feel should be required for every cat every cat should have these um name right what else do you guys feel is required wait to me it kind of feels like some cats is probably the only thing that you actually know about i guess eye color this one you can tell right yeah so we'll grab that now i'm i'm gonna pause just and bring in my put on my api uh designer hat here and go or actually i'm gonna start with my database administrator hat so we need a unique identifier to identify each cat because i'm guessing there's many cats with the same name and we're not going to be able to tell these apart so i always recommend having an id property um which you can make integer and increment or you can just make a string but i'm going to make an a an integer and then i would add description we need some sort of description of each cat and that's just a string i'm going to add that and then i'm going to go back up and i'm going to make sure my id is required because every cat should have a unique identifier that sound fair yep all right we've got a cat object now uh let's let's talk about how we actually make this uh cat object available by an api and not just an api to be able to get cats we want to be able to actually add update and not delete it's gonna have to cut here for one second yeah just checking do you happen to have this the audio of the stream running on your pc [Music] someone is getting a bit of a nico um i don't i have it i have the stream open so i can see it but it's muted okay then fine so i have this i have the skype is the only one that i have so yeah it's probably something on my side i'll i'll check quickly well i will uh let me close the stream because i'm just as long as you keep an eye on the chat yep um okay and see if that fixes it and then we can diagnose from there all right it is closed uh so now we have a cat object we want to allow people to uh get cat objects or cats but we got to be able to add them first right because you can't actually get a cat until uh you you you're able to add that cat so let's define the paths for this api uh right here under paths it's still waiting for us for the validator uh to do this and so this is every part after uh the host or the domain where we're gonna we're gonna host our our cat api maybe it actually helps to to talk about that object here so let's let's talk about servers for a second so where is this api we don't we don't actually have a server for this api but this is where the the server object is how you define one or many places where you can actually locate this api uh using http 1 1. so this would be the url for the server and it would probably you know be something you know http we want to make it secure we don't want any cat information leaked um and then whatever our domain is and this is uh uh pretty standard you know you'd have a url you could have multiples of them but the path is everything that comes after that subdomain or url for uh our restful or our rest api and so when we're defining a path the first thing you define is um in a restful way we're gonna we're we're gonna get cat we're this is a an api for getting many cats so we don't wanna just call it cat because we're not just gonna be able to get one cat we can get many cats so in a in a restful way or a resource oriented way we're going to call this path uh cats and this will go right after our url here and be be our caps resource and then we can start defining each individual method http method that is available for our uh cats api adoption api and the first one because we want to add is use post so post is how you submit information and create new resources using http so we're going to create a post method and we're going to give it a little summary that says add cat and we can give it a little description uh this allows you to add a single cat now we've got our summary in our description of this and then for for various reasons um that that we may or may not cover later but you need a unique identifier for this method to be able to for when you do code gen there's a number of reasons that you want a unique id for referencing this api down the road and this is one of the things that people tend to forget and so this is a good reason why the open api specification it kind of acts as a checklist for all the things that you should be thinking about with your api and when you're you're building it so uh the unique identifier in in open api speak is operation id and they are camel case and we're going to just call this ad cat now this is a post so how are we going to get the data in here um as part of this where we it's a post so we should be using the body uh to be able to describe this and so i don't actually know the syntax for uh for the request body so this is where i you know fall short and and what's in my head and what i can actually remember and i go to the open api specification here and we have worked our way down the objects here looking at so we've done the open api we've done the info servers we're in the paths object so let's navigate to the paths object that's interesting interesting so let's click down here um here's a here's a path object in json here's a path object in uh in yaml um we're going to go down to a specific path item and this is where i think there's a there's a question chat yeah um so do people normally start with the open api spec first like you're doing here or do they have an api first and then they make the open api part most people have already have the api so people are historically very code first you you create an api for a for a mobile app or a web app and you have that api there's a new you know starting around 2012 there was kind of a movement to what's called api design first and it it involves not writing code and not creating your api and actually designing it or defining it first using an api specification and like a swagger open api raml api blueprint all of these were kind of created in response to that movement and that's what we're going to show you here is is a is a design first approach because we don't have an api we don't have a cat adoption api so hopefully then we can talk a little bit about why that's beneficial because it you know in short it can save you some time and energy and cost it's it's pretty costly to code apis first and if you don't get everyone on the same page about what that api should do um then uh then that's a problem you you know it's going to be more costly for you to do things so um so yeah all right json api is something similar to open api no so so json api is let's go back to the browser here and i like googling these things because then you know it's it's what someone would be doing if they want to understand this so json api is a specification for building apis in json but it's it's not the full surface area of your api it's a it's a specification for defining uh the response model that should be uh provided with each api response so that there's more structure to what gets returned rather than you know we just created a cat object out of nowhere um well we use schema.org but this gives you a lot more structure um it has basic hypermedia built into it that'll give you links back with each response but if we use json api we would put our cats object right in here and define it as part of the data object for it and so json api is helping you be more structured consistent and use a standard for for the response structure of your api and it gives you a lot of affordances like hypermedia dealing with relationships dealing with sub resources and a lot of things you're going to hit down the road once you operate your api for a while so i highly recommend looking at json api and considering it and there are examples of designing your api using open api uh with json api um and so i'll have to find a few of those but there are some pretty good examples of that all right no more questions back at it yeah back at it gets cracking so uh yeah otherwise we're not gonna be able to mock doc or test this yeah so um so i'm gonna i'm gonna slowly pick up speed on it pick up some momentum here um so we're we're trying to define the request body structure we need to be able to post this um and i didn't know uh i didn't know how to write that so let's look at a post operation object um let's see if i can find a post one here that's easy for me to oh i just gotta find a request body and that'll give me one here okay so what we have here is uh the request body object uh this is a way of defining the body that gets submitted as part of your http one one request and um let's me i don't like how they do the examples here uh because it doesn't actually show the the object name and so what i gotta do here now is is i gotta say okay i wanna do the request body and hope i type this right well you would complain if you don't right like yeah you should get an error yep so it's it must be an object okay well let's um let's go back to our um so i'm gonna just grab i don't want all of this so i'm gonna just grab this part right here so this is the description and the content of that body and if i go back to my postman paste this in here and then this is one of the you know the problems with the ammo is your delimiters are tabs so we've got to hopefully get our tabbing correct i think that'll be all right we'll see if it keeps yelling at us so application json why doesn't it like that because i don't think it's tabbed properly so let's keep looking at what it's yelling at us for it's yelling at us for various things so you see as i'm i'm correcting this so we have a request body for this it has a description um this is the cat object and we can get better at our descriptions uh the content for this because in open api three you can have multiple content types so this is application json i could have if you go back to the the reference here um i could have an xml representation i could have a text plain implementation i could have html i could return html there's a lot of different ways you could or i could submit sorry um i'm doing the request body i'm not returning so i have an application json now it has this schema property and this is called a reference so all this is doing is saying uh within this document that pound sign because this could be a fully qualified url referencing something outside of this document but this is just referencing components which is right here so you highlighted it for me so i'm just saying components schemas and i'm going to say cat because this gets i'm gonna submit application json that represents this json schema object for the cat now um our second property here is called user we're going to change that to cat and this is our example so say go back and look so we got id so let's say the id would be one the name would be um was it the name of your cat do you have any cats i do not my brother has one it's called shadow shadow my daughter has a cat named shadow as well original do you know shadow's eye color uh i do not actually i've never met you we're gonna go with them an orange um because because why not um why is it yelling at id invalid property id so examples we'll have to figure this out a little bit i don't know why yelling at me for this i'm guessing oh is it because you have an extra space in there maybe no don't know so i have to go back and look at my properties here so examples user so they're using the next little euphrate don't know why it doesn't like that looks like all my tabbings are correct it's with these lines helpful are helpful for cat i do not know oh this is another one that gets me examples for example that's examples so it says uh do we provide cat or does cat as an example needs to refer to something else well because you could have yeah that's that's a good question let's try that so but i'm i'm assuming examples would be multiple examples making this an array and it doesn't like that so i think looking back at the example here um so this is a user example and their object is a user so this is just a lowercase reference of this um saying this is called a user and this has two properties i don't see what um let's see well do you have a summary of the example as well so let's look um missing required so what i just clicked on here is down here at the bottom and what we're talking about with pains you have more detail on what this is this will give you all of the errors that you have and we have several errors um one of the things i i like to do is i don't like to worry about them because sometimes they'll trigger we don't have any responses for this api yet and that could be cascading downstream sometimes or upstream and causing problems so a lot of times i won't stress on every error i'll just keep going until we can uh um and then i'll i'll do a round of cleanup at the end so let's um let's keep moving um so if we we are going to need a response for this api request next um and responses live so we got a tab back at the same level as our our method so our method is we've got a summary whoops we've got a description an operation id the request body what what gets submitted now we want a response we want to be able to actually show um that we have a what what should come back and i'm going to actually copy and paste this guy too let me see here so i'm gonna so in the meantime if anyone on the chat knows why the examples did not work let us know yes please we can correct so here's here's an example response object you can have you can have many of them and yeah we're gonna get our our tabs correct here so every hopefully you have a happy path for each response we have a 200 status code for this response we have a description um and this should uh return now with a post do we return a 200 and then return what just got posted do we okay yeah do we re because you can um what is it 201 anyone know what a 201 is this is another thing is i don't know all my status codes created yes thank you so a 201 is a uh that saying that uh the cat has been created and it's funny we're doing the cat api and the default for open api is the pet store yeah so um so yeah we're i think we're we're right on par um and again well do we want to return our uh we don't want to return our schema so it's going to be an empty return we're just going to rely on the status code to say that this was successful we're not actually gonna we're gonna return an empty body with this coming back and that should uh alert people that it was created or alert any client that's making calls to this uh that it's it's working so now we've got the ability to to add uh uh a cat now we wanna be able to let's let's actually hit save while we're while we're at it here um [Music] hold on one second let me so i've looked at other examples one of them was using example singular and then there was no cut yeah like the id name i recorder and miguel says should the id have semicolons just like the status code oh no yeah i got that so examples that's an object let's see here let's keep let's delete some of this and see what it gives me okay it must be an object we got that and then an invalid property id i don't know what that is that's weird well i'm not going to worry about this one because in essence of time let's keep it simple and let's keep it valid we've got a valid oops we actually don't have something about so what's going on now um ah come on invalid property response it should be responses ah responses and there we go schema is validated we are good to go no errors found and you want to do this along the lines um but if you can't always you know you can kind of cue up those errors and deal with them at the end if you need to um so according to media type object you should have a value field according to mentor vanillo the so the media type here should i have a value i think this is this is what's going to be our value i'm not quite sure exactly that like which bit is referring to i'm guessing it was when we were trying to check for the the id oh yeah yeah so that's that's the value of okay yeah that would make sense um i'm not going to deal with examples right now because i think we want to get to a complete open api here and um and so uh so let's let's let's plow forward so so i have my add method i want a git method okay and it sometimes it helps if you just want to copy and paste um whoops come on there we go and i'm going to just paste the same method but i'm going to make it my get so this is my get method and this is get cats i'm not gonna get a single cat i'm gonna get all cats uh so this allows you to uh get all cats and we're going to call it get cats and so this we don't need a request body because it's not a post let's get rid of the request body let's leave our response here but we're going to make this a 200 status code and we're going to say a successful list of cats and then we're going to uh but we're going to actually need to return a body this time so we actually need something here so let's go back i'm going to grab this content property here go back to my postman come here i'm going to paste it in it's apple content application json schema ref and then again we're referencing but we want to reference cat but wait this is a problem because we don't want to just return one cat we want this to return an array of cats and our cat is an object and so we have to like okay now this is uh we have to do something different here as far as how we return these so we need an array we need another schema object here that is um and we're going to call it cats and this type is an array and then i believe and i could be wrong see if this works um that's what we do on the stream anyway we just try things and see if it works yeah and that's this is my normal life destiny isn't even that um so i believe it's let's go um and i just do not know what that is let's go back to let's see if we can find an example here um items that's what i needed right here so i'll just do that a lot where i just kind of find something that works we're going to paste it in and then i'm going to tweak it because i'm not an engineer i'm a reverse engineer and i just reverse engineer things all this array of cats is going to return is a cat is an array of cat so now i can reference cats and i believe my schema needs to be tabbed in and still got two two issues missing oh and i called it responses again no uh the this one is called response the other one is called responses ah so maybe it was both responses about property response so this one should be responses but the other one too oh and this one needs to be responses i see okay here's the issue when you're like that zoomed in it's good for the viewers but when you're trying to debug like a long file of long spec doesn't help yeah so so now we have um uh we have a get method a summary a description an operation id and we have a response a 200 successful status code that returns application json and returns cats which is just an array referencing the cat object so now we have the ability to add and get cats but we're going to want to update cats as well and we're going to probably want to do some other things and this is where we get to uh talking about um what uh the delete are we gonna delete cats and so this is where we're gonna need a new path because we don't uh cats is just working with all cats so we want to be able to add a cat into the pool of cats and we want to be able to get all cats with this path if we want to work with a single cat we're still using the the cat's path but we're going to extend it and we're going to go further and we're going to uh oh man variables always screw me up platform between postman and everything is another thing that my brain my brain just doesn't remember is um how to do paths so let's go back up to the path object and okay so it's variables like this one bracket um and this this is we got to keep working on this as postman so this is where we we pass in the id for our for our cat so we're gonna be working with one cat here rather than all cats and we're gonna pass in that unique id to actually get uh get a cat back and so so now we need to be able to what do we want to do we want to be able to update updated cat is what we're going to do here yep okay so i'm gonna just keep copying and pasting my my uh methods up here so i'm gonna grab uh my post method because a lot of the parts and pieces are gonna be the same so rather than it and i need to tab in one and i'm gonna call this a put because we're gonna update a cat and change my summary i never see the i often see post used for updating right like yeah the put is very rarely used even though that's like the it's the way that it should be i feel like we've lost its usage over time maybe yeah well i don't i'm not sure we we ever ever fully had it yeah i think and i think patch can further confuse the subject for people the way http methods were handed down uh um from from the mountain i think along with moses and the tablets was with apis is is post is create of a resource uh put is update a full resource like all of the properties of that resource delete is delete and then git is get and patch came in as a partial so you can update some of the fields you don't have to update all of the fields and so that just people understanding that was really difficult and and a lot of people just kind of use them as they need you know and so post and get are i would say the most ubiquitous um and most people just shove everything else in a post anything you need to create or update or do any any transformation on so yeah it sounds about right so but if we're if we're arrested firings um we believe in our verbs and um we can we can use our verbs properly so we're going to use the the request object it's going to be application json it's going to be cat it's going to be the same as a post but we're going to update this and then um we're not going to use 2 201 what is appropriate status code for for a put i do not know off top my head i never remember these things um so i don't think i could remember that one either that's a so for a put 204 yeah that's what i remember so 200 or 204 should imply the resource was updated successfully so i like going with the 204 just because it's um a little bit more restfuran and and fits with the with the vision and then again i don't return anything with it so now we have the ability to add oops we got an error what's our invalid property cat's id so why is it tabbed too much yeah i think so we're yep i went in too far so this is this is yaml fun you know always making sure so now we're good and our schema validated we're good so now we've got the ability to get add get all cats and update a a single cat let's also um let's grab our get here and let's also allow us to get a single cap and are we tabbed appropriately yes we are our verbs are lined up and this is just get capped and this allows you to get a single cat [Music] and i'm going to change my unique operation id to get cat and then the response is 200 a success this is a successful return of cat and i could probably use better language for those but i don't care and i'm not returning cats i'm returning a single cat and so that gives me an individual get for this path for for updating and then getting a single cat and so we've we've got most of our we've got a acra api we don't have a credit api yet because the d in crud is delete right so we don't want to delete cats so i what i recommend doing so because we don't want to ever delete cats and as a a cat adoption agency we probably want a history of all cats who have always been uh adopted as part so we don't want to delete cats because deleting cats is not good so i would say we go back down to our schema and we add some sort of status status like adoption status yeah just um you know well maybe not adoption i hate to say maybe some cats pass away too before they get adopted um i would say there's going to be several statuses needed and this is where actually uh the previous question of can we add enums we could say it is adopted it is available um we could probably come up with some better um is dead the right word um passed where do cats go when they pass like unavailable unavailable okay so um we can add some options uh enumerators for what uh constitute status so that answers our delete question we're not going to do a delete so we just got a cra api and when we want to change the status of a cat [Music] we can update that status and then we can let people this will show when you're getting cats we can add a parameter object and let's go back to our our uh open api specification and let's look at our parameter object and let's grab a parameter object see if he's got one down here i think joyce was trying to start a debate on youtube as well she said jason is superior to yaml so if anyone has anything to add to that [Music] so i just grabbed a parameter property and so say we want to allow people to filter and so the name is status it's in the query i want it to be a query parameter and this is used to filter cats returned by their status uh it's not required you can return and what is wrong value must be an array oh yeah so uh yeah chris is saying tabs versus braces choose your poison yes exactly exactly so that'll probably do so it looks like we're valid we're valid schema so now we have a property that allows us to filter by the status so in in practice when we query this we can filter by status and get back just a certain status of cats and we don't ever have to delete a cat ever and so that's not a crowd api as i said it's a craf api but it's pretty close so we have if we scroll down we have a schema for cat with all of our properties we have an array of cats and then we've provided two paths unique paths one is cats for us to post or add cats allowing us to get all cats and then we can update or put a single cat to update its delete its details and then we can get a single cat from the system does that sound like what we're wanting to accomplish for just an open api yep sounds i mean that's like hand read lines already it's pretty good for for cro api yeah for api so yeah shinkin is saying jason takes up more space than the imo which is probably true yeah depends how like again depends how you indent your like json like we've seen some weird indentation from some people you never know which i guess is probably one of the things we've chosen right like you could have a lot more on the same line than you could with yammer yeah yep so it's a you know but json was lighter weight than xml um and but it's it's easier to hydrate and dehydrate json too you can you can minify it much easier than you can yaml because yamo you have you you're reliant on those tabs and and line or carriage returns what i do like about yaml is you can comment yeah that's some someone just pointed that out as well um yeah my readability is superior so it's more comprehensive oops that's not actually a valid comment but it's a it's a hashtag right it's yeah that's right so i'm thinking in my my javascript or uh other code head yeah so we have an api now that's it we don't have an api we have a um design we have a open api definition before sorry for for it so um now let's you know we want to develop this api we want to do something with it in an api first world we we want to mock this api we want to make it as tangible and meaningful as possible without actually having to write any code because right now so far i haven't we haven't written any code right so we want to try to bring this to life to make it make it a little bit more tangible because not everybody we give this to is going to make sense if they're not open api fluent they're going to look at this and and be like well okay what it's not an api what do we do now um let's go write some code and you can do that that's a valid way to bring this api to life but for an api first approach we're gonna want to mock this api and so uh using the postman api builder you can generate a collection for this uh open api that we can use as as the mock representation of the api so excuse me so let's go and hit generate and we're going to call this um this is our mock and we're going to choose uh the purpose is api mocking and we'll show you why in a little bit excuse me so naming my mock server so this is my are we mocking cap we don't we don't delete or mock cats no making fun of cats through cat if you make fun of cats they're kind of like crows they remember it forever and and they'll come back um we're not going to if we want to make this private we can make it private so it requires an api key to access i'm not too worried about our cats api right now um so i'm gonna not make it it private and we could save the mock url as an environment variable which is a pretty handy feature but i don't have an environment should i create an environment parliament you think first or can we do that after the fact i think if you tick that box it's going to create a new one for you let's try it um i was actually learning a lot of new tricks with mocks and uh running postman buttons from joyce yesterday and i'm i've got some new things i want to try out here so i'm very happy to try that but i can't get to my button because get it to zoom in there's my button down there um and there's my toolbar um so let's go ahead and create this mock server or mock collections excuse me and if i look over here under collections i've now have a collection that represents has my get my post my put and my get for my single cat so now with this said man the ui is just looking pretty slick it was like a part of the part of the update i didn't mention but yeah we've updated like a lot of the logos and stuff which it's a lot arrow here is smoother it's just oh yeah we had a debate around that last week i think we're trying to choose like what it's supposed to be because it used to be a play button we never knew but yeah definitely an arrow now so this mocked my created a mock server here i've got a url here when i chose to do that that is slick that makes me so happy now that you can do that and i've got a collection that represents my my api here or my my my cat adoption api and so um do i have an environment i have a cat mock environment oh my god i'm so happy it's got the url in there the base url in there exciting but let me look at a request here let me look at my cats oh it's got base url um so we got a little bit out of whack with our variables so this yep this is is not gonna match our we use url here is what i let it auto-generate and we and we want base url that's all right we can do that pretty quickly so uh we got status as a property i'm not going to worry about passing that in i just want to send say get what do i get look at that i've got one really basic note i've got two really basic cats so how did it do that are let me how did it how i didn't create that json how did it do that i just took it from your components yeah yeah i'm not sure how we decided to do two instead of like i think one or more i think that's just probably our product team assuming it you know because it's an array because we properly define it as array arrays with one in them sometimes confuse people because it looks like it could just be one object you know so so yeah so it's creating two but what it did is it took it went through the json schema and it created an example from from these so it took all of these fields and the types and then it just created a basic uh base object now if i this is just stored as an example up here for this request so if i wanted to actually update this and want to actually put you know some values in here i could actually update these and do that here so i could actually make this example put put the cats that i wanted in here and make it a little bit more tangible for people wanting to do something with it so we didn't deploy the api but we mocked the api so we have a functional version of our of our api with a click of one button and just giving it a name so it took this open api and it generated a mock server pretty slick so i would say the next thing that we want to do because because we're not developing the api the reason why we want to do api first is uh we want to make this api as as real and tangible as possible so we can share it with other people so we have a team that's going to build the the cad adoption website we've got one that's going to do the cad adoption mobile application and then we've got some other uh cat uh rescue places that want access to our list of cats to just be able to pull so uh we want to make sure hey do you need any other fields in here are there any other properties do and because this is a cad adoption api all were created so far is the ability to manage the cats we would need to add a new path that probably would would go after the cats here and we'd probably do something like adopt and we would add a method for being able to actually adopt a single cat and then we could build that out and continue extending this but right now we want to just really you know in an api first kind of way we want to make this as tangible and real as possible so that we can share it out with people and get feedback on on what should be added we don't want to just assume oh we're going to need an adoption path we want all of the stakeholders involved to actually give us feedback so we've created a mock the next way we can make it really tangible for people is to generate some documentation so um let's uh so i'm going to name the collection documentation the purpose is docs can you look at the oh today sorry i was going to look at the advanced settings that i think we've added recently as well um and i think there's something around examples and what you can use for examples yeah this i saw this conversation yeah so for request parameter generation yeah so if you choose schema it's i think it's going to take the the type and infer from it i think this is yeah so it'll pull from the schema and for from an example from the schema the same way it did for the mock where if we had finished our examples in the open api it would pull those from the examples from here so i think that's the separation because we didn't create our examples in there um it'll generate them for us so that's let me redo that because i actually want to see that so i'm going to delete whoops i'm not going to delete mock i'm going to delete docs let's delete this one and let's regenerate that so we're gonna call this stocks api docs we're gonna go to advanced settings i'm gonna scroll down and i'm gonna pull a request parameter generation from the schema response parameter generation from the schema folder organization by paths i'm going to leave that one and then i'm going to hide these so i can see my button and i'm gonna generate okay now i've got a collection here um one that is driving my mocs one that is driving my docks but i have to go one extra step to actually turn this collection into documentation i've got to actually publish it as docs which similar to the mox it would be nice if it automatically did that if that was the purpose of it right yep um and this is one thing you encounter this a lot where there's no environments listed even though we have we know we have one environment i get this pretty regularly and i'll show you how i i overcome it um but when you publish your collection as docs you get a whole you can associate an environment you can do some styling around it and then you can choose to add it to the postman api network or add it as a template i don't want to do that right now because we're just going to try to get some docs out the door and then you're given a url here and there's our docs they're not the prettiest we look like we could do a little bit of work um we could better organize or better label our folders i think rather than just relying on the auto-generated names we look like we need some some better descriptions at the collection and the folder level but you know our individual methods look pretty good they don't look too bad so we got each of our methods we got some basic example requests and body responses for the body all right so that's our docs so now in we should be able to share that url with users and then when they land on the docs they're able to hit run in postman and that will load the collection into their workspace along with the environment and uh i actually that's what i learned from joyce yesterday is how you can generate a mock also as part of that process not from the docs here but from a regular run and postman button so um that's going to be my next uh kind of prototype that i play with is they don't you know do i want to give them access to my mock server because that's going to hit my my number of calls on my mock server i would rather them be able to mock it in their environment and use that but either way it allows them users to be able to see what this you know see this api like i had published it's got actual docs um if i share the mock with them they're able to make calls to it see how it works um and actually play with it and then give feedback to us on on they can actually come in here in their postman if they have access to this workspace they can come in here and leave comments on this api you know you know adding new fields you know if i want to add new fields or i want to say this looks great so that the comment thread exists here around the api and then if they have concerns about the mock themselves or any individual request they can um you know they can load the request and they can go into comment mode here and they can comment on individual requests do we want to go into test world or do we we're kind of running i think we so we usually stream until half eight which just like on the dot just turn half eight yeah so we're probably not gonna go further on this uh i do want to talk about like a bit about like more advanced uh api specs even though i don't think we have time to run through them so if like would do you have some recommendation as to what people should go and look at as a an example of good like open api spec or like extensive one yeah so there's a couple of them out there i mean github is always a good place to go look for open api specs um i recommend just you know typing in open api you're going to get a lot of tooling and whatnot but one of the ways you can quickly filter is using topics and so if you do just search for open api the spec obviously comes up first open api generator redoc but you can click on specific topics that if you want to so you just click on open api and and better filter by by and look to see what comes up for that there's again you get a lot of the same uh tooling suites tooling whatnot but if you actually say well i want to if you want to filter further and you say well i want to look just for code and then you can start drilling down and say okay i want to look for just json then you start getting more into the open apis that are available and you can look through them you can sort you know by best match you know all of that but i can tell you a couple um that are interesting that you can just quickly look for is you know slack um open api on github that's a pretty quick one if you want to play around with the slack api they maintain their open api definition here and so you can get at the spec it's a pretty big one so here's the open api for that i also recommend um new york times yes i think that the newspaper would have yeah we we often underestimate i feel like the the research or the labs of uh like newspaper but they often come up with or they're often like on top of what like what's the trend or like how things should be done so that's interesting to see that they have an open api ind open yeah yeah and i mean i've been a big proponent in encouraging uh api public api providers to do this um and always encouraging more to publish them here so people can access them play with them and and use them to better understand their api another one that's super advanced and super cool is um github's open api which is really hard to actually find because um for obvious reasons i'm looking for open api and github but i actually want github's api and i'm still trying to find there we go through the blog yeah github api open api and they have just an amazing story mark's done this amazing story about telling the story behind it how people can get involved how it's using for being used for the docs there's a specific story here um and then they also talk about how they drive octo kit with it so they actually do code gen with it um and so whoops that's actually taking to the spec but i recommend looking at github's because github is a really um so you might actually find the spec to show you here it is so here's the actual github's rest api open api description and they tell a little bit about what it is but when you when you actually go in and look at it grab the latest version we look at yaml here and two megabytes yeah it's pretty pretty hefty but it's cool because they really use um refs in a really interesting way they use full full usage of refs um in in referencing operations and if you go back here and look um you know they oh no they dereferenced it oh cool so it's all just one doc now it used to be a folder set of docs man maybe that's still somewhere else but okay well um i recommend looking at github's it's so github rest api description it's a pretty advanced version [Music] cool yeah um so we have shah here i'm sorry if i don't pronounce your name correctly that is saying thank you kin this was a wonderful intro but thank you all for joining before we leave actually i'm gonna do my share of uh community shout outs because we always have people in the community like uh so i'm gonna share my screen with keen first and i'm gonna switch to my screen so everyone can see so keen can you see my screen uh yes i can in real time cool okay so uh yeah we always have people in the community that that participate um it could be you if you're interested uh if you're interested to participate we have a guest blogger program as well so if you want to write about api stuff it doesn't have to be postman just like any piece that you want to write about that is like on the tech technology wise and api-wise you can share that with us and we can publish it on our blog as well but we have allen which is one of our community champions that published that blog post 23 days ago now i don't know if we've talked about it but it's a question that comes up a lot it's uh can you use postpartum for load testing um and well the short answer is yes long answer is uh yes but it's not the tool that is designed for that uh but it's options and you you can use it and that's one of the one of the blog that leads you through that so that's one of the things i wanted to talk about um then the other thing i wanted to show is joyce created the meme during the stream which i thought was pretty funny i just wanted to share that with everyone that hadn't seen it before i like it i like it so yeah i think uh i think we can finish on this that's a very good uh good good meme quality and that's a good end to the stream so thank you all for uh sticking along uh hope you love you've learned some stuff otherwise it's always good to talk with you all thank you kin for uh being here and sharing your knowledge as always as well thank you for having me this was it was good to be on this side of the table uh finally so thanks for making the the this live stream happen keeping it going you and joyce are are awesome for that and thanks for having me thank you all right bye bye everyone and see you next week bye [Music] you

Channel: Postman

Views: 8,574

Rating: 4.9745221 out of 5

Keywords: software development, API, Kin Lane, OpenAPI

Id: V2PWRA6q3jE

Length: 97min 27sec (5847 seconds)

Published: Mon Aug 31 2020