API Fest 2022 | Workshop by Kin Lane on Designing API Schemas

All right. Excellent. Thank you so much for having me here today. It’s good to see everyone, and I look forward to questions from you, and feel free to just ask in the chat. I will try to pay attention to the chat and share some good information. So, first off, who am I? I’m Kin Lane. I’m Chief Evangelist at Postman. So what does a Chief Evangelist do? Well, I run our developer relations program as well as our open source technologies program. So, dealing with open source tools, anything to do with APIs. And I tend to do a lot of talks to people, to folks like you who are students, different companies, different conferences, and try to share my knowledge and what I know about the space.

So let me go ahead and dive in. I’ll share my screen here. You should be able to see my Postman desktop now. I’m going to walk you through how to design — an API design-first approach to delivering an API — walk you through the details of how you can use a schema to design your API, and document it, mock it, and add some things to it, make it your own API, and work with it on your team. But before I start doing that, I really feel, especially for folks who are just getting started out, it’s really important to understand what APIs are and why they matter. And so this is something I’ve been doing — I started being an evangelist in 2010, so I’ve been doing this for 12 years — and it’s really an important part of my work to help people understand why APIs exist first off, and then why they matter and why they’re important, and anyone, not just developers, because I think they’re an important part of our world. And so before I show you how you can create an API, which is something everybody should learn to do — again, even if you’re not a developer — let’s start with just a simple walkthrough of why APIs matter in the first place, because I think this really helps set the stage for why you should be thinking about APIs.

So first off, APIs are touching every aspect of our lives in 2022, and this isn’t an exaggeration. They’re part of everything we do — our health care, our education, our work, our televisions, our home lives. They’re everywhere. So it’s really important to understand how they work, and you just end up having an edge in your career, in your job, when you understand that APIs exist and that you can put them to work. So I always want to start at the basics. I don’t want to assume anyone knows what an API is, and even for those of you who know what an API is, sometimes it helps to get a little refresher.

So APIs power most all the websites that we visit and look at and work with. This hasn’t always been true. Websites are often driven from databases, but increasingly over the last 20 years a lot of that content that you’re reading, the media, are actually published by APIs. So if you’ve ever watched a YouTube video on another website, that’s an API. If you’ve ever bought Amazon products or anything like that from a seller or shop or a store, that’s done through APIs. So a lot of websites are powered using APIs these days. Next, APIs power mobile applications. So whether you have iPhone, Android, or other mobile device, those applications on there all are using APIs to send data back and forth to the cloud. And so starting in 2007, 2008, APIs started powering all of the mobile applications we use and depend on. And they’re part of our everyday lives because of those mobile devices. And then APIs are being used to power devices. Automobiles, signs, streetlights, our homes, our televisions, our thermostats — all of these devices are using APIs to send data back and forth and do what they do. So APIs are powering not just things on the websites and mobile applications. It’s actually everyday objects and devices that we interact with.

Now, Postman — what does Postman do? Well, Postman powers APIs. This is how you understand what APIs are doing. This is how you troubleshoot them. This is how you see them. So Postman is how you find the APIs behind the websites, behind the mobile applications, behind the devices. And as you’ll see today, if you have the ability to not just see and play with and work with an API, if you have the knowledge on how to create an API, then that sets you into a whole new class of builder that understands how APIs work, and you can build web applications, mobile applications, device applications, and other integrations. So Postman is the heart of this. This is what 18 million developers are using Postman for.

So, why do APIs matter? As I said, everything in our personal life is being powered by APIs. APIs are powering everything in our professional lives. Our jobs depend on this. And I’ll walk you through just a handful of applications that are the top websites and applications that we use in our personal and professional lives, just to show how important it is if you know these APIs exist. So, spreadsheets, PowerPoint, Outlook — all of these Office 365 applications have APIs behind them. So if you know how to use the APIs and automate and build things with these APIs, you’re going to be ahead in your work. Where you work is going to want to keep you because you’re going to know how to integrate and automate and do things with those APIs. Microsoft Teams — you can communicate using the Microsoft Teams APIs. You can manage meetings and discussions, the data behind it. There’s a lot of things that you can do with the Microsoft Teams API. Similar to Office 365, all of Google Apps — Gmail, Google Calendar — all of these have APIs behind them. So Google Sheets — you can store data in Google Sheets, and you can get access to it through an API, and you can build applications using that data. It’s a very cheap way to make APIs.

