How are REST APIs and OpenAPI related? ... and why should you use OpenAPI when working with REST APIs or services? Hi, I'm Nathan Hekman from IBM Cloud, and I'm going to answer that for you today. But before I do, please hit that subscribe button. Let's jump in with an example. Let's say you're a developer for an ice cream shop and you've just created a Web application that allows employees to manage the flavors of ice cream that are in stock. This Web app communicates with a cloud based server that communicates via a REST API. So, let's say that the ice cream company hires a brand new developer, Mark, to get started developing and maintaining this application. So, here's Mark over here, and Mark is real excited to go ahead and get started and become productive, but he doesn't understand the REST API in the service and what it does, and he doesn't really want to go through line by line, digging into the service and API code. So, how can he understand: what does this REST API do? Well, he can reference what's called an OpenAPI definition and quickly understand what exactly this REST API does. So, he's off and is ready to get productive. Great! So, let's step back a bit and talk about: what is OpenAPI? Why should you care about it? I think we can get started by first talking about the OpenAPI specification. So, what's the OpenAPI specification? Well it's a specification, right, it defines, it defines how to describe a REST API interface. So, it's a specification that outlines how to describe a REST API interface. So, how do you describe a REST API interface? Well, like we said over here, like Mark referenced - he used an open API definition. So, an OpenAPI definition, what is that? So it's actually a file. It's typically YAML or JSON. And, like we said before, it describes what an API or service can do. So, that's what Mark, over here, referenced to understand what this API can do, what can the service do. So, it outlines exactly that. Great, so, let's talk about some of the benefits. Like we said, why should we care about OpenAPI? So, first of all, it's a standardized format. So, a standardized format for describing your REST API. And it's readable by humans or machines, so Mark, or whoever, could look at this OpenAPI definition and understand what the REST API does. Or the OpenAPI definition can be fed into some DevOps or automated process using some tooling for testing and some other neat things that we'll talk about a minute. So, with an OpenAPI definition, you can describe a few things, right? So, first of all, you can describe the REST API's resources, which includes properties or data types. You can describe endpoints, operations, parameters, and the REST API's authentication or authorization. Great. So, a second benefit is guidance, right? It's all about guidance. So, it allows somebody referencing this OpenAPI definition to understand ... to understand, or actually use, the service or REST API. So, it makes it crystal clear exactly what it does. And then, third, OpenAPI allows you to extend your REST API with tooling. So, there's some pretty neat tooling available that can take an OpenAPI definition as an input and produce some pretty neat things. So, one example is there's an API validator that will actually take in an OpenAPI definition and run through some validations to ensure that the REST API actually conforms to a certain set of industry standards. Because not all APIs are made equal. There is also ... there's an API doc generator, which will take in that OpenAPI definition and generate REST API documentation or reference that's interactive and it describes very clearly what exactly this REST API does. Another example of tooling is an SDK generator, which will, once again, take in the OpenAPI definition and the output will be client libraries in the programming language of your choice, or SDKs, so you can actually consume that REST API. Great. So, that kind of outlines what OpenAPI is, and what some of the benefits are, and how OpenAPI is used with REST APIs. So, let's talk about ... back to our example. So, Mark, over here, when he's looking at this OpenAPI definition, we'll say that this is called "icecream.yaml" Right? And let's take a look at maybe an example of what this ... part of this file might look like. OK? So, the beginning: you have some basic REST API info, right? So, you might have a version of OpenAPI that's being used, some version of this REST API itself, maybe a description. All that can go towards the top of this file. Next, you might have a section to describe ... so you're actually describing the REST API request, so "API request". Right? So, in this case, we're looking at the operation "list flavors", so you see a path there of the "/flavors", you see the "Get HTTP" method that's outlined there for exactly how you form your request. And then the next section of the OpenAPI definition might be a place to describe the API response. Right? So, describing the REST API response, you see the 200 response might have these properties here like "flavor", you have an ID, it says the data type as well, "string" in the case of flavor. So, all of this information just clearly describes, "yep, this is exactly the request, this is the data you'll get with your response". And then, lastly, the OpenAPI definition could have a section for an example response. So, it will actually have sample data for you to look at when you're referencing the OpenAPI definition. Great. So, hopefully, this makes it clear, and describes why OpenAPI is so fundamental and you should really, really use it when you're working with REST APIs or services. Thank you. If you have questions, please drop us a line below. If you want to see more videos like this in the future, please like and subscribe. And don't forget: you can grow your skills and earn a badge with the IBM Cloud Labs, which are free, browser based, interactive Kubernetes labs.
