API Evangelist Conversation With Frank Kilcommins About the OpenAPI Arazzo Specification

Hello, Ken. My name is Frank Kilcommons, and I am also an API evangelist with a company called Smartware. I do a lot of work across the board. OpenAPI initiative and, uh, Good, Bad or Indifferent have been working quite a bit with the ORAZO specification.

Razzle is a, it’s the [00:01:00] brainchild of the OpenAPI initiative. So quick history lesson a few years ago, I don’t know if we got bored because of the pandemic or whatnot, but we tried to tackle some bigger challenges that are happening across the API landscape under the API umbrella. So we created working groups, you were. heavily involved, uh, kind of in the formation of all of those can, and one of the topic areas that really piqued my interest was the concept of, well, how can we describe API workflows on top of modern API, um, let’s say technology in a way that will alleviate a lot of the pain that we felt as practitioners. Um, and Erazo was the, the result or the birthing of that process, uh, into a that also went, to a certain degree, a long way to maturing the OpenAPI initiative to a multi specification project. And so RAZO is all about describing API workflows. And so I think we’ve all been in the scenario where we’ve been onboarded to an API. [00:02:00] We’ve gotten that reference documentation or that OpenAPI description, but it’s, you know, 200 endpoints long. And you’re like, well, that’s cool, but actually what I want to do is A, B, C, and D, and how can I achieve that? I’m kind of blinded by the verbosity of this thing. And in other situations, what we want to achieve might span across multiple OpenAPI descriptions. And again, that’s where the process breaks down from a kind of community or open standards perspective. ‘cause we had no way to kinda chain, uh, what to do across multiple of tho those types of artifacts without some human manual work. And if you did really well, you would describe that in your developer portal in a format like. You know html and having the pages there to guide folks through the process If you did it not quite as well, then maybe out of band you would be sharing things like powerpoint docs google slides Pngs gifs videos, whatever the case may be, which is all great It’s all trying to make the life [00:03:00] easier from a consumer But ultimately once you put the investment into crafting those things they have at this nasty habit of getting stale and out of sync very, very quickly. So, um, they were some of the primary use cases that we focused on from Erazo as well as better testability and revamping kind of the SDK and code generation ecosystem. Because again, if you have that really big open API description, or you have. you know, very modular OpenAPI descriptions. Again, the code that gets automatically generated from those things can be hard, hard to deal with. But if you generate code specifically for the use case that you’re interested in, it keeps you on peace and it ultimately makes you, makes your life a lot easier. And then the elephant that came into the room throughout the whole process, of course, was, was AI. And okay, now we have AI as an API consumer. How is this all going to work, especially if we haven’t been doing our job so well from an API documentation perspective? And Erazo seems to be coming out right at the right time, [00:04:00] where it’s kind of adding the required levels of determinism to give us confidence in offloading the responsibility of API consumption to these agents who are going to perform, you know, critical activities on our behalf.