Twitter — Twitter has APIs. It’s one of my favorite APIs out there. There’s so much that you can do. Whatever you’re interested in, you can study, you can research — science, politics, culture, movies — it’s all on Twitter. And their API is one of the more robust, easiest to access, and you can build real global-scale applications on it. Similarly, Facebook, or Meta — Meta has APIs as well. They have the Facebook Graph API, and you can do quite a bit with it. And they also have Instagram. So the Instagram API is part of the Facebook suite of APIs. I do not have the chat open — there we are. It closed on me, so I’m going to open it back up so I can see it, because I wasn’t looking at your messages. So, again, Zoom APIs — communication, similar to Microsoft Teams. You can manage your meetings. You can do quite a bit with the Zoom API. You can see who’s been on calls, what was shown, files that were used. There’s a lot of interesting ones. WordPress — WordPress powers around 50% of the websites. I think it’s even higher when you talk about the top websites. So all of those websites have APIs behind them, because you can use the WordPress API. GitHub — if you’re going to be programming code, if you’re going to be building APIs, doing anything technical, you’re going to be playing around GitHub. And automating and integrating with the REST API or the GraphQL API is a pretty important part of what you’re going to be doing. YouTube — I mentioned the YouTube widget. There’s a lot of functionality that you can tap into with YouTube as far as searching for videos, embedding videos, managing them, and you can automate all of that through an API. Amazon — you can buy any products. This isn’t even touching on Amazon Web Services. Amazon is one of the companies that has changed how we think about the world using APIs. So it’s a really interesting place to study and explore when you’re working with APIs. And then again, a very rich source of information similar to Twitter, one of my favorite APIs, the Reddit API. So you can do quite a bit — build different applications, do different types of reporting, visualizations — really interesting things you can do with the Reddit API.

So I could go on and on and on, but really, it’s an API-first world. APIs are behind everything — every big movement in technology of the last 20 years, from e-commerce to the cloud to maps to delivery services to mobile phones, mobile devices, connected devices. It’s all being powered with APIs. So if you’re aware of these APIs, if you can see and work with and play with these APIs, and more importantly, if you can build these APIs, you’re going to find that you’re going to do fine in this world and you’re going to be able to get ahead and understand what’s happening. You’re going to have the job skills that people want when it comes to hiring. And whether you’re a developer or not a developer, there’s a lot of ways as a business person you can use APIs to integrate, move data around, sync between systems, and make a lot of different things happen. So hopefully that gives you a look at what APIs are, why they matter, and kind of the scope. I mean, that’s just touching on it. Really, there’s a lot more depending on what your interests are, who you are. There’s a lot of different things you can do when it comes to APIs. If you’re interested in music, there’s the Spotify APIs. If you’re interested in the environment, there’s environmental APIs. If you’re interested in medicine, there’s health care APIs. So I can’t emphasize enough how important it is for you to be API aware, and be able to not just consume APIs, but also produce APIs.

So let’s dive in. Let’s actually look at how you can design an API for a very simple use case. And I’m not actually going to program it — you’ll do that tomorrow. I’m going to walk you through how to design it in an API-first way so that you can actually see it, play with it, work on it with your team, and understand how to get started with your API project. Now, we’re going to do a specific one — we’re going to do a restaurant API here. It’s very simple, but you can do this with anything. You can do it with any type of digital resource that you can dream up. It’s pretty unlimited.

So, while I’ve prepared for this, I always like starting from scratch. I’m in my Postman desktop here, so I’m logged in. Same Postman everyone has — it’s nothing special or different. We’re actually in my personal account called API Evangelist. It’s a blog that I have. I prefer to do demos here because I can set up as many different workspaces, and it’s just easier to create different things here. So I’m going to create a workspace. Everything with an API starts with a workspace. You want to create just a place that you can do the work and be able to find it later, and you know all your work is there. It’s like having a little workspace, like a little workshop, where you do things in, and when you come back, you know all your tools and all your information are going to be there.

So let’s go ahead and create a new workspace. And I’m going to be live coding, so hopefully the live coding gods are on my side and things are fast and doing what I need them to do. Come on. There we are. So we’re going to call this API Fest Restaurants and give it a description so everyone knows what it does and what it’s about. You don’t have to write a book here, but you should at least describe this for your teammates so they understand what it is. This is a workshop workspace for API Fest. I’m always tempted to call it REST Fest. There’s another conference that’s gone on for the last decade called REST Fest, and so I’m always a little tempted to say REST Fest. All right. I’m going to go ahead and make it a public API because I don’t mind doing my work out in the open. So I’m going to create this as a public API, but I could do it as a team or a personal one if I wanted. But I’m going to go ahead and create this new workspace. Hopefully it creates nice and quick. So I’m looking at the questions a little bit here in the chat while it’s building. So, how do APIs power hardware devices? Man, that’s a lengthy discussion. We’ll touch on that in a little bit.

