So, I'm excited about Open API, I'm excited about frozen, I'm excited about you all being here, so let's go into it.
Open API traditionally has been a single standard.
It's the Open API specification describes how it's possible, describes every aspect of your API.
In the last year, Open API has released two related standards.
The first one is on the list, which lets you make changes repeatedly to your Open API file.
The other one is a rato, which lets you link your Open API, your different API calls together, and programmatically describe how that stuff should be used and should work.
Both of those new standards, we didn't invent them in the last year.
They had their 1.0 releases in the last year.
These are things that we've been working on for a long time, and that address some of the most common questions, requests, complaints, however you want to call those things in Open API.
The things that people wish Open API did that really were outside of the scope of the existing specification.
So, if you're here, I hope you know what Open API is, so where is describing API?
The Open API descriptions are in JSON or Yanna format.
This is aimed so that both humans and machines can work with this format.
Please don't complain to me about the choice of formats, I don't make the rules, okay?
If you've worked with something called Swagger, why back in the past, you know what I'm talking about, because Open API was firmly known as Swagger.
That was quite long time ago, Swagger became Open API 2.
We released Open API 3 in July 2017, and 3.1 in February 2021.
So, even 3.1 is for years old.
So, my request to you is if any of your tooling providers do not yet support 3.1, could you please ask them why not?
Or maybe choose another one, just saying.
How do we get there on that run? Okay, so Open API, you can get overview information.
Now, this is something the info section at the top of the file.
Sometimes, that's not the interesting part, and we don't do an amazing job.
We visit your existing API descriptions.
We are increasingly moving to catalogs of APIs, discoverable APIs, machines, discovering APIs.
You need to sort out your index, your index, info section, because this is how everything will be finding and understanding what it does.
And an internal context as well, this stuff is really, really important.
You describe each endpoint, and that's the requests that the URLs that you can make requests to, whereas I have red groups.
So, if you have something where an event causes a response, rather than an incoming request, you describe that as well.
All of the responses that can be returned and the security.
So, Open API describes every aspect of a rest-through-ish HTTP API.
It isn't going to work for every HTTP API, depending on your API design.
It is not great with RPC style, so that's kind of the main overview.
Let's talk about overlays.
I will not admit to having a favorite standard out of the three, so we'd better just go over that part.
All of the ways are a new standard for an API.
Actually, it's been in draft for two years.
And then we realized, oh, we come at changes to this standard, because it's implemented like that.
And we now call it to write until we've done a release, and then we can make some changes.
So, I have released the other ways, specification this year, but I did not do the work.
And I just made it so that we're ready to use it.
Overly solves a really common problem in Open API, which you even have an Open API description that you use,
or that you either as a consumer or as a producer, which you raise your hand if you think it could be improved in any way.
And that's the problem that overlays solves.
So, in a design first workflow, which is kind of a modern practice, but I'm not going to judge anybody.
You even make those improvements at design time.
If you're Open API comes from somewhere else, either a design that you're not allowed to have input in,
or you're a consumer and you can't improve the Open API description at source.
This generated from code, which is still super common, then overlays lets you feel in those gaps and improve things.
If you're getting Open API generated from code and all the descriptions are rubbish, or there are no examples.
If there's perhaps one response example described that not the intercollection, the error message,
so if there's a missing, if you need to add them in overlays, you can.
You can also use overlays to remove things, so the structure of the file is a series of actions where the action is updated or removed.
So, if you have a situation where you can't include that experimental endpoint in your Open API description,
because you're not ready for everyone to use it yet, in fact you can't include it and use it internally,
but then you can use an overlay to drop out those private beta experimental internal partner only, whatever endpoints that are part of your API surface,
that which you maybe don't want to publish to other people or don't want to include your SDKs yet.
Another very common use case, and I sort of think about overlays in two phases, one is the input to make the Open API amazing,
which is some of the stuff I just said, and the other is the output to prepare your Open API description for a particular destination.
So, overlays, the draft spec has been around for a while, the two support is nice and stable, and then in a sort of backwards kind of array,
we finally released the one-point version, one-point zero version of the specification, officially in October.
So, it sounds believing edge, it really isn't, people are using it, and we just haven't.
The person who is driving this project, stopped driving the project, and yeah, that's the story.
Here's a tiny example, so this is an overlay with a single action, it adds a tag to all of the endpoints that use a delete method.
You can see I've got an array of actions, I was only one, because I didn't want to let my phone size any smaller, they are executed in order.
This thing is deterministic, so it will always do this and then this and then this and then this, every time.
So, there are a lot more examples and more explanation if you want to have a proper look at it on the Open API documentation site, which is learn.openaprives.org.
If you have questions, that was a very welcome, use a discussion on news and discussions feature on the GitHub repository.
If you have problems with the documentation, criticism is welcome, I wrote it, open the pro request, I'll be in the other end of it.
Please help us, and I will help you help us.
Openase is coming along at a time that I am seeing such a big change in the API industry.
I think we have a real understanding now that an Open API file is not a static build artifact or even right once and it never changes.
I'm saying a lot, there's a lot of things some understanding that having different lenses, different versions of the API different renderings, if you like, but that's now common practice.
If you work on a microservices architecture, there's tooling now that will allow you to take each individual Open API description and bring them into run, but then you can use to make documentation that gives the impression that the different departments in your company talk to each other.
I don't let me go down the run about API governance and standards, that's a different talk and we don't have time.
You could probably find a video of it somewhere, so we have the tooling to bring those multiple APIs together into run if we want to.
Over those will allow you to fill in the gaps. Those missing error boxes are a constant problem.
The way the Open API began to be used was very much kind of a gateway to accurate documentation and the result is we have a lot of generated docs where there's a parameter called this, it's described in the code, it shows up in the docs, that's it.
And for anyone who cares about the API consumers, the expectations and API experience are greatly improved and even expect very rich and complete documentation and I'm going to use your Open API file for things that are not just docs.
There are lots and lots of different tools that support this format today and so it's important that we fill in those gaps.
Increase the descriptions. A lot of good news to overlays is if you want to provide documentation in other languages, you can localize the description fields with overlays.
And so if you are generating your Open API or if something else changes about it, you're not trying to hand patch between these different versions that you have to maintain.
Forget it. You've got a set of overlays. Yes, if the Open API changes, you might need to add more stuff to the overlay, but it's repeatable.
You can also use the same overlay for multiple Open API descriptions. If it isn't specific, so for example, I've recently worked for a customer during a project where there are two problems that we solved with overlays.
First was that Open API descriptions did not have a license in connection. So that's all the same license, right?
So one overlay applies to everything. Everything's got a license now. If we change our mind about a license, we're updating it in one place. We can reuse it.
And the other one was the applied gateway, you can different metadata, depending which region they were deploying to, for different data sovereignty, and right in it, legal reasons.
And that's all. We just did a bunch of copies of the Open API file, applied it to overlay to each one and sent it off to whichever region they were deploying to.
And so we didn't need to maintain a bunch of different things.
There are a bunch of tools in this space overlays is not the only way, and it might not serve all of your needs. I have seen a bunch of really excellent Open API problems solved with JQ.
So they'll be fried to use any tool that comes to hand, especially in the special mention also to re-duck these decorators. They give you scripting inputings, so you need the input data to figure out what your output should be.
You're going to go down that way instead. But yeah, overlays will give you the changes. Cool, okay.
Let's look at the other episode.
Some of you knew this already.
Our episode is eternal for tapestry.
Our episode is the world that we move together.
Our different API calls to make a big picture.
Now I'm not involved in the marketing effort.
It's similar to the API.
Okay. So it let you put together a sequence of API calls.
The API calls are described in Open API files.
And so you add a bunch of, hey, this description in this description, this description.
Hit on those multiple descriptions.
So if you're making calls across different API services, you can easily combine them.
It can, you can give it some inputs.
And you can take the output of one API call and use it as the input for the next API call.
So I see this useful also in integration testing.
You probably have some sort of home, span, scripting, or maybe a postman collection,
paper, nothing.
Awesome.
A postman collection with a scripting that captures the input sets of variable and then calls the next one.
Right.
So this gives you some of that.
You can run the post, look at the response and use that resource identifier in the next API call.
So it's something that lets you really put things together.
You can describe what success and failure looks like for each API call.
And you can also say what you expect to happen.
Because sometimes we are not testing the happy path.
And so we expect the America.
That's good.
We need to be able to.
When I think about the use cases for our answer,
I think it is through about the API experience on our modern and more complex APIs.
It allows us to create documentation that describes a multi-step API operation.
It allows us to generate SDKs that know you do this and then this and then this to complete a particular function or task.
And so we can present a single method called for the user.
And the generators can understand that it's multiple steps.
Testing is a big one.
So I expect the testing tools to be the first thing that we see.
Really being stable and ready.
So the structure of the answer document.
It describes one or more workflows.
Each workflow contains a series of steps.
So each step is going to be your API call.
Those calls are in open API descriptions.
You can describe success and failure.
And you can both give input variables to workflow or to a whole file.
And then use those values and the outputs of other API calls throughout the workflow and the steps.
So I really like this.
Here's a tiny example.
I only had to chop a little bit out the middle.
Sharing it.
Referring to an open API description for animals.
And the workflow has one step.
It just gets a random animal.
But you could start to add other steps.
If you didn't get an animal back, then you would do something else.
There's a bunch of, there isn't really dogs for a lot.
But if you look in the array, so repository.
There's quite a good selection of examples in the directory main examples.
Hopefully you'll find it.
And so that's a really good place to look for the kinds of things that you can do.
And I'll build it on that all the time.
So that is an offset in your workflow.
So right now, it's kind of early days.
This is one to watch through this year.
Because try to get the tooling vendors to tell me what they have.
I mean, it's another green road, Bob.
A couple of people are like, oh, yeah, we've got a plan.
It's like, well, that really, really thing is out right.
This is, you're going to hear about this over here.
So I'm not going to name any tools right now because it's going to be out of date by next week.
But you're going to use a lot so to improve the quality of your own APIs.
You're going to use it to describe how things change together,
and to be certain that all of those things work,
and to explain those things to other people.
Remember that all this stuff is important for internal APIs as well.
You know, I like my colleagues just as much as I like my external API consumers, right?
They deserve the same experience.
It's going to help us with integrations.
Remember, for actually for overlays as well as a RACO,
there's no rule that says you can't use this extra,
super, much extra stuff on other people's APIs.
Right? If you're disappointed with your producers API experience,
you can still ramp that up inside your usage.
I mean, and then maybe you should blog about it and tell them to be better.
You're going to use it for testing.
You're going to use, there's going to be more things.
Right now, you can link both reductly CLI and Spectral have support for RACO linting,
which is really useful when you're working with a new and unfamiliar standard.
All right, what's next? So, this part is incredibly hard
because we're volunteers, kind of know that all your I think things will happen in.
But if anyone comes and champion something, then that's what's happening.
And it's a little bit subjective who's working on what and how much volunteer time they then have.
As you earn, though, from your open source projects, you know, somebody has a baby,
and then that wraps out half a year for everybody. It's just, it's normal.
And the open API initiative is no different.
Right now, our main activities are on improving the resources that we have.
If you depend on our schema representations for Open API RACO and overlays those,
look again, we have really pulled on socks up with that.
That is much better.
We're revisiting all our registries and you will see changes coming in our documentation
and in the spec site in the coming weeks and months.
This is all the stuff I was prepared to put on the slide.
Soon, meaning probably in the first half a year, what we're releasing in Open API 3.2.
It is a minor update.
So, we recently released 3.1.1, which was just text updates to the specification,
but no actual standard changes.
3.2 does have standard changes.
We've added support for device authorization flow,
and the OL2 skins can be marked as deprecated as well,
so that if you're using something that then you're going to remove in the future,
we've got the deprecation support on those fields.
You can, we're adding support for,
but you are able to get the OL2 metadata,
so you can find out how to authenticate,
so it's like a discovery thing that's in OL2.
We support that now.
It also has extended support for tags.
So, as of 3.2, you'll be able to add a summary for the tag.
You'll be able to categorize the tag and you can also nest tags.
This is impactful for everybody.
Please go and read about it and tell us if this seems like a terrible idea.
It was my idea. I'm happy to hear that feedback.
The path URL and templating improvements,
that doesn't change anything,
but it describes what you can and can't do much better,
and that's mostly aimed at tools vendors
to help us be more interoperable, right?
Not soon, but someday, you'll have Open API 4.
The goal of Open API 4 is,
it will be a complete change.
You'll be doing some of the same things,
but the format looks really different.
We'll be supporting more types of API,
so your RPC style should be better supported,
some of those legacy APIs should be better supported.
There'll be more ways to describe what's coming in and going out.
And things will be a little bit more separated
in terms of what's an API and what's a deployment,
those kinds of things. It is early days.
So, keep in touch with the project.
If you are really interested,
or there are features that you want to see in the next version,
that we cannot fit into three,
everything that happens in Open API happens in the Open.
So, you're going to go to OpenAPIs.org
and you're going to choose your own adventure
from that location.
So, we've got everything that happens in all the projects
is on GitHub.
It's in issues.
There are meeting agenda issues or discussions
look in the discussion tab as well.
To see what's going on.
All the pull requests to there.
All the conversation is there.
They're constant refrain in our Slack channel.
Can you put that in a comment, please?
We have regular public meetings.
So, all of those three specifications
meet either every week or every other week.
It is public.
It's kind of an anti-social time for this time's own.
Sorry.
Yeah, I can't.
There's many things I can't fix.
If this is like information overload,
go to the website, sign up for the newsletter,
we'll just send you small updates
so you can keep up at times.
So, that was an overview of the OpenAPIs landscape.
OpenAPIs are live and well.
Still being updated.
If your tools are not being updated,
why not?
Overlaze.
Make your OpenAPIs better.
Please.
All right.
So, tell the truth about how things actually go together
and that helps you and it helps your consumers.
I've got some links to share with you here.
Please connect with me, talk to me.
I am currently looking for a job.
So, if you need me, you should tell me.
And with that, I will say thanks very much for your attention.
Thank you.