... 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.