So let’s give this an overview. Here’s the landing page of my workspace. It says it’s a workshop, but we want to give it a little bit more description about what this is. This will have our OpenAPI definition, documentation, and mock server for our restaurant API. And I can change this at any time. I just want to make sure it’s got a little more detail than the summary, because this shows up when people search for it and when team members land on it. So you want to keep updating your overview and use this to communicate with whoever’s going to be visiting, looking at your site — team members and other contributors.

So now let’s create an API. Let’s just dive in. So in Postman here, you’ve got your main toolbar where you have collections, which we’ll show you in a bit. You have APIs, you have environments, mock servers, monitors — Flows is pretty exciting, but we’re not going to talk about that today — and then you have the history of whatever API calls you made. We’re going to dive into APIs. So we don’t have an API yet. Let’s go ahead and create an API. I’m going to call this my restaurant API. I’m going to call it version one. And I’m going to use what’s called OpenAPI 3.0. So OpenAPI is an API specification that allows us to describe our APIs. That’s a whole other workshop, whole other class, but just know it’s what you want to use to describe your APIs. And you should spend time learning more about OpenAPI if you can ever get the chance, because it’s a very important part of your career if you’re going to be building APIs or consuming APIs. We’re going to choose YAML because it’s a little easier to read, but you could choose JSON. I like YAML because it’s just easier to edit, easier to read. I’m going to go ahead and hit the create button. And then it said it created it. It’s got a draft. And I’m going to close this.

So now we should have our API. We’ve got our restaurant API here, version one. And you have an overview of this API just generally, what’s going on with it. We don’t have much going on right now. We’ll look again at this in a little bit. The second tab is our definition. This is like a config file, or this is the outline of our API. So this is an OpenAPI 3 file, and it describes the surface area of our API. And when you create a new API in Postman, you get some parts and pieces here. We’re going to clean this up and walk through it. But the first thing you get is a little bit of information, and I’m going to zoom in because this is always hard to read, I know. See if I can zoom in here. Let’s do one more time. There we go. That’s maybe too big, but let’s adjust our screen a little bit, make it easier. You can close this. So we can go like that to give us a little bit more room, or we can leave it open. I’m not really going to be needing it, so I’m going to close it, and I can always get back to it. So it gives you a little bit more real estate to work with when you’re designing your API.

So I’m not going to go through every detail of OpenAPI. You know, we’ve only got a certain amount of time. But what I’ll do is try to share what I’m doing as I’m going down this, and then hopefully you can follow along, and you’re welcome to use this workspace. It’s publicly available, so I’ll share the URL, and you’re welcome to grab the work and reverse engineer what I’ve built here today. So we’ve got our information for our API. We’ve already filled this out. We’ve called it our restaurant API — that’s the title. It’s got a version one that we gave it. Now, the servers just says localhost. We’re not going to worry about the servers right now, because we’re just mocking it, so we’re not too worried about it.

Now, the next part is describing the paths. So say our server here was api — I’ll just use example.com. Now, whatever comes after this, this is the path. So just like it would in a URL for a website — and we have postman.com/apievangelist up here — that’s how APIs work as well. So this path right here, we’re going to call this restaurant. Because when people type in our API, we want to be nice and readable, and make it so you know what the resource is. It’s easy to understand. So it would be api.example.com/restaurant. And that returns a list of restaurants, is what we’re going to do for this demo, and make it so that you can build applications around this. So I’m going to give this a summary. This is just going to give us a list of restaurants, and you’ll see all this work in a little bit.

I see some other questions up there. So, yes, this will all be recorded. I’ll walk through the version stuff in OpenAPI again in a little bit, give you a little more detail, but let’s go ahead and just scoot through this. Now, what I’m doing here is, this is my path to my restaurant. I have what’s called an HTTP method here. So most every API call or web call you’re making is called a get. Every time you call a website up here, you’re making a get call. And this is an HTTP method that allows us to return data, make a request for a list of restaurants, and get those restaurants back. Here we gave it our summary. Now it’s asking for an operation ID. I’m going to call this list restaurants. And then you can tag this, so we’ll call this restaurants. And then you can choose to add any parameters for this. We’re not going to have any parameters, so we’re just going to clean this up. It’ll make it a little bit simpler, easier to read.

