From Legacy to Agents: Rethinking API Governance for AI

Ikenna: Hello, welcome everyone to the API Governance for Scale podcast where we discuss scaling API platforms, API governance and API delivery in the enterprise. My name is Iken Nangwewu. I'm an independent consultant at Ikena Consulting and the host of this podcast. With me today is Anjie Yajina who is chief API architect at PZU, which is the largest insurance provider in ⁓ Poland, which has been around for decades.

And he's the author of the book, Restful API Design Patterns and Best Practices. And I've bumped into Andrzej at quite a few API conferences, and I'm so happy to have him on the podcast today. Welcome, Andrzej, how are you? Andrzej Jarzyna: Hi Eikino, thank you.

⁓ I'm very good, I'm happy to be here. Yeah, it's a beautiful day finally in Poland today after a long winter. Ikenna: Yeah, I hear it's very cool there right now. Andrzej Jarzyna: Yeah, it has been for like three months.

Now it's perfect. I mean, it's getting perfect. Ikenna: So good, good. It's warming up, warming up, warming up.

I like warm, I like warm weather. So, know, Andre, you know, again, thank you for being on the show. I, when I, we were at platform summit together in October last year and I missed your talk. You know, I was, you know, somewhere else, I missed your talk.

But when I, when I saw the topic out, you know, and I saw your slides, I was like, this is really interesting because in it, you kind of tell the story of API governance at PZU. Andrzej Jarzyna: Can imagine. Ikenna: all the work you guys did, know, awesome work. And I'd love to really dig into that today.

⁓ but before we go down there, I thought you first by maybe just we'll start by ⁓ asking you to tell us a bit about yourself, how you got into APIs ⁓ API governance. Yeah, tell us a bit about yourself. Andrzej Jarzyna: Sure. So my story with APIs is quite long, think.

It's around 15 years. I started in 2011 at of three ⁓ first API companies, Threescale. ⁓ I'm not if you are familiar with it, but yeah. So that was also the place where...

Ikenna: Yeah. Yeah. Know them well. Yeah.

Andrzej Jarzyna: I started my story with API governance. However, I think it wasn't called like that at that moment because stayed for five years at 3scale we to call ⁓ API as API or API management or things like that. At that time, as it was like early stage of my career, I was helping onboarding our enterprise customers. And because there was like good practices yet like worked out in the market or they were very scarce, we were trying to help our customers to build those API programs.

And with experience, I later started a true API governance journey at Adidas where we had already an API governance team and we're leading the program for the whole company. was a pretty big company, even though they are not like software provider, they employed like a couple of thousand of developers. So that was that. And then I worked at ING bank, helping them with their API governance program, particularly with policies code initiative.

I wrote this book, I helped some companies consulting a little bit ⁓ ⁓ ⁓ started working at PZU, I think it's more than ⁓ and a half years ago. So this experience is a bit different because before everyone had something already established in terms of their API program. PZU was like the tabula rasa, like a blank slate. Ikenna: Mm.

Andrzej Jarzyna: And I had to convince, I mean, they were convinced they want something, right? But I had to convince them what has to be done and how and what is my vision and then like come to an agreement. Where do we go? Ikenna: Interesting, interesting.

I was also interested that you mentioned right? Because I know that they were one of the, if I remember correctly, and tell me if I'm wrong, one the early kind of public API standards documents that were published on GitHub then. I think Adidas and kind ⁓ of ⁓ at forefront, I guess maybe while you were there or some part of the team, just pushing those... Andrzej Jarzyna: Mm-hmm.

Ikenna: kind of API standards and all that kind of stuff really early on. I think there quite a few ⁓ people in the API governance space that started off at Adidas or were involved in that team. Yeah. Andrzej Jarzyna: Yeah, I think so.

⁓ We're very lucky to have Zdenek Nemec on board. He was like the visionary, the first person helped building that program together with ⁓ Aldrich... ⁓ don't remember his name. a very difficult name, I guess.

Sorry. I don't to like not mention him. ⁓ Ikenna: Mmm. Yeah.

Yeah. Andrzej Jarzyna: Wow, just name. Yeah, yeah. Together with Aldrich, they've built the API governance program.

