WEBVTT 00:00.000 --> 00:16.000 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. 00:16.000 --> 00:24.000 Open API traditionally has been a single standard. 00:24.000 --> 00:33.000 It's the Open API specification describes how it's possible, describes every aspect of your API. 00:33.000 --> 00:39.000 In the last year, Open API has released two related standards. 00:39.000 --> 00:46.000 The first one is on the list, which lets you make changes repeatedly to your Open API file. 00:46.000 --> 01:01.000 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. 01:01.000 --> 01:07.000 Both of those new standards, we didn't invent them in the last year. 01:07.000 --> 01:11.000 They had their 1.0 releases in the last year. 01:11.000 --> 01:24.000 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. 01:24.000 --> 01:32.000 The things that people wish Open API did that really were outside of the scope of the existing specification. 01:32.000 --> 01:40.000 So, if you're here, I hope you know what Open API is, so where is describing API? 01:40.000 --> 01:46.000 The Open API descriptions are in JSON or Yanna format. 01:46.000 --> 01:52.000 This is aimed so that both humans and machines can work with this format. 01:52.000 --> 01:59.000 Please don't complain to me about the choice of formats, I don't make the rules, okay? 01:59.000 --> 02:09.000 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. 02:09.000 --> 02:14.000 That was quite long time ago, Swagger became Open API 2. 02:14.000 --> 02:23.000 We released Open API 3 in July 2017, and 3.1 in February 2021. 02:23.000 --> 02:28.000 So, even 3.1 is for years old. 02:28.000 --> 02:41.000 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? 02:41.000 --> 02:44.000 Or maybe choose another one, just saying. 02:44.000 --> 02:50.000 How do we get there on that run? Okay, so Open API, you can get overview information. 02:50.000 --> 02:55.000 Now, this is something the info section at the top of the file. 02:55.000 --> 03:03.000 Sometimes, that's not the interesting part, and we don't do an amazing job. 03:03.000 --> 03:07.000 We visit your existing API descriptions. 03:07.000 --> 03:16.000 We are increasingly moving to catalogs of APIs, discoverable APIs, machines, discovering APIs. 03:16.000 --> 03:27.000 You need to sort out your index, your index, info section, because this is how everything will be finding and understanding what it does. 03:27.000 --> 03:34.000 And an internal context as well, this stuff is really, really important. 03:34.000 --> 03:43.000 You describe each endpoint, and that's the requests that the URLs that you can make requests to, whereas I have red groups. 03:43.000 --> 03:50.000 So, if you have something where an event causes a response, rather than an incoming request, you describe that as well. 03:50.000 --> 03:54.000 All of the responses that can be returned and the security. 03:54.000 --> 04:02.000 So, Open API describes every aspect of a rest-through-ish HTTP API. 04:02.000 --> 04:07.000 It isn't going to work for every HTTP API, depending on your API design. 04:07.000 --> 04:14.000 It is not great with RPC style, so that's kind of the main overview. 04:14.000 --> 04:17.000 Let's talk about overlays. 04:17.000 --> 04:25.000 I will not admit to having a favorite standard out of the three, so we'd better just go over that part. 04:25.000 --> 04:29.000 All of the ways are a new standard for an API. 04:29.000 --> 04:32.000 Actually, it's been in draft for two years. 04:32.000 --> 04:40.000 And then we realized, oh, we come at changes to this standard, because it's implemented like that. 04:40.000 --> 04:45.000 And we now call it to write until we've done a release, and then we can make some changes. 04:45.000 --> 04:52.000 So, I have released the other ways, specification this year, but I did not do the work. 04:52.000 --> 04:56.000 And I just made it so that we're ready to use it. 04:56.000 --> 05:05.000 Overly solves a really common problem in Open API, which you even have an Open API description that you use, 05:05.000 --> 05:14.000 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. 05:14.000 --> 05:17.000 And that's the problem that overlays solves. 05:17.000 --> 05:24.000 So, in a design first workflow, which is kind of a modern practice, but I'm not going to judge anybody. 05:24.000 --> 05:27.000 You even make those improvements at design time. 05:27.000 --> 05:35.000 If you're Open API comes from somewhere else, either a design that you're not allowed to have input in, 05:35.000 --> 05:41.000 or you're a consumer and you can't improve the Open API description at source. 05:41.000 --> 05:51.000 This generated from code, which is still super common, then overlays lets you feel in those gaps and improve things. 05:51.000 --> 06:01.000 If you're getting Open API generated from code and all the descriptions are rubbish, or there are no examples. 06:01.000 --> 06:10.000 If there's perhaps one response example described that not the intercollection, the error message, 06:10.000 --> 06:14.000 so if there's a missing, if you need to add them in overlays, you can. 06:14.000 --> 06:24.000 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. 06:24.000 --> 06:33.000 So, if you have a situation where you can't include that experimental endpoint in your Open API description, 06:33.000 --> 06:41.000 because you're not ready for everyone to use it yet, in fact you can't include it and use it internally, 06:41.000 --> 06:52.000 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, 06:52.000 --> 06:59.000 that which you maybe don't want to publish to other people or don't want to include your SDKs yet. 06:59.000 --> 07:10.000 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, 07:10.000 --> 07:24.000 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. 07:24.000 --> 07:37.000 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, 07:37.000 --> 07:43.000 we finally released the one-point version, one-point zero version of the specification, officially in October. 07:43.000 --> 07:49.000 So, it sounds believing edge, it really isn't, people are using it, and we just haven't. 07:49.000 --> 07:56.000 The person who is driving this project, stopped driving the project, and yeah, that's the story. 07:56.000 --> 08:10.000 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. 08:10.000 --> 08:23.000 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. 08:23.000 --> 08:32.000 This thing is deterministic, so it will always do this and then this and then this and then this, every time. 08:32.000 --> 08:46.000 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. 08:46.000 --> 08:55.000 If you have questions, that was a very welcome, use a discussion on news and discussions feature on the GitHub repository. 08:55.000 --> 09:02.000 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. 09:02.000 --> 09:08.000 Please help us, and I will help you help us. 09:09.000 --> 09:20.000 Openase is coming along at a time that I am seeing such a big change in the API industry. 09:20.000 --> 09:37.000 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. 09:38.000 --> 09:55.000 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. 09:55.000 --> 10:16.000 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. 10:16.000 --> 10:23.000 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. 10:23.000 --> 10:35.000 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. 10:35.000 --> 10:44.000 Over those will allow you to fill in the gaps. Those missing error boxes are a constant problem. 10:44.000 --> 11:04.000 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. 11:04.000 --> 11:24.000 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. 11:24.000 --> 11:33.000 There are lots and lots of different tools that support this format today and so it's important that we fill in those gaps. 11:33.000 --> 11:44.000 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. 11:44.000 --> 11:54.000 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. 11:54.000 --> 12:03.000 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. 12:03.000 --> 12:19.000 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. 12:19.000 --> 12:26.000 First was that Open API descriptions did not have a license in connection. So that's all the same license, right? 12:26.000 --> 12:34.000 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. 12:34.000 --> 12:51.000 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. 12:51.000 --> 13:00.000 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. 13:00.000 --> 13:05.000 And so we didn't need to maintain a bunch of different things. 13:06.000 --> 13:19.000 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. 13:20.000 --> 13:34.000 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. 13:34.000 --> 13:42.000 You're going to go down that way instead. But yeah, overlays will give you the changes. Cool, okay. 13:43.000 --> 13:45.000 Let's look at the other episode. 13:46.000 --> 13:50.000 Some of you knew this already. 13:50.000 --> 13:54.000 Our episode is eternal for tapestry. 13:54.000 --> 13:59.000 Our episode is the world that we move together. 13:59.000 --> 14:04.000 Our different API calls to make a big picture. 14:04.000 --> 14:06.000 Now I'm not involved in the marketing effort. 14:06.000 --> 14:08.000 It's similar to the API. 14:08.000 --> 14:13.000 Okay. So it let you put together a sequence of API calls. 14:13.000 --> 14:18.000 The API calls are described in Open API files. 14:18.000 --> 14:24.000 And so you add a bunch of, hey, this description in this description, this description. 14:24.000 --> 14:26.000 Hit on those multiple descriptions. 14:26.000 --> 14:33.000 So if you're making calls across different API services, you can easily combine them. 14:33.000 --> 14:41.000 It can, you can give it some inputs. 14:41.000 --> 14:48.000 And you can take the output of one API call and use it as the input for the next API call. 14:48.000 --> 14:53.000 So I see this useful also in integration testing. 14:53.000 --> 14:59.000 You probably have some sort of home, span, scripting, or maybe a postman collection, 14:59.000 --> 15:00.000 paper, nothing. 15:00.000 --> 15:01.000 Awesome. 15:01.000 --> 15:07.000 A postman collection with a scripting that captures the input sets of variable and then calls the next one. 15:07.000 --> 15:08.000 Right. 15:08.000 --> 15:10.000 So this gives you some of that. 15:10.000 --> 15:19.000 You can run the post, look at the response and use that resource identifier in the next API call. 15:19.000 --> 15:24.000 So it's something that lets you really put things together. 15:24.000 --> 15:30.000 You can describe what success and failure looks like for each API call. 15:30.000 --> 15:33.000 And you can also say what you expect to happen. 15:33.000 --> 15:37.000 Because sometimes we are not testing the happy path. 15:37.000 --> 15:40.000 And so we expect the America. 15:40.000 --> 15:41.000 That's good. 15:41.000 --> 15:45.000 We need to be able to. 15:45.000 --> 15:51.000 When I think about the use cases for our answer, 15:51.000 --> 16:01.000 I think it is through about the API experience on our modern and more complex APIs. 16:01.000 --> 16:09.000 It allows us to create documentation that describes a multi-step API operation. 16:09.000 --> 16:20.000 It allows us to generate SDKs that know you do this and then this and then this to complete a particular function or task. 16:20.000 --> 16:26.000 And so we can present a single method called for the user. 16:26.000 --> 16:32.000 And the generators can understand that it's multiple steps. 16:32.000 --> 16:34.000 Testing is a big one. 16:34.000 --> 16:38.000 So I expect the testing tools to be the first thing that we see. 16:38.000 --> 16:41.000 Really being stable and ready. 16:41.000 --> 16:43.000 So the structure of the answer document. 16:43.000 --> 16:47.000 It describes one or more workflows. 16:47.000 --> 16:52.000 Each workflow contains a series of steps. 16:52.000 --> 16:55.000 So each step is going to be your API call. 16:55.000 --> 16:58.000 Those calls are in open API descriptions. 16:58.000 --> 17:01.000 You can describe success and failure. 17:01.000 --> 17:07.000 And you can both give input variables to workflow or to a whole file. 17:07.000 --> 17:16.000 And then use those values and the outputs of other API calls throughout the workflow and the steps. 17:16.000 --> 17:18.000 So I really like this. 17:18.000 --> 17:20.000 Here's a tiny example. 17:20.000 --> 17:22.000 I only had to chop a little bit out the middle. 17:22.000 --> 17:25.000 Sharing it. 17:25.000 --> 17:29.000 Referring to an open API description for animals. 17:29.000 --> 17:32.000 And the workflow has one step. 17:32.000 --> 17:34.000 It just gets a random animal. 17:34.000 --> 17:36.000 But you could start to add other steps. 17:36.000 --> 17:40.000 If you didn't get an animal back, then you would do something else. 17:40.000 --> 17:44.000 There's a bunch of, there isn't really dogs for a lot. 17:44.000 --> 17:47.000 But if you look in the array, so repository. 17:47.000 --> 17:52.000 There's quite a good selection of examples in the directory main examples. 17:52.000 --> 17:54.000 Hopefully you'll find it. 17:54.000 --> 17:59.000 And so that's a really good place to look for the kinds of things that you can do. 17:59.000 --> 18:02.000 And I'll build it on that all the time. 18:02.000 --> 18:08.000 So that is an offset in your workflow. 18:08.000 --> 18:13.000 So right now, it's kind of early days. 18:13.000 --> 18:17.000 This is one to watch through this year. 18:17.000 --> 18:22.000 Because try to get the tooling vendors to tell me what they have. 18:22.000 --> 18:25.000 I mean, it's another green road, Bob. 18:25.000 --> 18:28.000 A couple of people are like, oh, yeah, we've got a plan. 18:28.000 --> 18:32.000 It's like, well, that really, really thing is out right. 18:32.000 --> 18:35.000 This is, you're going to hear about this over here. 18:35.000 --> 18:40.000 So I'm not going to name any tools right now because it's going to be out of date by next week. 18:40.000 --> 18:45.000 But you're going to use a lot so to improve the quality of your own APIs. 18:45.000 --> 18:49.000 You're going to use it to describe how things change together, 18:49.000 --> 18:52.000 and to be certain that all of those things work, 18:52.000 --> 18:54.000 and to explain those things to other people. 18:54.000 --> 19:01.000 Remember that all this stuff is important for internal APIs as well. 19:01.000 --> 19:07.000 You know, I like my colleagues just as much as I like my external API consumers, right? 19:07.000 --> 19:11.000 They deserve the same experience. 19:11.000 --> 19:13.000 It's going to help us with integrations. 19:13.000 --> 19:19.000 Remember, for actually for overlays as well as a RACO, 19:19.000 --> 19:23.000 there's no rule that says you can't use this extra, 19:23.000 --> 19:28.000 super, much extra stuff on other people's APIs. 19:28.000 --> 19:32.000 Right? If you're disappointed with your producers API experience, 19:32.000 --> 19:37.000 you can still ramp that up inside your usage. 19:37.000 --> 19:40.000 I mean, and then maybe you should blog about it and tell them to be better. 19:40.000 --> 19:42.000 You're going to use it for testing. 19:42.000 --> 19:45.000 You're going to use, there's going to be more things. 19:45.000 --> 19:52.000 Right now, you can link both reductly CLI and Spectral have support for RACO linting, 19:52.000 --> 19:59.000 which is really useful when you're working with a new and unfamiliar standard. 19:59.000 --> 20:04.000 All right, what's next? So, this part is incredibly hard 20:04.000 --> 20:10.000 because we're volunteers, kind of know that all your I think things will happen in. 20:10.000 --> 20:14.000 But if anyone comes and champion something, then that's what's happening. 20:14.000 --> 20:21.000 And it's a little bit subjective who's working on what and how much volunteer time they then have. 20:21.000 --> 20:26.000 As you earn, though, from your open source projects, you know, somebody has a baby, 20:26.000 --> 20:30.000 and then that wraps out half a year for everybody. It's just, it's normal. 20:30.000 --> 20:34.000 And the open API initiative is no different. 20:34.000 --> 20:40.000 Right now, our main activities are on improving the resources that we have. 20:40.000 --> 20:47.000 If you depend on our schema representations for Open API RACO and overlays those, 20:47.000 --> 20:51.000 look again, we have really pulled on socks up with that. 20:51.000 --> 20:53.000 That is much better. 20:53.000 --> 20:58.000 We're revisiting all our registries and you will see changes coming in our documentation 20:58.000 --> 21:02.000 and in the spec site in the coming weeks and months. 21:02.000 --> 21:05.000 This is all the stuff I was prepared to put on the slide. 21:05.000 --> 21:12.000 Soon, meaning probably in the first half a year, what we're releasing in Open API 3.2. 21:12.000 --> 21:16.000 It is a minor update. 21:16.000 --> 21:21.000 So, we recently released 3.1.1, which was just text updates to the specification, 21:21.000 --> 21:24.000 but no actual standard changes. 21:24.000 --> 21:27.000 3.2 does have standard changes. 21:27.000 --> 21:30.000 We've added support for device authorization flow, 21:30.000 --> 21:34.000 and the OL2 skins can be marked as deprecated as well, 21:34.000 --> 21:38.000 so that if you're using something that then you're going to remove in the future, 21:38.000 --> 21:42.000 we've got the deprecation support on those fields. 21:42.000 --> 21:47.000 You can, we're adding support for, 21:47.000 --> 21:50.000 but you are able to get the OL2 metadata, 21:50.000 --> 21:52.000 so you can find out how to authenticate, 21:52.000 --> 21:55.000 so it's like a discovery thing that's in OL2. 21:55.000 --> 21:56.000 We support that now. 21:56.000 --> 22:01.000 It also has extended support for tags. 22:01.000 --> 22:05.000 So, as of 3.2, you'll be able to add a summary for the tag. 22:05.000 --> 22:09.000 You'll be able to categorize the tag and you can also nest tags. 22:09.000 --> 22:11.000 This is impactful for everybody. 22:11.000 --> 22:16.000 Please go and read about it and tell us if this seems like a terrible idea. 22:16.000 --> 22:19.000 It was my idea. I'm happy to hear that feedback. 22:19.000 --> 22:23.000 The path URL and templating improvements, 22:23.000 --> 22:25.000 that doesn't change anything, 22:25.000 --> 22:29.000 but it describes what you can and can't do much better, 22:29.000 --> 22:31.000 and that's mostly aimed at tools vendors 22:31.000 --> 22:34.000 to help us be more interoperable, right? 22:34.000 --> 22:39.000 Not soon, but someday, you'll have Open API 4. 22:39.000 --> 22:42.000 The goal of Open API 4 is, 22:43.000 --> 22:45.000 it will be a complete change. 22:45.000 --> 22:47.000 You'll be doing some of the same things, 22:47.000 --> 22:50.000 but the format looks really different. 22:50.000 --> 22:53.000 We'll be supporting more types of API, 22:53.000 --> 22:56.000 so your RPC style should be better supported, 22:56.000 --> 22:59.000 some of those legacy APIs should be better supported. 22:59.000 --> 23:04.000 There'll be more ways to describe what's coming in and going out. 23:04.000 --> 23:06.000 And things will be a little bit more separated 23:06.000 --> 23:09.000 in terms of what's an API and what's a deployment, 23:09.000 --> 23:12.000 those kinds of things. It is early days. 23:12.000 --> 23:15.000 So, keep in touch with the project. 23:15.000 --> 23:17.000 If you are really interested, 23:17.000 --> 23:20.000 or there are features that you want to see in the next version, 23:20.000 --> 23:22.000 that we cannot fit into three, 23:22.000 --> 23:27.000 everything that happens in Open API happens in the Open. 23:27.000 --> 23:30.000 So, you're going to go to OpenAPIs.org 23:30.000 --> 23:34.000 and you're going to choose your own adventure 23:34.000 --> 23:36.000 from that location. 23:36.000 --> 23:39.000 So, we've got everything that happens in all the projects 23:39.000 --> 23:40.000 is on GitHub. 23:40.000 --> 23:41.000 It's in issues. 23:41.000 --> 23:44.000 There are meeting agenda issues or discussions 23:44.000 --> 23:46.000 look in the discussion tab as well. 23:46.000 --> 23:47.000 To see what's going on. 23:47.000 --> 23:49.000 All the pull requests to there. 23:49.000 --> 23:51.000 All the conversation is there. 23:51.000 --> 23:53.000 They're constant refrain in our Slack channel. 23:53.000 --> 23:56.000 Can you put that in a comment, please? 23:56.000 --> 23:59.000 We have regular public meetings. 23:59.000 --> 24:01.000 So, all of those three specifications 24:01.000 --> 24:04.000 meet either every week or every other week. 24:04.000 --> 24:05.000 It is public. 24:05.000 --> 24:08.000 It's kind of an anti-social time for this time's own. 24:08.000 --> 24:10.000 Sorry. 24:10.000 --> 24:12.000 Yeah, I can't. 24:12.000 --> 24:13.000 There's many things I can't fix. 24:13.000 --> 24:16.000 If this is like information overload, 24:16.000 --> 24:18.000 go to the website, sign up for the newsletter, 24:18.000 --> 24:20.000 we'll just send you small updates 24:20.000 --> 24:23.000 so you can keep up at times. 24:23.000 --> 24:27.000 So, that was an overview of the OpenAPIs landscape. 24:27.000 --> 24:29.000 OpenAPIs are live and well. 24:29.000 --> 24:30.000 Still being updated. 24:30.000 --> 24:32.000 If your tools are not being updated, 24:33.000 --> 24:34.000 why not? 24:34.000 --> 24:35.000 Overlaze. 24:35.000 --> 24:37.000 Make your OpenAPIs better. 24:37.000 --> 24:38.000 Please. 24:38.000 --> 24:40.000 All right. 24:40.000 --> 24:44.000 So, tell the truth about how things actually go together 24:44.000 --> 24:47.000 and that helps you and it helps your consumers. 24:47.000 --> 24:50.000 I've got some links to share with you here. 24:50.000 --> 24:53.000 Please connect with me, talk to me. 24:53.000 --> 24:55.000 I am currently looking for a job. 24:55.000 --> 24:57.000 So, if you need me, you should tell me. 24:57.000 --> 25:00.000 And with that, I will say thanks very much for your attention. 25:00.000 --> 25:02.000 Thank you. 25:02.000 --> 25:04.000 Thank you. 25:04.000 --> 25:06.000 Thank you. 25:06.000 --> 25:08.000 Thank you.