Now, when this API call is made, we can return different responses. And we’ve got a response of a 200 here. And we’re going to describe this as, again, a list of restaurants. Now, we’ve got a section here for headers. We’re not going to need any headers right now, so I’m going to clean that up. It comes default with Postman. All we’re going to return is some content that’s application JSON, and it has a schema. And we’re going to describe what that schema looks like. It’s going to be called restaurants. And again, there’s a lot of detail going on in here. This is all OpenAPI. You won’t fully understand it for a while. It’ll take time. But it helps if you have one you can reverse engineer. So when we’re done here, you’ll be able to come to this workspace. Claire tomorrow will have a copy of this. So don’t worry about every little detail here. It comes with time. I’m able to edit it directly because I have a lot of experience doing this.

So now this is what’s going to be returned as my response when someone calls this API. It’s going to return a 200 status code, which means success — everything’s okay — and we’re returning this content. Now, I don’t need this default one either. I’m going to get rid of this. This is extra. So what we have here is a basic API call. We have an API that describes what it does, and we have one path. I want to get restaurants. That’s all I want to get. I just want a list of restaurants.

The components section here allows us to have schemas. And I’m going to clean up what’s here, because we really don’t want most of this. Actually, I’m going to keep a little bit of it here because it makes it easier to type. So this is a restaurant. I’m going to call that — this is the plural. I’m wanting restaurants. This is a restaurant. It’s an object. And we’re going to use an ID. I can’t get this over there properly — I want the type to be a string. I don’t want my IDs to be integers, so I’m just going to make it a string, and I’m going to give this a description. This is the unique identifier for the restaurant. Every restaurant’s got to have one. And then I’m going to have a property called name. It’s a string also. And I’m going to want a description that is name of the restaurant. Yeah, I can type. All right.

So basically now we have an object that we can return with this, but we don’t want just one restaurant. We want a list of restaurants. And so what that takes is we need a second schema. And again, I’m going pretty fast here, just to get through the workshop. You can reverse engineer this. You can learn from it once it’s in use. So I’m going to just grab this here, because this keeps me from making typo mistakes. So I’m going to call this — this is an array. This isn’t an object. And again, I’ll show you how all this works in a little bit. And then what we’re going to do is we’re going to do items, and we’re going to call this — sometimes the YAML tabbing leaves a little bit to be desired here. What am I doing here? I’m doing ref. I never remember this. I’m typing this from over here, because I have a cheat sheet off screen. And so, there we go. Our error went away. You see how it had the error until I got it right? It’s helping correct me. So what am I doing here? I know it’s hard to follow and see. Again, you’ll want to reverse engineer this and spend time with it, learning how the mechanics work. And then it helps to see it working, which we’re going to do in just a second. So now I’m calling this restaurants. So all this is doing is saying, when this returns, please return components, which is right here, schemas, which is right here, restaurants, which is right there. And then all this does is say it’s going to return an array of items that is components, schemas, restaurant, and it’s going to return this object.

All right. Let’s start with that. We have zero errors. Always check to make sure you’re valid. We have zero warnings. It means our OpenAPI is valid here. It is correct. And so we can hit save. So now we have an API definition. We don’t have an API, but we can mock this API, and we can do a lot of different things with this API. So this OpenAPI definition describes what we want. We want a restaurant API that allows us to get a list of restaurants. Very simple.

Now, up here there’s a button called generate collection. This is where we can do a lot of different things with this OpenAPI definition, and it shows you the magic of having an OpenAPI, because I can test the API, I can monitor it — but it doesn’t exist yet, so we can’t do those things. We can document it, and we can mock it. So what we’re going to do is we’re going to choose to mock it, and I’m going to call this our restaurant API. So what this does is it will create a collection. I’m going to leave it open to the public. Now, if I go back over here to my toolbar, click on collections, you’ll see there’s an API here. Here’s our API, but we also have a collection called get list of restaurants. Now, we have a base URL, which says api.example.com — remember that it grabbed our server — and then we have our path, which is restaurant. Now, I should have had it set my base URL to be the mock server, and I didn’t. I apologize. I made a mistake there. So what I’m going to do, if this helps you learn — because we all make mistakes along the way — is, when we generated this collection, it also created a mock server. So we go under here to mock servers, click on restaurant API, and then you hit copy URL. So this is pretty hard for you to just follow along and be doing things. So I hope you’re trying, and I’m sure you’re jumping around trying to figure out what steps to go to next. But try and watch what’s happening, because you’ll learn from it, and then when you’re able to play with it on your own, it’ll make a lot more sense. And then when Claire takes it and walks you through generating code, it’ll make even more sense.