⁓ when I arrived, we had already like a very early version of API guidelines. ⁓ So we had something to start with and we had a model to approach building the design process. ⁓ And ⁓ were... Ikenna: You remember it, it will come to you.

Hmm. Yeah. Andrzej Jarzyna: already like API first, API as a product and so on. But yeah, during my tenure, ⁓ think we were the first ⁓ company using Spectral.

So I'm even mentioned somewhere on the Spectral page is like, ⁓ contributor the first guidelines. So that fun. That was a lot of like ⁓ being the a little bit now on what was happening at that time. Adidas was definitely.

Ikenna: I hope not. Andrzej Jarzyna: a company which tried to do something one of the first companies. Ikenna: Yeah, yeah, really interesting history there. So we come now to PZU, right?

And the work you're doing there. And I think in your talk at Platform Summit, you talk about this ⁓ governance ⁓ that was started. But tell us, first of all, kind of what was the lay of the land? What were some of the, you know...

challenges, what did we see, know, how complex was the environment you were coming into to look at introducing API governance. Andrzej Jarzyna: Mm-hmm. Yeah, so PZ2 is ⁓ ⁓ company with, as you said, years on the market. It created, I think, in 1803.

many, many and a lot of legacy. ⁓ And also has some particularities which come with this ⁓ business. When you a life insurance, that life insurance will last throughout the life of a person who signed it, right? It's not like a car insurance which you renew every year or a house insurance.

And that's why, for example, we have to maintain systems from the ⁓ when the digitalization first came to these kind of companies, to the banks and to the insurers. They had some systems written in super obscure languages no one understands anymore, but ⁓ we still them. There is one person who knows that language. Ikenna: Hmm.

Andrzej Jarzyna: it's spun like there are like ⁓ don't know 50 people who insurance on that system and it has to be there. So there is a lot of legacy. There is like almost technology you can imagine from this ⁓ until now. there is a lot of complexity and there is another factor which is more about communication and the company culture but it also comes from regulations.

So when we have when we talk about ⁓ insurance company It's not that like we have PZU it handles all of the different types of insurances by as one ⁓ It is into business units ⁓ which are separate companies and they cannot exchange data between them. So if you have car insurance at PZU and you have life insurance at PZU, there are two separate companies and they don't talk between each other unless explicitly say that they can. I think it's older than GDPR actually, this regulation.

So I haven't been working in insurance before GDPR, but ⁓ believe it's much than this. this creates difficulties for communication. The are very siloed, so they don't necessarily exchange a lot of information between each other. ⁓ If someone built an API for, I don't know, some technical reasons and they established some kind of standard within their own business unit, it would be very unlikely that something from that would be reused in another business unit or another team.

There are some initiatives to do this cross-team knowledge exchange. We have Architects Guild, but it... Ikenna: Mm. Mm.

Yeah. Andrzej Jarzyna: It is more about exchanging ideas and discussing ideas than to actually reusing your ideas, which is a bit of a shame, I think. So that was the state when I came. And even though my job was to do API governance, I think it was also about breaking this silo.

So without that, we cannot put something on a strategic level like... Ikenna: Yeah. Andrzej Jarzyna: like API governance, we cannot tell everyone, okay, now you have to, I don't know, put all your APIs into a catalog because everyone will be doing this in their own fashion, right? There was a good thing that actually OpenAPI was a standard 100 % of APIs were documented or 99 % of APIs were documented using OpenAPI.

So we had some start, but then we also had... Ikenna: Okay, that's good. I mean, that's a really good level for a company that size, you know. Andrzej Jarzyna: Yeah, yeah, yeah.

And it was, I think it's besides like three APIs, it's open API version three. So it's actually pretty modern. But it also comes from the fact that REST API, APIs is a thing of 2019, I think in the company. Before it was almost only SOAP.

So, so thanks like being a late adapter, they are using a more modern stack actually. Ikenna: More. Yeah. Andrzej Jarzyna: So, but yeah, there was no catalog.

We have two API solutions. Actually, we can say three because the third one is no API management. there is ⁓ no way to actually discover your APIs. And we not even talking about whether there are standards or not.