Yes, again, and I think that’s the way everything is even maybe accelerating now is people are going to get less caught up in the actual. Semantic formats that are under the hood of these things. They just want better experiences and, and, and capabilities to enable them, get their job [00:06:00] done, uh, as a practitioner or, or as a product manager or whatever the case may be. Um, so it’s, it’s very exciting to see the emergence of new tooling because. While I do love specifications, a specification that is not supported or implemented by any tooling is not so accessible for folks. Um, so it’s, it’s really encouraging to see the tooling that’s, that’s coming about. Um, I see different vendors focusing on the kind of consumer experience. So thinking about things like recipes, things like. guided walkthroughs when it comes to the API documentation. So again, folks don’t have to get stuck in the weeds of an OpenAPI description. They can focus on kind of going through step by step what are the tasks that we need to achieve to achieve this overall job to be done. And so really kind of guiding people very carefully through that process and [00:07:00] having an ability to be able to kind of keep that documentation up to date on the fly as the underlying components may change. And there’s a lot of interest in the testing side of the house. And I think that’s where we’ve done poorly across the industry in general is giving folks. the robust and easy to use tooling to make sure that what they’re doing actually, you know, validates what’s on the tens or are they doing what they promise? Um, and also are they able to manage drift over time, which is a big, a big challenge. So if you think about a razzle, giving you a way to, um, proclaim your promises and your capabilities to the world. It gives the tooling and the machines under the hood a way to validate that you can keep and honor that promise as the underlying APIs change themselves. So I also see it kind of doubling up as a end to end or functional testing specification in the minds of many, and I think that will be kind of an area that we’ll be advocating for quite a bit as well.[00:08:00] And I also alluded to it in my big spiel to open, but the SDK side of the house and co generation side of the house is very interesting. And there’s a good few vendors focusing there as well. And then we have the supporting tools around. around that, like, like linting, like validation, like just being able to parse and ensure that these things are, are correct. Um, which is, which is exciting. And I even see industry bodies becoming interested in it, which again is, is a good sign that they see this as a, I don’t know whether they’re looking at it as a piece of chocolate, a carrot or a stick, but it’s, it’s something that they can use to make sure that the providers that are within their industry vertical or doing things in a consistent manner.

Well, that’s the goal. I think Let’s say this, the semantics that are contained within something like this and the format itself aids itself to allowing tooling to help us govern these things. So, um, you know, follows a lot of the same principles as open API and async API with regards to some of the metadata objects that are there that you can enrich and make it, you know, more. Uh, let’s say better able to classify by tooling. So I can imagine that you will have things like portfolios of capabilities rather than portfolios of distinct API. So it’s more like you can, you can search and you can discover the capability that you need to solve the problem that you have. And then from there, you can see potentially what, you know, what API providers are offering these things underneath the hood. And, you know, that will expose a whole other dimension of things that you might care about, you know, the SLAs that are offered by those underlying providers, etc. So it gives [00:11:00] you this, this ability to kind of. attack the problem from maybe a higher plane and one that is a little bit more intuitive to think about as we’re trying to solve problems in the human context. And there’s something, there’s a thread that I haven’t pulled on too hard yet, but I think Um, we also do a bad job at expressing what we want from software, and then we can only really fully articulate that back to the provider when we see something. Um, and for me, I think there’s a, there’s something in arousal, which combined with maybe practices from behavioral driven development that can give us. Something to move more confidently from the requirements that we are setting forth into the actual software that’s built to honor those requirements. But it’s a thread I haven’t pulled on too hard yet, but for me, there’s something interesting down that rabbit hole.

Yeah, that’s the plan. Like, um, you know, nothing is happening in a vacuum and that’s. That’s kind of one of the benefits of it being a specification under the broader OpenAPI initiative umbrella. Um, so, you know, advancements that we make with regards to referencing [00:13:00] across all of these different types of artifacts, uh, having some kind of continuity of principle with regards to how we tackle some of the bigger problems, we’ll then start kind of sharing those and. Implementing those hopefully consistently across all specifications. Um, one of the exciting things that we’ll be working on soon, um, as part of kind of the core working group is also adding support for Async API within Orazo. So, you know, it’s very practical that you will have, um, a workflow or a use case that will span request response type of interfaces as well as event driven um, types of interfaces. So being able to describe that. As part of this overarching workflow or recipe is something that will be possible in the not too distant future.

Yeah, so we were welcoming of help across the board. So what I would say is go to the, uh, to the open API’s website. So that’s, um, open apis. org. And what you will find there is you’ll find a way to join the slack community, which is an open community. You’ll also find where all of the GitHub repositories are. So any form of entry into that ecosystem is, [00:15:00] is, is welcome. And one of the things that we will be doing is updating the tooling site, having a listing of all of the emerging tooling that is coming from an Erazor perspective. And we’ll be looking to showcase some of the vendors that are building tooling there underneath the OpenAPI. Outreach committee as well. So we are eager to kind of showcase the work that folks are doing, uh, in kind of driving adoption of the specifications forward. And it’s something that we’re, we’re hoping to get much more engaged in as a community.