So we’re back to our OpenAPI here. We’re looking at the definition of the API. And I’ve generated a collection. I’ve generated a mock server. How do all these work together? So our OpenAPI is what’s considered the source of truth. This is what our API does. Our collection is what’s mocking that. It’s generated this collection, and it’s using this mock server. So what I’m going to do here is click on this collection. And again, there’s quite a bit going on in this screen. Unless you know Postman, there’s a lot of different things you can do here. But what we’re going to do is click on this collection, and we’re just going to click on variables. And what variables gives you is, here’s that base URL. When we generated this collection, it put in api.example.com. I’m going to paste in my mock URL. And I’m going to hit save. Now I’m going to close my OpenAPI, and I’m going to just click on my collection here. And base URL is now my mock server, and my path is restaurant. Let’s hit send.

So if you look, we have two records returned. Now, it’s Latin. It doesn’t make any sense. But we have an API. We have a mock API. So this response is being mocked by this server. But this mock server, all it’s doing is pulling this list of examples right here that was generated from that schema we created. Remember back here? Let me go back to the API. I do a lot of jumping around, but you’ll find you’ll do a lot of jumping around when you’re in Postman, and you get kind of used to it, but it takes time, and I know it’s hard to follow. But here’s back that API we created. When we go back down here, here’s the fields that we asked for. This is where it generated the ID and the name. This is how it knew what to do here. And this is how it knew to create an array.

Now, if we go back to our collection, back to our example, we can change the name. So say we want our ID to be ABC123, ABC234. And say we wanted our restaurant to be — ooh, I’m going to go something global, something everyone’s familiar with. And what’s another one that we can do? We’ll just stick with chains, because people tend to relate to chains. And what I’m going to hit is save, and we’re getting a 200 OK. So api.example doesn’t exist. So, yeah — back in your API, if I had grabbed my mock server — I’m going back to my mock server, copy URL, I go back to my API — you can put this in your definition. So you can have different servers. You can have more than one server. So we can put our mock in there as well as our example one. Or we could remove the example one and just put the mock in here. But we didn’t know this before we generated it. It generated the mock server for us. So now we put it back into our definition, and we’re able to use it.

So back to the example. If I click on this now and hit send — I’m back here at the collection, my list of restaurants, and I hit send — what do I got? I got ABC123, McDonald’s. So now I can give anybody this collection on my team. This collection right here — I can share it. So you can share it with people. You can embed it in documentation using a button, or you can just grab a link and copy it and send someone this link to this collection. And then they can come here, and they can use this mock server. They can fork it. And they can run it, and it’ll work like this. And if you have control over the API, if you’re part of this team and you’re part of this workspace, you’re also able to edit this. If you’re not part of the workspace and this isn’t a public workspace like it is, all you can do is fork it. But we just created an API. We created the OpenAPI definition, and then I generated a mock server, and then we have a collection here where we can run that API.

Now, if we want to make changes, say we want to add another restaurant. And it’ll be ABC567. And it’s getting late at night — my brain’s not working for restaurants. What’s a good restaurant everyone’s going to know globally? Hmm. It’s a restaurant — Subway. Thank you. Thank you. So we got Subway. Oh, KFC. Yeah, could use KFC too. So now I go back to — this is just my example. Closing my example, I go back to the list of restaurants, I hit send. Now I’ve got three restaurants in there. So now you can make your API do things. You can add data to it. You can share that URL.

And over here, one of these icons — always explore in Postman. There’s all these little icons. Like I tell you, we add so many features so fast, I can’t always keep up with it. So always explore. Here’s the documentation for this. So you click right here, you get documentation. You want to view the complete documentation. You can add a description. This pulls a list of APIs — or a list of restaurants. We’ll just call it that for now. And it’s got all the details. It’s got curl examples. You’ve got different code libraries. You’ve got PHP. You’ve got Node.js. You’ve got an API here, all at this mock server.

And now if we want to change this — say we wanted to go back to our collection here, go back to our example. Say I wanted to add a field. Say I wanted to add something — let’s add cuisine. So what kind of cuisine is this? Ooh — was it a burger joint? Now let’s add this property to all three. So I’m going to call this — whoops, I didn’t actually call it cuisine, did I? Well, it’s late at night, you’ll have to forgive me. Cuisine, cuisine. What do they have here? They’re coffee. What do they have here? Sandwiches. So now we just hit save. We go back to our collection. We make a call. We’ve added a property to it. But we’re out of sync with our API, because we didn’t add that field here to our source of truth.