So the... ⁓ Ikenna: Hahaha Andrzej Jarzyna: Like the starting point was complicated. Not everyone understood that there is a need actually for doing so. I think everyone understood benefits of having a catalogue, right?

So the fact that you can see what's there. Although also like security policies, by they don't allow you to see stuff. ⁓ So had break this ⁓ barricade as Ikenna: Mm-hmm. Yeah, that's really interesting.

This is like a environment to introduce ⁓ API governance. What was the main driver though for the initiative? Andrzej Jarzyna: So as that's money, right? The new CEO at that moment was the person who wanted to invest into APIs because he came from more like startups ⁓ environment.

He worked for a VC, I think, with many startups and he understood the value behind APIs. his vision was to... ⁓ Ikenna: Hmm. Hmm.

Andrzej Jarzyna: to create some sort of a marketplace of APIs so that our partners, other startups could kind of buy our data or like use our data to create like fintech companies ⁓ and because we like the biggest ⁓ database for insurance things in country that was like a no-brainer ⁓ in his mind at But that was the starter, ⁓ Like when they employed me, that was the idea. But in the meantime, ⁓ had all the AI agents ⁓ ⁓ And I joined in September last year. MCP was released in October or November, right?

So the focus a little bit. Ikenna: Mm. Andrzej Jarzyna: Also the CEO changed, but oh no, 2014, 2024. 2024.

Yeah, so the board of directors changed in the meantime and also everyone was like, okay, we have AI, we have to jump on this. And without APIs being like open and accessible, we cannot actually have these AI agents because... Ikenna: So when you say last year, you mean 2024. Yeah.

Andrzej Jarzyna: where will they get data? Ikenna: Yeah, yeah. I mean, that's really interesting, right? Because on two ⁓ things coming together.

One is really the ⁓ the need for digital products, right? Digital APIs, seeing, ⁓ of thinking of APIs as products ⁓ allowing that to open new income streams with partners, with third parties and really creating that modern digital platform. Right. And then on the other hand, Andrzej Jarzyna: Mm-hmm.

Ikenna: AI ⁓ to leverage AI and give agents access ⁓ that platform in a really clean way to drive ⁓ the good stuff that you get with ⁓ ⁓ new capabilities with the agents. So those two things coming together there is just a ⁓ really driver and bedrock for driving API governance across the enterprise. Andrzej Jarzyna: Yep, yeah, definitely. Ikenna: Yeah.

Okay, so tell us the story. So how did it go? you've got the go ahead executive buy-in, go ahead to drive this API governance initiative. How did it go?

Andrzej Jarzyna: It went well, think. So it went well, although it went slower than I anticipated. But it's also like, yeah, yeah, yeah, yeah. Because, well, it's a big company and it has already some sort of culture established.

And we talked about the fact that it was not the easiest one to work with this kind of like platform initiative. So Ikenna: Everything takes longer, doesn't it? Andrzej Jarzyna: idea was to ground API governance around three principles. The is the most important by far.

⁓ They going to be adopting your things, right? The processes, which is what I think traditionally people understand this as API governance. And then the tools, because you cannot actually implement those processes with proper tools to support people who will be... following them.

So this is like a triangle in all the directions. So think good governance is about like ⁓ it easy to build stuff in a good way, right? And making it a bit difficult to make it in the wrong way. ⁓ that was our idea and we wanted to have people on board of that.

So I created a working group so that everyone Ikenna: Yeah. Mm, mm. Andrzej Jarzyna: or every area we had what 70 teams in the company, 70 product teams and around 1300 people in IT. So it's pretty big for a not IT vendor company, I think.

It's a bit less than Adidas had, but still a lot. Ikenna: Mm-hmm. Andrzej Jarzyna: ⁓ built ⁓ kind of center of excellence where it was three people working for my And then we had 30 people who were architects from different areas of the company, different domains and different teams. And we divided that big group into smaller working groups, which were working, for example, on tooling, on standards, ⁓ on testing, on the security and compliance, things like that.

So idea was that we have to ⁓ this work in groups because otherwise ⁓ cannot do it by myself, right? It would ⁓ unsustainable. Then it also gives ownership to directly, even though they have representative more than like ⁓ the whole team, but ⁓ yeah, they have ownership over what's going to be introduced in the company. And then third thing is that working big teams is not efficient.

Working like two, three, five people teams is actually pretty efficient. So that was the idea of like splitting this, but also having a bigger structure on top. So that was one of the principles. And then the second one was building guidelines because we wanted to have some sort of standard with naming, with descriptions, with Ikenna: Mm-hmm.

Andrzej Jarzyna: the way we describe models and standards use. ⁓ Ikenna: Yeah. Andrzej Jarzyna: So that was these two first things where ground's up. There is no tooling yet because had the third initiative which was crucial at this point.

It was, well, I think calls it landscaping, but it's like API discovery ⁓ in the sense of like, what APIs do we have? Which APIs go outside of your product so other teams use it. Ikenna: Mm-hmm. Mm.

Yeah. Mm-hmm. Andrzej Jarzyna: ⁓ Because if someone has like a very technical API for like internal stuff, I don't want to care about this, right? Like do it the way you want to do it.

⁓ But it doesn't have business value. So we focused on those which go outside of your product, other teams use it or people outside. Which API management do you use? How do approach authentication, authorization?

Because there are different models in the company. ⁓ Ikenna: Yeah. Mm-hmm. Andrzej Jarzyna: not one, like it would be too easy.

⁓ And that also us what kind of like patterns do people ⁓ already to. So that's how we learned actually that open API is a standard, de facto, even though no one ⁓ said ⁓ So ⁓ with we were able to move to like the second phase. Ikenna: Yep. Mm.

Yeah. Hmm. Andrzej Jarzyna: and build API guidelines. And that was like a big lesson for me, actually, because my approach was that like, let's build them together, right?

Like we are here together. ⁓ we established this team. We have the ownership. Let's work it out in this like group of five.

And then I was like working the team and ⁓ they like, well, you should build this. I was like, no man, like we should do it together. I was like. Ikenna: Okay.

Andrzej Jarzyna: I don't know what to do. have no experience. So I was like, okay, this actually makes sense. And what I did is like, built first version of API guidelines in sort of autocratic way, right?

Like I'm talking about the democratic process here and like having a contract, well, whatever for everyone. But I did this in more ⁓ autocratic showing them what I think is a good practice. Ikenna: Yeah? Yeah.

Mm-hmm. Mmm. Andrzej Jarzyna: The guidelines were kind of minimal so that everyone would be able to follow them because I want to have this minimal surface covered. Leave a lot to the teams, nudge them into good directions, but require only a few things.

Like we require open API version 3. Ikenna: Yeah. Mmm. Andrzej Jarzyna: We require APIs to have descriptions and we require them to follow certain naming conventions and that's basically all.

⁓ Not too much, the rest is like nudging. So in terms of API guidelines, like it's a warning, right? Like you should do that. You don't have to, but you should.

⁓ And this worked, we built later some tooling for that. So we built a spectral rule set. Ikenna: Mmm. Yeah.

Yeah. Andrzej Jarzyna: and put it into CI-CD pipelines. because it's spectral, it can be used locally, ⁓ because it's spectral, it can also be used in the pipeline. So you have this instant feedback.

When you work on a product, it's very important to have instant feedback. Otherwise you will be like doing something, then ⁓ trying deploy it and the security team will come like, ⁓ you cannot do it ⁓ this Ikenna: Yeah. Andrzej Jarzyna: Why? ⁓ I won't tell you, you have to figure out.

Yeah, so we build it as a plugin for Visual Studio Code and IntelliJ. we also put it to CI CD pipeline. So we have a quality gate blocking the APIs don't comply with our basic rules. Ikenna: You Andrzej Jarzyna: So, yep.

Ikenna: That's, really interesting. When you were talking about API standards there, ⁓ starting ⁓ I that was ⁓ a interesting approach because, and ⁓ I this tension, because on one hand, you're like, Andrzej Jarzyna: Mm-hmm. Ikenna: start small because we can evolve from there and grow from there. But the other hand is like, Hey, there's all these rules.

I know, I really know we're going to use, right? I know we're going to use all these rules in future. They're going to be helpful for, you know, da da da da da. And we really need to build lint in and things around them.