Now, one way you can fix this — oh, I didn’t link my documentation. How weird. This is how I discover weird things. So what I’m going to do is link my OpenAPI here. It should have linked it, because I generated it. But I guess I had it as a mock server, huh? I didn’t actually generate it as documentation. Where do you have mock servers anymore? Now I look silly, huh? There’s no mock servers anymore, or maybe I’m just not seeing it. Anyways, what I’m going to do is link my documentation up. If I had done this properly, if I had generated the documentation first instead of the mock server, this would have been easier. So what do I have here? I now have my OpenAPI. I have my documentation. I want to validate this against the definition. Man, I’m really looking bad. It didn’t find any issues, and I know there’s issues, because there’s no property down here. All we have is ID and name. Hmm. Interesting. Yeah, I don’t know why that’s not doing that. That seems like a bug to me, but it could be — it could be late at night. So I’m going to add cuisine here. You have to have cuisine. Man, excuse me, I’m not typing very well. Let me get some more room here. So I’m going to add a property. I’m not seeing what I’m doing. I’m going to add cuisine. Postman’s supposed to catch stuff like this for you. So occasionally you’ll hit bugs like this, or maybe I’m doing something wrong that I don’t know. The cuisine being offered — we’re going to document this. So now we have three properties — ID, name, and cuisine — that are all required. And I’m going to hit save. Now I’m going to close this. I’m going to go back to my collection and make a request. Yeah, it’s not doing validation for me. That’s interesting.

Anyways, hopefully you get the point here. There’s the ability to create your API using OpenAPI. You can make calls to it. You can change it using your examples. You can add records if you want data to show up in your application. You can add properties to it. You have a mock server right here that logs every call made to it, so it sees every call that’s made to it. So you basically have an API. You can continue to make changes to it. If you have questions for your friends, you can come back here to your API. You can click here to your comments. You can talk to your friends. You can even go in — say you want to switch to comment mode. Sometimes the interface gets me. When you’re working on your API, you can say, I really want to know — come on. Man, the Postman live coding gods are not looking favorable on me. Okay, we’re going to try this again. Go into comment mode. Try leaving it inline. Leave a comment on a specific part. I’m doing that, and it’s not letting me comment. Hmm. Well, I’m going to back out slowly of this one and go to the next feature, because that’s silly. I’m guessing I need to refresh my screen or something. Or again, it’s just late for me and I’m making mistakes, but you should be able to comment on any property here when you’re in comment mode. You should be able to highlight anything — and see, I get the little content bubble, but I’m not actually getting my content. And it could be this — it could be that I need to zoom out. I’ve had this problem too. The windows don’t work. But anyways, I’m going to move on, because it’s not commenting, and it’s not making me happy. Is it working for you? Okay. Well, pretty common — I mean, for me — hitting a bug and not being able to figure it out. I guess if I refresh my screen — maybe I’ve had my browser open too long.

Regardless, the next thing we want to do for this is — now we can get a list of restaurants. We want to actually mock other capabilities of this API. So what we’re going to do is add the ability to add a record. So we want to be able to add a record to this and be able to mimic — it’s not actually doing it, but we’re going to mimic it having the ability to add a new record for this. So what we’re going to do is add not a new path — we’re going to add a new HTTP method. And we’re going to just copy this one here, and we’re going to paste it, and I’m going to change this to be a post. So what we’re doing here is, here we’re getting a list, and here we’re posting, so we’re going to add a restaurant. And I’m going to change my operation ID to be add restaurant. And this is still tagged restaurants. We still want a response, but we want this response to be, rather than 200, it’s going to be a 201, because this is the proper status code when you’ve added something. And then we’re going to change this again to add restaurant. And then we’re going to want to return not a list of restaurants, just the restaurant we added. So this is just a restaurant. So now we should be able to hit save, and we should be able to come here to our documentation, click on validate — and it found issues this time. Thank you, Postman. So now what’s happening is, we would need to review our issues, and it recognizes that I added a method. I added a post method, and what we can do is add this to the collection. So rather than generating it all again, I’m going to just hit confirm changes, and I’m going to view the updated collection.