And it's like, how do you see, know, you've gone for that approach of like start small and grow, you know, how do you see, how do you see, how do you balance that tension and how do you grow and make sure that Even if we start with small, like we don't end up small, we actually end up growing those standards as a teams, more mature in understanding what guidelines they need. Andrzej Jarzyna: Yeah, I think this ⁓ be done in two ways. The way we are trying right now is more through nudging.

besides these creating processes and guidelines and spectral, our responsibility is to curate the tooling. So choose which tools do we recommend as this like API center of excellence. customize it. ⁓ Spectral is a good example of that.

Like we build ourselves our internal rule But it's ours kind And by choosing tools, leverage certain things in your open API contracts, they will be kind of nudged into direction of having them in your... contracts because otherwise the tool won't be able to help them. A great example is actually examples. If you want to have mocks, the best way to have mocks is to put examples in your files.

If you want to have some sort of simple provider-side contract tests, you should also have examples because we will be able to leverage tooling and generate tests and on. You want to use our ads and processes, put examples. in your open API, that's the way to go. So can do this way, but you can do another way as well.

So you can try to extend with like a more democratic, I know, appeal maybe. So discuss your team about which rules make sense to like jump or bump them into higher tier. So we had... this example with problem details standard.

So when I build the rule sets, I said, guys, this is, we have to do it, right? Like you have to, this is And then they were like, but tools don't support it. And like, I would have to change a lot of stuff for new APIs is good, but like it doesn't work backwards too much because it's ⁓ a, it Ikenna: Yep. Andrzej Jarzyna: basically how our API is designed, right?

So we actually changed these problem details to be not required, but like something which we encourage people to use, we show some tools ⁓ that leverage it. But discovered that we plan to bump it up. So whenever you have time, resources, try to use ⁓ details, will benefit you. Ikenna: Yeah.

Yeah. Hmm. Andrzej Jarzyna: And if you want to be AI ready, ⁓ even better, like more important. You should definitely ⁓ problem And that applies to other things as well.

This is like the one which I think is the most, ⁓ the brightest on ⁓ our site recent months. ⁓ Ikenna: Yeah, yeah, yeah, absolutely. Now talking about tooling, I think this was from your presentation, ⁓ showing some of the you have in your CI pipeline, you know, using a spectral there, which is off your ⁓ API style guide or guidelines. know, chain checks, contract tests and all that stuff.

How has this for you in terms of ⁓ ruling out that API governance? Andrzej Jarzyna: So think this is sort of an enabler of proper API governance. This process is, as you say, as you see, like GitOps process, GitOps DevOps driven. These two vertical lines means like blocking, a blocker, right?

So here we see that When you do a pull request to your repository, there is a process which verifies or validates your open API file against our spectral rule set. If it fails, well, it fails merge or pull request. Then we check it for breaking changes. ⁓ This only for new API, existing APIs, not new ones.

So ⁓ we validate the changes made in the file correspond to the version change name. So if you introduce breaking changes, you should also tell that to your consumers by bumping the major version. We use semantic versioning. If you do smaller changes, then you should bump a minor or a patch version.

The contract testing is something which we are still working on. Ikenna: Mm-hmm. Andrzej Jarzyna: and it's actually not on this site. I learned that after.

yeah, the contract testing should be after deployment, right? Because you check contract against implementation, which is not ⁓ deployed. ⁓ yeah, we are using Microx right now more in like proof of concept testing to validate. Ikenna: True.

Yeah. Yeah. Yeah. Andrzej Jarzyna: whether our API contract is what was coded, what's deployed on our servers.

And then contract repository ⁓ ⁓ central contract where all the APIs which were validated for breaking changes and guidelines, end up at. that's it's not ⁓ really the of because the source of truth is the repository. But this is the place where ⁓ Everyone can see your API, read the documentation, get like developer portal as well. Right?

So this is pro we call contract because it's programmatically accessible from outside and it contains all the catalog of APIs and the developer part is kind of a on top. It's just ⁓ the solution we have Ikenna: Yeah. Okay. Right.

Andrzej Jarzyna: this way that we can use it as developer portal. But really, repository contracts or the catalog, I think one of the most important parts of the whole API governance ⁓ initiative. If have no visibility, you have no governance really, because you cannot apply it to the whole ecosystem. You will be just like shooting all over the place.

Ikenna: Mm-hmm. Andrzej Jarzyna: and super easy how to do it. You can even just get a mono repo where you dump all the APIs. The only thing is that it has to be dynamic, so it has to be up to date.

So you should put it inside process like this one, so that the catalog is updated time an ⁓ open API file is Ikenna: Hmm. Yeah, so get the CI-CD pipeline to push into that. ⁓ Andrzej Jarzyna: Yeah, we have also API management now being put kind on top of that, right? So like when something is deployed and tested, then we can put it outside automatically from the pipeline well.

Ikenna: Okay. Yeah, yeah. I want to take you back to something else you said, which is around ⁓ API contracts. Again, ⁓ that driver about the organization adopting AI ⁓ and them having to consume these API contract files.

When you talk about AI ready API contracts, what did that mean for your organization ⁓ what did you need to do to the contract files to get them AI ready? Andrzej Jarzyna: Mm-hmm. So when all the craze about AI started, I was kind of... I wouldn't say afraid, but worried a little bit of where it will go, in which direction, because honestly I didn't know that much about the problem.

But then I learned that... how they work actually, right? Especially if we talk about AI agents, what they do is that they read some information and give them, building context, and basing on that context, they reason what's the most probable thing that you ask them to do, So a year and a half, a year ago, all this talking about MCPs and what it is and like exchanging APIs. There is no ⁓ need for APIs anymore.

Everyone will be using MCPs That was a little bit unnerving, but then yeah, what's important for AI is to understand your API, right? And MCP is a sort of like natural language way of them to understand your... your API. But if you use standards, well, maybe going a little bit back, how they going to understand your API, right?

Like they were trained ⁓ on many on some RFCs, on what's available and what people use in repositories, ⁓ what repeats itself ⁓ the standards, right? that's why they are called standards because they Ikenna: Hmm. Andrzej Jarzyna: they are most common things you find. If you have problem details that will occur in many APIs, your custom solution won't, right?

So if you follow these standards, AI agent figure out that it's a standard. If you have an open API file and give descriptions ⁓ of what API is for, ⁓ what your endpoints are, kind of resources are they, what your ⁓ operations on those That will give probably enough context to the LLM it understand what has to do. If you just put an open APA files with no descriptions or with like just minimal descriptions, it will be like... giving it to a junior developer from another company and telling integrate with this API.

Like, I don't know what API does. ⁓ like in your is not everything. Like you have to understand what can you achieve with it. ⁓ And ⁓ doing some tests with this.

Just like ⁓ a random open spec file. Ikenna: Yeah. Hmm. Andrzej Jarzyna: is kind of understandable by agents, but it's like 70-80 ⁓ % of accuracy.

you put what we were ⁓ advocating with API governance initiative, so putting descriptions, using standards, examples, that bumps the accuracy to almost 100%. That's like 99.6 or something like that, from our test at least. ⁓ Ikenna: Mm-hmm.

Wow. Andrzej Jarzyna: So ⁓ we were talking to do is I think for the standard scenarios of executing single call, that's what's needed. ⁓ MCP it's great, but it has limitations as well, right? If you have a production ready API, you don't probably want to put it through an MCP.

You have... 100 requests per second, MCP won't be able to handle that at all. Ikenna: Mm. Mm.

Andrzej Jarzyna: So, yeah, that's my take on AI readiness. It's simpler than we think. ⁓ Ikenna: Yeah. Did you ever have any problems with like drift between the contracts and the actual API behavior, say with missing information on the open API contracts, know, missing properties?

Andrzej Jarzyna: Yes, well, that's... This is pretty common, right? Like, I think every company will have some API with the drift, even best ones, unless they have only one API, then maybe not. But that's ⁓ we ⁓ implementing contract testing part, that we want to validate that the implementation the contract.

Ikenna: Hmm. Yeah. Andrzej Jarzyna: We still don't have it, but as I said, like governance API governance is a program which will last forever, even it doesn't have to be like openly or API governance, no? Like making your API standardized and well-designed, that's a process and you have to also change it with time.

Ikenna: Mm-hmm. Yeah, yeah, yeah. Andrzej, let me show you two things ⁓ talked about again on your talk. So they are about, you about complex route documentation.