So now we’re back at the collection. Now we’ve got two methods. We’ve got a list restaurants and we’ve got an add restaurants. And we should be able to make a call to our add restaurants, and we get one restaurant back. Now, if we want to edit this restaurant — say the restaurant is ABC8910, and the name is — what was that one? We did KFC. And then the cuisine is — is it just chicken these days, or is there more? And so we save our example. Now we hit our API call again. Here’s our single record, mimicking that we added it. Now, we don’t have a body. So we need to go back to our OpenAPI, go back to our definition, and we need to add in here the details of a request body. Because what this is going to do is allow us to submit that record that we’re adding — that we’re going to do when this is a live API. Required. I need a description. This is the restaurant to add. What do we want here? We want basically a restaurant object. It’s basically this guy here. So we want, rather than typing — boom. Now we’ve got a body and we’ve got no errors. So what this is saying is, when we add this, you must have a request body. It’s required. And it should be application JSON, and it should match our restaurant object. So I’m going to hit save. Go back to our docs. I’m going to validate again. I’m going to review my issues. And it didn’t build. Why do you do this to me? Let me look here. It didn’t give me my body. Hmm. So what this would have done is add this here. It would have just went, this is your body. So now we’ve got the ability — I’m going to close all my tabs here — I’ve got the ability to list restaurants, and I’ve got the ability to add a restaurant.

So, we are running a bit late. So should I wrap it up here pretty quick? I’ve got just like five minutes left, and then I’ll wrap it.

No, no. I guess you can actually go ahead, you know, and convey whatever you want to convey. I guess that is fine.

Yeah. Okay. I’m almost done.

Yeah, because students would want to kind of get completely everything out of the workshop, right? Because that is their starting point. So, like, you know, everything.

Yeah. We’re almost there. So I’ll breeze through this. I’m going to go back to my API. And I want to be able to not just list restaurants and add them. I want to be able to get a single restaurant. I want to be able to update the restaurants, and I want to be able to delete restaurants. This is called CRUD, or create, read, update, and delete. And every resource that you have, you want to be able to do all of these things. But to be able to do those ones, we’re going to need a new path. So I’m going to create a new path here, and you’re going to see me rapidly doing this, because we’ve got a shorter amount of time. So I’m going to add a new path, but what I’m going to do is, we want to be able to pass in it the ID of our restaurant. Rather than just get all restaurants, we’re going to get just the ID. So this is not a list of restaurants — this is a single — and then the operation is get restaurant. And then it should just return a single restaurant, and we should be good. So why — what does — the operation does not — the ID — oh, we need a parameter in here. So I’m going to bring back my parameter that I got rid of before. One second. So now we’ve got our ID, the unique ID. We’ve got the name, it’s in the path, description. So that gives me what I need here.

Now, I’m going to be even quicker here. I want a put object. So I’m going to grab this post up here, which is pretty close to my put. I’m going to add it right here. So I’m going to say this is my put, because put is how you update things using HTTP methods. We’re going to update our restaurant. Update restaurants. And the body it’s sending is a restaurant, and the response it gets back is a restaurant. But we want a 200 status code, I believe. No — actually, let me look. Correction — we want a 204. You’ll see all this work in a second. We’re just moving really fast here, so bear with me. So we don’t want any response for our put. And then we want to quickly take our put — wait, we got an error. Let’s figure out what we need. What’s missing? The operation does not define the parameter ID. So it does not have the parameter. So we need this parameter right here. So we need to add this property, and then our error should go away. Yay!

Now, we’re going to need a delete, which is pretty close. So we’re going to grab this. We’re going to paste it. We’re going to call this delete. And we’re going to add delete. So this is all very puzzly, formal-like. I still need the parameter. I don’t need the request body for my delete. And you’ll be able to tear this apart in just a little bit. You should be able to access this — I’ll share the link here. We’re going to call this delete restaurant. So I hit save. I don’t have any errors. I’m going to go to my documentation. I’m going to validate again. It found some issues. I’m going to review those issues. It’s got a couple things that it wants to do here. So what I’m going to do is select all those changes. I’m going to confirm. And now, if you look at my collections here, I should have a list restaurants, an add, a get a single restaurant, an update restaurant, and a delete restaurant. Now, it looks like I did something wrong, because I don’t have examples for my single restaurant. And I don’t have an example for my update restaurant. And I shouldn’t have one for my — no, delete, I should have one.