Obviously in the insurance domain, there are workflows where you need to talk to different endpoints to achieve an outcome for the user. So you talked Andrzej Jarzyna: Uh-huh. Ikenna: those workflows with something like Arasso, also ⁓ Hypermedia as engine of application state and all that. These are alternative to that defining those complex routes for agents.

Again, tell us your experience about this, about your experience with Arasso, Heteos. kind of where the organization is leaning and what you're finding with these different approaches. Andrzej Jarzyna: Yeah, so those two solutions kind of solutions to the same problem, I think. Just in a different way, Hatos ⁓ how REST was designed, right?

Like if are purists, we won't call any API ⁓ REST it have hypermedia, right? But well, I think at this moment, we are kind of beyond that already. Ikenna: True, yeah. Andrzej Jarzyna: What gives you is that the API is self-documented, right?

Like you only have to know how to access the API and what's endpoint there. that, you will get all the first contextual data or metadata you will figure out what you can do with that. So we can kind of follow and explore your API. or the API you want to use.

And that's great for agents. It's also very good for coding complex processes. Hypermedia was not adopted because it actually ⁓ first makes design of much more complex. But I think the biggest was the complexity of clients ⁓ multi-fold.

It's bigger. And agents actually ⁓ for understanding hypermedia because, they ⁓ very well with dynamic text right? And Aradzo is solution similar. problem, it's simpler, I think, and you don't have to change the design of your API.

⁓ Ikenna: Yeah. And sorry, just to let listeners know again, Aradzo, it's a workflow description that's provided by the OpenAPI Initiative. And you can go to the OpenAPI Initiative website and learn all about Aradzo for people who are not familiar with it. So sorry, do carry on, Andrei.

Andrzej Jarzyna: Yeah, thanks for this. Yeah, I sometimes forget that not everyone knows. Yeah, Aradzo ⁓ your open API specification document. And think async API spec soon, it's coming in the next version.

So you are to describe deterministic processes using Aradzo. So... Ikenna: Yeah. Andrzej Jarzyna: workflows where you need multiple steps.

And coming back a little bit to the AI accuracy thing, I don't know if you've heard ever about Berkeley function calling leaderboard. is, I don't know if it's experiment. It's a page which tests... accuracy of different models, different LLM models.

And you look at accuracy of single shot, so this is like a ⁓ one-off And in context of APIs that would be just calling one operation. And they have pretty high accuracy. They have around 90 % of accuracy, figuring out they have to do and how they understand the response. we can bump it much higher if we describe the context properly, what we talked about before with OpenAPI spec, but they are not really accurate if you give them multi-turn function.

So if you have ⁓ do a workflow, so the best models have 60 % of accuracy there. But if you describe this ⁓ workflow a ⁓ deterministic way using something like Aradzo, the accuracy... goes up to over 90%. So, aretsu is very understandable for AI because it's ⁓ a format of description, right?

And we also did tests internally, trying to model some workflows internally, which we had, and were using multiple APIs actually, we don't have simple workflows. ⁓ worked great. Without that, the AI was not able to ⁓ do more than one call or ⁓ two sometimes. But Aradzo, it was very accurate.

The problems when you go into edge cases because Aradzo is not like a tree structure. It's more like a list. Ikenna: Mm-hmm. Andrzej Jarzyna: Right?

Like where you have one node after another. But it's good enough for describing the happy paths. And I think also it can be a very good tool for testing, end-to-end testing. You can test the whole process.

It's actually describing not necessarily happy paths, right? So that's something which I... Ikenna: Yeah, yeah, yeah, yeah. Yes.

Yeah. Andrzej Jarzyna: I haven't seen yet in any tool, but maybe I don't know the tools enough it's going to come, I think, in the future. Ikenna: Yeah, think so. think ⁓ Redocle has something out there doing that kind of, you know, end-to-end testing with ⁓ Aradso and the kind of Redocle CLI, think, does that.

So, yeah, absolutely. ⁓ there. But mean, ⁓ do what's your prediction on the future, Anjay? Do you see Aradso, like, do you think it's promising for those use cases you described?