All right. Now I should be able to make calls to these. Let’s see what it does. And this is where you see the errors that we make. Oh, it didn’t like that one. It didn’t like ID, because I didn’t put in a value for ID. Let’s try update. Didn’t like it, because I didn’t put in a value for the ID. All right, let’s look at what happened here. So I’m guessing we need an example. Add an example. Add an example. And I’m bungling some of this. You’re probably wondering, like, what’s going on? But what’s going to happen here is, I’m going to figure it all out and pull it together, and it’s going to work for you. And then what you’re going to do is reverse engineer this, and it’s going to make a lot more sense. So I’ve got five API calls here. I’ve got five examples. Now, let’s look at my post. Do I get my record back? Yes. Let’s look at my get. Do I get a record back? No, because I still don’t have my ID. Why don’t I have my ID?

All right, you know what I’m going to do in the essence of time? Because I know I made a mistake somewhere on my thing, I’m going to grab the complete OpenAPI. I’m going to go over here, because off screen I’ve got a little cheat sheet, my little OpenAPI. I’m going to paste it in here. And I’m going to go to my documentation. I’m going to revalidate. Let’s review those issues. Update. Let’s see what it does. I don’t like what it did. Here’s what we’re going to do, just so you can reverse engineer this properly. Man, I apologize, you guys. What I’m going to do is delete my collection. My collection is gone. And you might find yourself doing these things. That’s why we’re mocking it. We’re going to generate the collection again. I’m going to generate it as documentation this time. Whoops. I’m going to generate mock. Where are we at? So — you got yours working, and I don’t even have mine working. That seems unfair. So I just made some mistakes somewhere. It’s always easy to recover, though. It’s always easy to get these working. I don’t want this mock server. Got my collection. Look at that — I’ve got examples. It’s got it neatly in a folder. Much better. Let’s see if these things actually work. Let’s go make a call. Oh, we don’t have our mock server. See, we have api.example. So I’m going to go get my mock server. This one’s deactivated. Why is that? I like that it says that it’s deactivated now. That’s a good feature. I’m going to delete this mock, because I accidentally deleted the wrong mock. I’m going to grab this. I’m going to mock it again. There’s like so many ways you can get at what you’re trying to do in here, and I know it’s probably confusing to watch me jump around, but you’ll find yourself doing these quite often. I’m going to go grab this. And this is how you get familiar with Postman. You get really quick at doing things. You get really quick at recovering from things.

You can come back — you’ve got an API. You’ve got a post request. There’s my post request. You’ve got a get request. Ooh, that one didn’t work. Why didn’t that work? Because our ID — I don’t know why it doesn’t like our ID like that. Okay, let’s try our put. I’m going to move on. It doesn’t like the put either. So it’s not going to like any of these with the ID. Claire, that ID is randomly generated — probably doesn’t match items. Oh, there they are. It’s the same ID. So it should just match there, right? I’m guessing there’s some other detail in here. Yeah, I’m guessing that’s it. Not URL encoded. There we are. That was it. Thank you, guys. That’s how you recover from all this. You know, you’re going to make mistakes, even when you’re experienced. But really, it comes down to being confident with OpenAPI eventually, being confident with Postman. Now I’ll get all my IDs cleaned up here. Restaurants works. And never feel — I mean, I’ve been doing APIs for a long time, and I use Postman. Look, we even have our empty response. The put should be empty. Delete should be empty. Our get single one should return a single record.

So we have an API, despite all my bumbling and fumbling around. Now we have our API here with our single source of truth, our OpenAPI. We have a mock server that is generated from that, that is in sync with it, because I had to keep it in sync to make it work. We have a collection that we can then make calls to — get a list of restaurants, add a restaurant, get a single restaurant, update a restaurant, and delete a restaurant. So I agree, it is overwhelming, because I kind of bumbled my way through it. And even if I’m slow and I walk through it and you’re not familiar with Postman, it takes time, because there’s a lot you can do here in Postman and there’s a lot you need to work with. And it just takes time — it’s OpenAPI, Postman, all of these concepts. It helps to play with it. So now, the beauty of this — because I’m not an engineer, I’m not a programmer who does things in a straightforward way — is you guys all can reverse engineer this. So if you need to get yours working, you can come to this public workspace, and you can fork my collection, you can look at the OpenAPI, and you can play with it and reverse engineer it. And you’ll make mistakes. You’ll bumble it. And you can just keep trying to do things, and you’ll fix it, and you’ll figure it out.

So, sorry — thank you for bearing with me. It’s 10:00 p.m. at night now here, so that was pretty funny. But thanks for letting me spend a little bit more time in and getting it to work. And thanks for your help. You guys made it so I could pull it together. Have a good rest of the API Fest. Thank you for having me.