Andrzej Jarzyna: Mm-hmm. I believe so. So you go to a lot of conferences, more than me. But what I notice when I go to these conferences is that people talk more and more about Arad.

So the same happened to OpenAPI Swagger before, right? Like when something gets momentum, people start to talk about it more and more. Problem details was also like 2017 it got. Ikenna: Hmm.

Yeah. Andrzej Jarzyna: got traction and see it happening to to Warats as well. Definitely is also driven by companies which have some interest in that but that's not bad right like if someone is an adopter and wants to make business from it if it's good for whole community it's good for them it's good right like I want tooling and on to evolve. Ikenna: Yeah.

Andrzej Jarzyna: ⁓ So there are some companies which promote Aradzo quite a lot. But also some companies like us for example, because we also started using Aradzo, will adopt ⁓ and I it help to solve this multi-turn function calling problem. ⁓ And it's very simple. Ikenna: Hmm.

Andrzej Jarzyna: It's very simple. You don't have to change anything you have. You just build something on top of your existing open API specification. Well, maybe you have to add operation ID.

the only thing, right? ⁓ Ikenna: Yeah. That's always a good thing to do. Yeah, cool.

as we wrap up, as we wrap up, Andrzej, if someone, ⁓ you imagine a kind of an API product owner or API platform team or API architect, someone who's really starting out in API governance, you know, ⁓ at the of launching their own API governance initiative, what tips would you give them? or you know on day one, what tips would you give them to get started with? Andrzej Jarzyna: I think I would start similarly as I started here at BZU, although we've like some lessons learned, right?

Like I engaging people, that's the most important thing. You cannot just invent your own API governance because you think it's good. It has to be good for people who will be using it, right? Even if it's a little bit against the established best practices.

Maybe they have a little bit different best practices. You have to take it into account. So listen to people. You also, if you go into a big company, you have to have some political leverage as well.

Otherwise will be difficult to implement your ideas because there won't be resources ever ⁓ to do ⁓ But politics is also people. ⁓ Ikenna: Mmm, yeah. Good point. Yeah.

Yeah. Andrzej Jarzyna: people are the most important and then do by, I mean show by doing rather than telling and that's lesson I learned ⁓ with my job is that first do something minimal and show them how ⁓ things like guidelines work, what kind of processes, what kind of tooling there is, how they can approach, I don't know, API design process. So if you have guidelines, you can actually use AI and create open API spec with code, with, I don't know, cloud code, right, ⁓ something, generated with your guidelines as the context.

And it will be probably compliant with your guidelines. So show them how to do it and then they will give you feedback on direction they want to go. This is, think, the core ⁓ of as an initiative. Ikenna: Yeah.

Yeah, really great tips there. Really great tips there. Thanks. Before we go, I just want to show book, RESTful Design Patterns and Best Practices.

Yeah, where we ⁓ get your Andrzej Jarzyna: one thing is that I didn't write this book alone. I had a co-author, Samir Amzani. We together at Adidas. So he has very similar experience to me, although we at some point we moved into different companies, we had a little bit different ⁓ history of careers.

you can get book ⁓ at Amazon or at Pact website. And there are some resellers different countries. but only in the form of ebook. So if you want to have physical copy, think it's only Amazon Impact.

Ikenna: Thank you so much, André. ⁓ And just before we go, if people were to contact you, where can they find you? If they want to contact you about anything, socials, anywhere. Andrzej Jarzyna: Yeah, I think the easiest is LinkedIn.

And it's easy to find me because, well, it's just my name. I hide ⁓ under names. Yeah, ⁓ post some stuff about ask questions to the community. And you can find on conferences, mostly the European ones.

⁓ So API days or platform summit. Ikenna: Yeah. Yeah. Andrzej Jarzyna: Yeah, and I will be trying to talk at these events this year, so yeah, we see each other there.

Ikenna: Yeah, lovely. André, it's been a pleasure, absolute pleasure to have you on the podcast and just hear about your experiences at PZU. yeah, I get to know about what you've done there. And yeah, I look forward to seeing you again soon somewhere, somewhere.

OK, thank you so very much for being on the call. Yeah. OK, see you later. Cheers.

Andrzej Jarzyna: Thank you. Yeah, thank you so much. Thank you so much. Have a great day.