Redocly, OpenAPI, and learning to Moonwalk with Lorna Jane Mitchell

[00:00:00] **Phil Sturgeon:** Hello everybody and welcome to another episode of APIs You Won't Hate With me, Phil Sturgeon and no Mike, the co-host. So I'm still muddling through trying to figure out what buttons I meant to press, but slowly get in the hang of it. And thankfully, I'm joined today by Lorna Mitchell. Say hello,
[00:00:17] **Lorna Mitchell:** Hi. Hello. Happy to be here.
[00:00:20] **Track 1:** Nice.
[00:00:20] How's it going? I think you've been on the podcast before. I meant to actually look that up back in the day talking about something or other,
[00:00:26] but if not.
[00:00:27] **Lorna Mitchell:** I actually don't think I have, I, I have written for APIs you won't hate, and
[00:00:31] I like to write. I should do that again. I'm not sure we've done the podcast thing before.
[00:00:36] **Track 1:** alright, well either way welcome. And for folks who dunno who you are, could you describe a little bit about yourself?
[00:00:44] **Lorna Mitchell:** Sure. I am Lorna. I am currently VP of Developer experience at Redley. But my background is I am been a software engineer for a long time. I'm a conference speaker. I'm a published author and I am mad passionate about APIs and [00:01:00] open source.
[00:01:01] **Track 1:** Ha, sorry, I was just doing some research live on a podcast like a real professional . Fantastic. Yeah, no, your, your name pops up everywhere in open API. And yeah, you were pretty helpful in the open API 3.1 stuff when we were trying to get all of that across the line. And what was it? What was the main thing you were working on?
[00:01:20] I completely forgot because I, my whole thing was like, Jason Schema needs to match open API or what are we even doing? But you were working on other bits?
[00:01:27] **Lorna Mitchell:** Yeah, so for 3.3 0.1, which is when I really came into working on open API itself, I was working on the webhooks thing.
[00:01:34] That's when I was at Vonage and with their two-way messaging APIs, you need webhooks callbacks are not the same. So that was I in my not humble at all opinion. One of the best things about the 3.1 release of open API.
[00:01:49] **Track 1:** Absolutely. I, I forgot that. Was that you that helped push that through and yeah. We're using it, using it right now for some webhook stuff that protect Earth's doing. So yeah, it, it's really nice that that's there. [00:02:00] 'cause it was always a bit weird trying to hack that into callbacks. You'd have to like.
[00:02:03] Pretend you'd have to make some sort of fake URL called like web hooks or something, and then just kind of pretend what it was for. But no, this is, it's useful to be able to say, sometimes there are messages that are gonna come from this server that aren't simply in response to a request you just made.
[00:02:18] You can register for a web hook through the website or whatever. I mean, Shopify's super weird. We're we're registering for webhooks. With them through like a CLA command, which is awkward. But then it will just forever spit web hooks at us on, on topics that aren't related to a single thing. So it's really handy to have that in there.
[00:02:35] **Lorna Mitchell:** Yeah, I think there's loads of use cases. You know, callbacks gave us half of it. You know, it's in response to an incoming request, but webhooks lets you have that payload going across in response to something else.
[00:02:48] **Track 1:** Yeah. Brilliant. And so you've been involved in loads of stuff with Open api. I, and obviously you're working for Redoc re Dock Lee now. But yeah, we, we, we've both been kind of in the same spaces working on trying to make like [00:03:00] a sidekick for open API. Right. I did
[00:03:02] that recent blog post about how Redoc Lee has kind of got there now, but you were around in, in Specky trying to make that useful.
[00:03:08] And, and spectral. And can you just talk a little bit about those tools and where you feel like they fell short and you know, what they're good at, what they're bad at? And then, and then what's going on with Redoc Lee? And its kind of open API psychic now.
[00:03:22] **Lorna Mitchell:** Yeah, no, I think, I think there are so many great API tools now, but it's not as if they just came out of thin air now, like they're ready to use now. Like you say specky I think was one of the first ones that at least I knew of, which really helped me to validate and check things. I'm not sure I was customizing it a lot.
[00:03:42] And so that can be quite frustrating if you're using out of the box rules. I think too many people do that and then it can be a hard experience.
[00:03:49] **Track 1:** Yeah,
[00:03:50] I think specifically I think you were the person who, well, a lot of people really hated all of the default rules about like tags and stuff.
[00:03:56] But I seem to remember you giving a bunch of feedback about that. Like why is [00:04:00] it constantly complaining that I need to use tags, I don't actually need to use tags, and that was just in
[00:04:04] there for some reason.
[00:04:05] **Lorna Mitchell:** I, I, think it was an API with like two end points. I, I really don't need to tag them, but thanks.
[00:04:09] And then we used Spectral a lot. I realized the other you'll love this. I realized the other day that my personal blog, so that's Lorna jane.net will put it in the show notes. My personal blog has instructions of how to link APIs with spectral. But it does not have how to link them with Reduc, CLI, which is, that's what I do
[00:04:29] now.
[00:04:29] **Track 1:** time for an updated blog post. I think
[00:04:31] **Lorna Mitchell:** definitely. Well, and we'll just write all the blog posts for
[00:04:34] all the tools because I think they're all great. But yeah, I used Spectral and that's when I started customizing rules. I was working for Vonage and what's interesting about this is I think I did Specky when I was working for Doing like integration consultancy. I, I worked on spectral when I was at Vonage. They're an API provider, so that, but they have a lot of APIs and they're quite different from each other. So working [00:05:00] on spectral there and making sure that we're enforcing that consistency. And, you know, I'm not sure developer experience was a buzzword then, but that's how I would call it now. In between. I worked at a cool, another cool Cloud SaaS and they had an API and that's when I started using Redoc Lee tools because I really enjoyed their linting and of course Redoc API reference documentation. So now I'm out redly working on Redoc Lee, CLI, which as you say is the API sidekick.
[00:05:34] And I think I'm still seeing some of those same problems like. People use the recommended rule set and then tell us it's wrong. it's, you need to cus
[00:05:42] **Track 1:** Yeah. Yeah.
[00:05:43] **Lorna Mitchell:** 1 0 1 run it. We'll give you some good feedback, you know, and I'm seeing some more of those upload your API and we'll tell you what you've done wrong. Like Yeah, but every API is different, so you need to customize your rule set and use it yourself. So Redly CLI is open source. [00:06:00] It does do the linting, but it does a couple of things that I would describe as Either side of that in the process. One is it has functionality for splitting your open API up into multiple files so you don't have to deal with a hundred thousand lines of diff. You can, and also you can look at like, which segments changed and that can be easier for review. It's also easier on your editor. And then you
[00:06:27] can
[00:06:27] **Track 1:** yeah, whenever you are trying to like send a pull request on a file that's 10,000 lines long, firstly it's just not gonna show you the preview half the time. And secondly, it's more, more likely to conflict. 'cause two people worked on something completely different, but it didn't realize it was completely different and therefore, but,
[00:06:42] **Lorna Mitchell:** Yeah, and it's harder
[00:06:44] to reason about which sections should have changed
[00:06:46] when it's just one long thing.
[00:06:48] **Track 1:** I think before, before we go past it too quickly. I think one of the most impressive things, so when I was doing the review of re doley I was like, okay, yeah, I know what this is about. They got like a liny thing and they got like a Bundy thing and they got like [00:07:00] a preview docs. These are all good, these aren't new things.
[00:07:02] They've been kind of brought together in a, in, in one new tool that does a whole bunch of things, which is great. But what I was really, really excited about discovering was the split thing. 'cause the number of times, like I'm looking at some massive open API file going, ugh, like it's been generated from HCTP or whatever.
[00:07:18] You're kinda like just, you're just staring at that massive far going. This is gonna take some time. And I think like stoplight studio at some point had vaped some functionality in like, move this to a model. But then the button broke and it was disabled, and I begged and begged and begged to get that button put back in and they were, oh, we're too busy.
[00:07:34] I was like, no, because taking a, taking a giant opiate open, API file. Like, I feel like no one's doing enough refactoring,
[00:07:40] automating, refactoring, like move this to move this to models. These two, these two in place things look the same. Change that to one ref. And I think, you know, split, split does a lot of that.
[00:07:51] They, they noticed that you've got refs and they were like bung 'em off into files and it did also notice that two things were the same thing
[00:07:57] and put them into the same file. And I was like, God damn, [00:08:00] that's useful.
[00:08:00] So I was really glad to see that even though it's like a, a undersung kind of feature.
[00:08:05] Yeah.
[00:08:06] **Lorna Mitchell:** it is. But I think it does really help, and particularly As we mature in our API practice, it's not just about, I wrote an open API file or I generated one. There you go. I've done that tick You know, those are living, changing documents and so the maintenance aspect gets quite big. So yeah, the, I think the, the splitting bundling and we also have join, so where people are maintaining different, every
[00:08:31] team maintains an API each, but you publish it as a single surface that's actually really messy.
[00:08:38] I've seen some horrible merge. Attempts and
[00:08:41] join attempts to handle that, which I think is really nice. So from an API management point of view, the other thing that I love about Reduc, CLI, which I am now seeing in other places, but Reduc CLI has had it for a long time, is decorators the ability to
[00:08:59] repeatably [00:09:00] transform something. an open API document so you get something it's not perfect or you want to add something for the next stage in your pipeline. There's a decorator's set. There are some built-in decorators, but you can also extend it by saying whenever you see a, I dunno, an an operation parameter, do this.
[00:09:23] **Track 1:** Interesting. Like, like what? Make it more tangible for my struggling brain,
[00:09:28] **Lorna Mitchell:** So we do things like you can add, you can replace all the descriptions. This, this operation Id should have this description. This one should have this description. So if
[00:09:35] you're getting poor quality generated content or you wanna add, you know, the descriptions in open API support markdown, so you can add really beautiful, rich links and whatever.
[00:09:49] Do you want to maintain that in your source code? When you are generating from that, you know,
[00:09:54] **Track 1:** Oh, I see.
[00:09:56] Yeah.
[00:09:57] **Lorna Mitchell:** you are maintaining the YAML for the markdown [00:10:00] in your source code. I just, I do understand why people don't enjoy that.
[00:10:05] **Track 1:** Absolutely. Yeah. I think it's the, the people that advocate most for the kind of code first B it all into annotations in our code approach are the people who aren't ever gonna put very much effort into their documentation. And therefore you know, you're not, you're not gonna see these like . Hundred lines of markdown showing up in the source code purely because they wouldn't bother to write it and the tech writers can't be faf to go and like get in there.
[00:10:31] Um,
[00:10:31] **Lorna Mitchell:** Not even have access.
[00:10:33] That's really common. You get frustrated tech writers who could add really great, you know, descriptive content. Example values.
[00:10:41] If it's generated from source code and not, and they're not giving access to the source code, it's very difficult to include that. And we're starting to see tools as well.
[00:10:49] Obviously the documentation tools, Redoc and friends are the very good API Documentation tools are available.
[00:10:57] **Track 1:** Standard BBC response. Yeah.
[00:10:58] **Lorna Mitchell:** Well, I just feel like, I [00:11:00] don't mind which one you use, but please give me some documentation, you know,
[00:11:03] **Track 1:** Yeah. Yeah.
[00:11:03] **Lorna Mitchell:** And the SDK generators as well. You know, we've just seen speakeasy release the overlays tool, Because their tool does better with some added metadata and you don't wanna
[00:11:14] maintain that in wherever upstream your open API. Things are coming from.
[00:11:19] **Track 1:** Great. Well that brings us on nicely. So I've been meaning to pick your brain about overlays a bit 'cause it's, it's something that there's increasing interest in. I mean, I, I work with the, the folks at Bump as well, and they were asking about, about a bit more about overlays and there's a lot of people in the docs space who were interested in that idea for exactly what you're saying.
[00:11:36] Like, if you know the, the code first, people dump out some open API. And it's whatever it is. And if you edit it, then it's just, you know, gone the next time they dump it
[00:11:46] out. Or you've got the people that are design first where the, the YAML is the source of truth and they do all their edits and, and that's that, and that's probably a little bit easier to add things into.
[00:11:55] But then maybe you are trying to expand somebody else's published design first. Stuff [00:12:00] that you don't have any control over. So there's this kind of constant idea of taking . Some open API and then like programmatically adding stuff to it for whatever reason. Tech writing, you could do translation, you could add a bunch of stuff in.
[00:12:13] I've, I've seen your name come up for quite a few blog posts and overlay overlays. And while I was doing some research, I noticed the folks over at Redoc aren't quite so impressed with it. So I was wondering if you could explain where it all sits.
[00:12:24] **Lorna Mitchell:** controversial?
[00:12:25] Yeah.
[00:12:25] I think so. There's an older blog post on the Redoc website where Adam, you know, It didn't love it when he saw it. It's, it's not a brand fresh site, but it is top hit for overlay. So it's
[00:12:39] not a secret And I think the point there is a good one, that it's yet another complex structure.
[00:12:47] We've got a specification with no tooling at all, and it
[00:12:50] requires use of JSO path. Now, if you've been using Spectral, that is very JSON path heavy.
[00:12:59] **Track 1:** [00:13:00] Yeah.
[00:13:00] **Lorna Mitchell:** But v Doley, CLI isn't, we do that by considering the open API as like a tree structure and the different data
[00:13:10] types. So everything's very type aware. And you can filter on fields and it knows, oh, this is a parameter you know, it'll have an in then We don't, with JSON path, it's just blind data structure. So we don't have JSON path currently in the Marine Dole CLI ecosystem I don't think at all. And so that extra learning curve, you sort of think, well, I don't know who could use this. Like it's a good solution, but there's no validator for the format. And the learning curve puts it beyond a lot of the users that
[00:13:44] at re doley we're trying to enable.
[00:13:47] **Track 1:** Right. And so I think when we are talking about the use cases for decorators, like overlays kind of intended to be a more generic implementation of that, that
[00:13:55] anyone could theoretically use, whereas decorators is more of a like redly feature.
[00:13:59] And [00:14:00] could theoretically be, you know, ji to, to be the same thing.
[00:14:02] But what, what you're saying is yeah, the. right now. Overlays are designed to use JSON Path and for anyone who's not familiar if you've been using Spectral yet, then yeah, that's, that's the absolutely batshit bunch of things. You're typing into those rules to try and make anything, make work. Make work.
[00:14:19] You can tell I'm tired. I was saying before the show, I've just come back from API days and, and normally API days gets you a hangover, but this time I've just been like sick for a couple of days and now I've just not slept. I decided to go and get myself into a hotel room early and then like got into bed at eight o'clock and there were just like homeless people screaming outside my window until 4:00 AM and then the fire alarm went off at 8:00 AM and I'm like, what is reality?
[00:14:44] So, yeah, JSON Path is even more confusing than my brain right now. And basically you have to kind of tell it what you would like to filter through, kind like a CSS selector but for js. And then, so JSON Path doesn't have a standard. They're kind of working on one, but it's not there yet.[00:15:00] And so much like what markdown had, like markdown plus and a million different markdown flavors.
[00:15:05] JSON path now has JSON path plus, which stoplight was using for quite a long time and, and used as the main thing for. For spectral rules, but then that wasn't quite enough. And then like Nier appeared, which is Jason Path Plus with some other bits and like it's even Jason Path Plus not Nier is a mixture of a lot of just squiggles and doodles and back ticks.
[00:15:28] But also you can bung red rejects in there. So you can kind of say, I would like to dot gets you into the property of something and then square brackets can get you into like the array of, of something. And then there's like stars to say all of them. And there's tilts to say, parent, and you can kind of fetch all of the headers where the parent is on this and the, the name begins with an X and you can do really powerful things.
[00:15:54] But it's . Almost impossible in any sort of . [00:16:00] I've made lots of spectral rule sets because I built an NPM rule set and, and I built an NPM test suite using jest so that I can type in these crazy things and go, am I close yet? Am I close yet? Am I close yet?
[00:16:12] And the result will show me what I've done.
[00:16:14] But most people are just writing a YAML file. And, and that doesn't work. So you have to like, literally switch over to your terminal, run it, and it just blows up at you in strange ways. And it, it can be very hard to do. So it's one of the things I really appreciated about about Redoc Redoc Lee, CLI was the, was the switch to using just named selectors.
[00:16:34] So you can say like. Header instead of going like, you know and I think spectral iss trying it, it made early attempt to fix that by adding aliases. But I'm just going, going off on a bit of a tirade now. I've gotta get
[00:16:47] some stuff off my chest.
[00:16:49] **Lorna Mitchell:** Carry on.
[00:16:50] **Track 1:** The roadmap for aliases was powerful and impressive, and I've smoked to Smart Bear who have now inherited this to try and get
[00:16:56] this back on the table.
[00:16:57] But basically aliases, the idea was [00:17:00] let's come up with a list of aliases. Common open, API, aliases common A and KPI, aliases, and then people can use those instead. So instead of dollar. Which is root and then paths, brackets slash post you, you would just say like you would just say paths and then you could do the square bracket slash post to pull out all the post ones.
[00:17:19] So you would cut out a lot of the nonsense by using aliases to replace a certain chunk of of the path. Whereas I think Redley would've said, you know, paths and then you would have. Header if, if, if post or something, right? So yours is more of a DSL approach, but aliases seemed like a good step forward.
[00:17:39] And yeah, the, the aliases ended up getting defined in the core rule set of like the core open API rule set. And they weren't extendable. So if you extend the core open API rule set, you can. Get those aliases out, they're only available inside the place. They're defined.
[00:17:59] So that meant [00:18:00] you couldn't actually use those to help.
[00:18:01] Like no one using, no one writing their own rule sets, extending open API or no one writing their own rule sets at all, could use those aliases
[00:18:08] unless you copy and paste them. And so I'm, I've been suggesting that like not only should they be extendable, but they should be defined in like the format. So you should, you know, anyone using the open API format.
[00:18:19] Whether it's the core rule set or not, you should get those aliases. But that's, that's a bit more of a, like a, a roadmap. One day they might fix it kind of thing, but
[00:18:28] I,
[00:18:28] completely recognize the need to not Jason path and therefore avoid that entirely in overlays. Right.
[00:18:33] **Lorna Mitchell:** yeah. Well, I don't think it is avoidable in overlays. And I feel a little bit like I've done it, an injustice there. Like leading with that, leading with that negative, the controversial blog post. You know, not everyone's a fan. I really think that overlays. Solves a real problem. Like I see this all the time we just talked about when it's generated from code and it hasn't got enough anything. I'm also seeing much more [00:19:00] complex pipelines. Now. People have multiple teams maintaining different bits of the a p surface. They all ship an open API. We join it into one, and then the, the downstream outputs, whether that's documentation, SDK, generation API, gateways, like whatever. All of them need their own enrichment and overlays solves that problem where you don't have to, you can just, yeah, add a translation, add an example, add the hint for the correct data type for the target language in the SDK and the team that deals with the SDKs can do that.
[00:19:37] We don't have to go all the way back in a, in a, in a big organization that's hard
[00:19:42] to find. The team that maintains the thing. That lives in the house. The Jack bill, right? So ,we, we can do that here. Overlays solves that problem. I don't think it's a coincidence that one of the implementations, there are not many [00:20:00] overlays, implementations. One of them is mine. We can link to it. It's very hobby.
[00:20:05] I just, I, this is how I get things out of my brain. I had to write code that did it so that I could look at
[00:20:10] it. I need to
[00:20:12] do
[00:20:12] **Track 1:** that's really helpful. I, I remember, I remember reading the, the official page of the overlays working group. And oh, just a quick thing on working groups.
[00:20:20] So open API used to do everything by everyone getting on a weekly call and then getting homework assigned, and then like, maybe it was done by the next weekly call, but that
[00:20:28] was how everything ever happened.
[00:20:30] And if there wasn't enough interest in certain things, then they just wouldn't happen. But now things have been split up into working groups and I think one of them was like workflows that I was . Briefly involved with, it's quite exciting.
[00:20:41] And there's a bunch of other ones and SLAs and, and yeah, so overlays was, was one of them.
[00:20:46] And it's great to see an early kind of finished I don't know what phases and stages there are, but I read the repo and it said like, we're basically stable. Now but no one's really implemented this, so can, you know, we need some big [00:21:00] implementations to go and do it. And, and it's cool to hear there's some hobbyist ones or some implementations out there,
[00:21:04] but that, that's the hard part.
[00:21:05] We had this problem at stoplight.
[00:21:07] Everyone has this problem where you want to support a feature, but you get a few user requests come in saying like, could you use this feature? Could we. Could we have this feature? And then you're like, oh, I'm not sure we should implement it because it's not stable yet.
[00:21:20] And the people who have like come up with it have said, well, we'll only call it version one when it's had some implementation and some feedback. So you get in this chicken and egg problem of everyone hoping somebody else
[00:21:29] will implement it, so that then it stabilizes. But then if they're the first to market, then you lose out, but you're not prepared to commit the resources to it.
[00:21:37] So
[00:21:38] So where are we at
[00:21:39] **Lorna Mitchell:** Good news. I have a hobbyist thing and I think Mike Sson has something as well. He donated me a
[00:21:45] Tests. Mine's
[00:21:46] open
[00:21:46] **Track 1:** course Mike does brilliant
[00:21:48] **Lorna Mitchell:** does. It's like he's got his finger on the pulse. But there's another implementation, which is from speakeasy. Now they do call modern SDKs.
[00:21:58] It is not a coincidence [00:22:00] that it is them that have gone to implement with overlays because. Open API does not have all of the metadata that you need to generate a great SDK in every tech stack. Some of them need more data type instructions or serialization information, or, you know, there's a lot that you need to add that wouldn't be in a standard open API description. So they have these extra extensions, the x dash fields that they add. And rather than everyone, like you say, you can't add them because then when you update your open API, they are lost. So not a coincidence that they implemented overlays. Their tool is available, it's open source, it includes a validator. Kind of embrace and extended the, the implementation a little bit, but I think that's an interesting use case too. So yeah. More than one tool to look at. And I'm
[00:22:53] excited because I think it, it really solves a real problem.
[00:22:57] **Track 1:** That is really cool. And once again, I'm googling mid podcast [00:23:00] 'cause I am extremely professional. But I'm looking at the speakeasy dev. I'm just seeing AI powered end-to-end API maintenance.
[00:23:06] And again, there's like, I've just come from API days. Every other talk was about AI and I just, you know, my, my eyes are in pain from rolling, but this looks like a, a really useful implementation. They're like . They've noticed that you've type that they've noticed that you've typed in a duplicate schema and
[00:23:20] then just like changed it to a ref , which is amazing.
[00:23:24] And there's a lot of other pretty cool looking stuff on this marketing page. Let's, let's be clear, but I like their intentions.
[00:23:32] **Lorna Mitchell:** Yeah. And I think
[00:23:33] **Track 1:** dig in more.
[00:23:34] **Lorna Mitchell:** I'm with you in in team Rolling your eyes. When it comes to Yeah. AI is gonna do everything but
[00:23:40] actually . The open API, that standard machine readable specification is gonna enable a bunch of AI applications. So, and also chat GT four knows quite a lot of open API and can
[00:23:54] like quickly give you, quickly give you back some hilarious and sensible example fields.
[00:23:59] For [00:24:00] example, I wouldn't let it write
[00:24:01] my API, but when I'm
[00:24:02] working on examples, it's like, ah, this could be better. Like,
[00:24:05] make me, make me something fun with circus animals. It can do that.
[00:24:09] **Track 1:** Brilliant. Okay. Yeah. 'cause writing, you know, arbitrary examples was always the hardest part. I would always really struggle to do tutorials or demos 'cause I was like, just coming up with contrived examples is so frustrating. And like, everyone's got a bloody to-do app and no one cares. And, and just, I, I fundamentally refuse to use the pet store for anything ever
[00:24:28] So,
[00:24:29] yeah, I, I have
[00:24:29] **Lorna Mitchell:** we can share a link to Redley just published a museum, API for more or less these reasons.
[00:24:34] Also, the
[00:24:34] pet store's really outdated.
[00:24:36] SmartBear only just gone to 3.1, so we've been using a variation of this museum thing internally and we were like, we should ship this.
[00:24:44] **Track 1:** right? Well, So I mean, , the, what really annoys me about the pet store is that it's a. Bad. API like it's describing a bad API. It's got like a bunch of really bad conventions in the actual API that it's describing.
[00:24:58] it it uses a weird amount of, [00:25:00] it uses like a, an odd amount of open API to do it. I think it's being copied from like swagger two and, and
[00:25:05] not being fleshed out.
[00:25:07] And then, so now the pet store lives in open API three when like 3.1 came out, 20 20, 20 21.
[00:25:15] **Lorna Mitchell:** 2021. By the time we press the button, yeah.
[00:25:17] **Track 1:** Yeah, so that's, you know, two, it's nearly, yeah, it's a while.
[00:25:22] So don't use the pet store. There's other better examples and I like that AI can help with that for sure. I mean, I have been using copilot built into VS code and it's been helping me out for the protector.
[00:25:34] API quite a lot. Like I was just adding an array of species to sites so that we can . Ahead of time, we can say, look, these are the only species we're gonna plant at this site. So when I'm going through the field and it's raining and I've gotta take a photograph of 4,000 bloody trees, we just planted for proof for our funding partners.
[00:25:50] I don't wanna be scrolling past like sea buckthorn, which we've never planted,
[00:25:53] Just to get to like the, the, the subset of the eight species that are actually in that bloody field. Right.
[00:25:58] 'cause we've got like 50 different species [00:26:00] we may plant there. So yeah, like I was just putting that in and I just typed on the, on the sites.
[00:26:04] List I typed in species and it was like, oh, would you like to add all of these obvious properties and this whole schema and then reference the docs slash schema no sorry. Schema slash species that I see over there. I was like, yes, yes, I bloody wood. And it just built like loads of stuff for me.
[00:26:20] And even building, building that that one schema was great, but there have been lots of times where it's just completely hallucinated and done something absolutely bonkers, and I've just like pushed it. So
[00:26:30] I, I still don't trust it to do anything much apart from like, kind of assist me, but I, I, I'll never do dictated but not read with AI
[00:26:38] **Lorna Mitchell:** No,
[00:26:38] **Track 1:** it's not there yet.
[00:26:39] **Lorna Mitchell:** think as well, like it's a, it's, it's a time enhancer for me. One of the things that I find time consuming is I'm no longer particularly technically specialist in any given. Programming language. I write about
[00:26:52] four with equal levels of danger. PP is my original community, but it's moved on.
[00:26:57] I wouldn't recognize it if I walked past it in the street. [00:27:00] And so and so actually I can write all of those languages and I can debug all of those languages, but I just like throw the thing I want. In and I get something back and then that's enough. So otherwise you're like, how do I iterate? How do I concatenate? What have I done wrong with
[00:27:16] **Track 1:** Yeah. Yeah.
[00:27:17] **Lorna Mitchell:** on this? You know, like I know that it JavaScript array is a reference, but I need it to not be. And so that kind of speed up is quicker for the things that I don't know. It just lies and I can't catch it. So yeah, I'm with you. That
[00:27:31] **Track 1:** That that is absolutely the problem. And it's totally fine if this decay like this podcast decay into complaining about ai. 'cause we've been meaning to talk more about AI on it for a while. We've got someone coming on soon to talk about things that it is useful for and so we can get some of the bullshit outta the way.
[00:27:44] But yeah, even with PHP, like people have said, oh, it can help you write your tests or whatever. And I was writing a test for a model and it just kept recommending that I like write these really complicated tests for relationships, which you don't really need to do. 'cause if you have an OMM that has relationship logic and you [00:28:00] just say, I.
[00:28:01] You know orders should have organization. You don't really need to write a test. That's, that says orders do have organization,
[00:28:06] but the test it wrote was invalid and didn't fundamentally work at all. And kept doing loads of other stuff. It was trying to test methods that didn't exist
[00:28:13] like it was trying to find out if that I. Order was allocated to something, but orders aren't allocated, like units are allocated to orders. So it, it sore enough to have a real college try, but it didn't actually do the right thing. And it just confused me more than if it didn't. 'cause if, if I hadn't spent like 10 minutes trying to faff around with the, the bad test that it made, I would've just Googled how do I test this thing
[00:28:37] and then done it
[00:28:38] So.
[00:28:39] **Lorna Mitchell:** And I do worry about how much it helps us to learn new things, and especially if you are earlier in your career, like actually, is this helping you to be the best that you can be? It, I'm, I'm just not sure, and time will tell, I think.
[00:28:54] **Track 1:** Yeah, one, one devil's advocate there is that it's, it's just sped up stack [00:29:00] overflow, copy pasting, which is, you know, and it has a bit of knowledge of your system
[00:29:03] where a stack overflow has none. So there's plenty of times that I've like Googled for a problem and like copied and pasted the close enough thing into my code base and, and hope for the best.
[00:29:12] And so if it's, if it's doing that, but slightly better than, okay.
[00:29:17] **Lorna Mitchell:** It
[00:29:18] isn't
[00:29:18] **Track 1:** still not really adding that knowledge and there's, you're missing the, like, the ability to see down votes and, you know I mean, I think you were around in the code United Days, right? And,
[00:29:28] and if not early PHP days where a lot of people were doing really dumb stuff and really dumb stuff was popular
[00:29:34] and, and the popularity of something, the frequency of which you see something doesn't make it better.
[00:29:39] And so you kind of have to hope that at least with Stack Overflow and some of those forums, you'd have someone posting a really terrible idea that may even be accepted and then a bunch of people down voting and going, whatcha doing underneath it?
[00:29:52] Which is good. And with this it just goes, now take that.
[00:29:54] May it'd be fine.
[00:29:55] **Lorna Mitchell:** Accepted answer. Go for it. Yeah. And what you want is you want the most voted answer. [00:30:00] And you also want, did this change recently? You know, stack Overflow is not a
[00:30:03] **Track 1:** yeah. Yeah. It was the correct answer for years Yeah.
[00:30:06] **Lorna Mitchell:** was correct but after 2015, you should do it this way. Like that's a, that's a real answer, and I feel that. Machine necessarily on our side with that
[00:30:17] because they can't take in that context.
[00:30:21] **Track 1:** can I, can I do a, a complaint about oh, it's my podcast to do what I want?
[00:30:25] **Lorna Mitchell:** I love, please, please continue.
[00:30:28] **Track 1:** one of the talks I saw by a lovely bloke, well-intentioned talk, but the whole thing fundamentally seemed to be. Integrating with other people's APIs is really hard, so here we can get AI to do it for us.
[00:30:43] So here is an, an AI doing all of this really complicated, amazing stuff and it was truly impressive what the toy demos were doing. But towards the end of the question and answer, it was very much, how much does the AI [00:31:00] need the API to be built in a specific way? And and he was like, oh yeah, basically there are certain ways that AI will expect the API to be built.
[00:31:10] And if it's not built following those very specific assumptions, then this basically won't work at all. So what some people do is build a new API specifically for the ai.
[00:31:20] **Lorna Mitchell:** Mm-Hmm.
[00:31:21] **Track 1:** Where it does follow all of those conventions and then it can save you loads of time. It's like, oh, okay. We're all just completely rebuilding all of our APIs and, and doing BFFs for every client just so that AI can then save some time instead of looking at the docs we spent ages making.
[00:31:36] I, that's, that's sort of thing is where my, my, my bullshit flag goes up.
[00:31:41] 'cause it's like, is this just early days and the AI will eventually be able to talk to any API or are we just kind of saying . Like the wizard will fix it and pass in more work onto API teams who probably would've had a better time sitting down with their stakeholders and asking what they really need instead of building some shit that was so confusing in the first place, that [00:32:00] everyone's scared of looking at the documentation and then ask for an AI to be built so they can figure out what the hell you did.
[00:32:05] Like
[00:32:05] maybe we could just make better APIs. Yeah.
[00:32:08] **Lorna Mitchell:** Well, and I, I'm an optimist, so I, I wanna flip that argument and say you're right, but it, what you're actually saying is that the people who have, well-designed, well-documented APIs described with open API. Can integrate easily and well both with other platforms and with ai if that's what people want to use it with.
[00:32:27] It's good for all integrations. People who have badly designed APIs incomplete API documentation, they are gonna have a hard time. I don't think the wrapper APIs add anything. You,
[00:32:39] you'd be better just to start again, talk to the actual users talk to the AI if you like. They're very chatty. And make, and make things better.
[00:32:49] **Track 1:** That's cool. Yeah, I think it's a good point is that some of those, some of those people were coming from a place of, you don't have any open API or anything similar. So if it's just
[00:32:57] like you have an implementation and then [00:33:00] like some Jason happens, I guess then how would anyone know anything about this?
[00:33:04] And I think open API is an interesting way that it can add in more. You can, you can train an API on that a bit. And even if they don't understand what all of the objects are moving through. Part of something that a, the API community needs to do anyway. Part of my like 10 year plan, 20 year plan for like what I'm gonna be blathering about in API world has always been step one, get people defining what the hell this data is, right?
[00:33:28] Like open API isn't the end goal that we all, we do this and then everything's brilliant. Even though I talk about it plenty, it was was you have random Jason flying about the internet and no one knows what the fuck is going on. This is not great. So getting people to like . Write that down, make a contract that, that, that was step one and then, okay, great.
[00:33:47] We know what your implement, you know, your version of a tree and your version of a person and your version of a whatever account. But then like, can we try and have shared collections? And at
[00:33:56] stoplight we were doing design libraries where you can have like a [00:34:00] repository of open API models you can reuse within your organization.
[00:34:04] 'cause there was one company that had . 500 different versions of a flight, which is
[00:34:08] literally plane goes from there to there. Like that's not very complicated. With some seats, but there are a lot of different versions. And so they've, they've kind of squished that down to one version of a flight now.
[00:34:18] So it's literally describe the mess and then like reduce the, the, the mess and then like reuse those outside of the organization
[00:34:27] with, you know, shared data models and, and concepts like schema.org. But maybe not that 'cause it's like. A lot of that is biological medical data, which doesn't seem very helpful, , but that kind of concept.
[00:34:38] And then after that, like everyone is more trained, Haos becomes more useful in that world because
[00:34:43] you don't need to train it to know exactly what that URL is. You train it to know what these generic models are and how you work with them. But it also makes AI more useful 'cause it then has that same shared knowledge of what's coming back.
[00:34:53] So I, I like that that approach seems to be. The same as my existing approach. , I'd have to [00:35:00] change my thoughts too much. Great. But yeah, the other, there is a lot of like magical Wi Wizard stuff in the world of AI and I do wanna kind of get people to be a bit cautious about what they go all in on.
[00:35:10] 'cause it,
[00:35:10] some of it doesn't seem very helpful.
[00:35:12] **Lorna Mitchell:** agreed.
[00:35:13] **Track 1:** Last bit we were gonna talk about was open API four. I have been very out of the loop on this. It has a fun name, moonwalk, what's going on, help.
[00:35:22] **Lorna Mitchell:** Yeah. I'm not sure why it needed a project code name. But I think we've been kicking this around for a while. I mean, I went off and spent two years working in the database space and came back. We were still talking about it, so it's not going anywhere.
[00:35:36] **Track 1:** I was gonna say you vanished for a while and then came back to open
[00:35:38] **Lorna Mitchell:** I did, I had
[00:35:39] **Track 1:** said yay.
[00:35:39] **Lorna Mitchell:** absolutely lovely time doing loads of derell with loads of open source databases at Ivan, which was
[00:35:43] great. Now I'm back in the API space. That's great as well. Did I mention I'm an optimist? So news, news from the open API community. Then I mean, I think I. There's news in both the V three and the V four worlds. The V three news is just, we are seeing [00:36:00] a lot of adoption. We are seeing people using 3.1. I think some of those educational resources are starting to get out there. Companies like Redley, and, but it takes the whole ecosystem
[00:36:10] and, and we, I think even though we are commercial competitors, we know we share a community and we collaborate really well. I'm sure that's true in other industries as well. But, so yeah, three, going from strength to strength, new tools all the time. General goodness, four. We've just put out a blog post from the Open API initiative committing to launching a version of four in 2024.
[00:36:37] **Track 1:** Okay.
[00:36:37] Getting people ready for it instead
[00:36:39] **Lorna Mitchell:** ticking. Yep. And there is, if anyone wants to see, we'll put it in the show notes. There's a repository full of discussions on GitHub about what we want to solve. At a high level um, it's, we are
[00:36:52] looking at simplifying the structure, making it a bit more resource oriented
[00:36:59] and a little [00:37:00] bit more approachable as well. Jason
[00:37:02] **Track 1:** Just to explain on that a second, the resource orientated, meaning it's a bit less about like paths. What are your paths? 'cause that's been a, a concern about . Not really being very resty.
[00:37:13] 'cause like paths, some people will say that in a rest API like paths are the least important thing.
[00:37:18] And they could literally be like a random MD five Check sum is the most extreme example I've heard someone say because it really is just, it's about interacting with resources as like a state machine.
[00:37:29] And the homepage is a resource that then like lets you see other resources you could interact with in various ways and describes how.
[00:37:36] And so the fact that open API has always been like, tell me your paths, resources are optional, has always felt a little bit RPC ish to many people. So
[00:37:44] is that something that's
[00:37:45] **Lorna Mitchell:** so
[00:37:46] well, and the goal I think, with moonwalk is to get away from paths so that we can include more types of API, including the ones
[00:37:54] that are less restful. So
[00:37:57] with RPC, where you have one end point [00:38:00] and maybe different query parameters or.
[00:38:03] Body data makes different actions happen. You can't represent that right now in
[00:38:09] open API. If you can just have, it's like the path and verb combination. Is it get, or is it post? What's the exact
[00:38:17] path? Not including query parameters, that's your unique identifier.
[00:38:22] **Track 1:** Yeah, someone had to make open api sorry, open RPC, which is like a copy paste of open API, but tweaked it so that you could do RPC stuff. And
[00:38:30] so yeah, that would be nice if.
[00:38:32] **Lorna Mitchell:** Yeah.
[00:38:32] And looking more at, there are more, the more things than that, that go into what we are now calling a signature. Like what endpoint is this? How would you root it in your code? You know, does your API do different things on header or on some other thing that we could take into account. Otherwise, you end up with this very lots of polymorphism because you can't. Correctly represent that these two things look completely [00:39:00] different. If it's, you know, completed orders or incomplete orders,
[00:39:03] it might be a filter on an end point, but you're gonna get different types of object back. Moonwalk is gonna cater for that as well. But there's
[00:39:11] a thriving community, lots of chats. Th three isn't going anywhere. That's a lively community too. And as with the open API initiative, we're looking more at how we can Better respond to questions in that community, stuff like that. I have triaged on those repos and just trying to get everyone to be a bit more present.
[00:39:30] **Track 1:** Nice. I will have to dive in a little bit more. I mean, bloody Yeah, we had Darryl Miller on on the episode on the podcast, and I didn't ask him a single question about it, but we're talking about other stuff. I think the reason they came up with moonwalk was that they wanted a bit of a experimental playground where they could just try and hash out some ideas
[00:39:48] without everyone going.
[00:39:49] That's definitely what's happening. Panic, panic, don't do four. Um, Which would definitely happen. We've had that before. So I can understand that. And it sounds like it's kind of got enough agreement amongst the [00:40:00] people that were paying attention that it. Is moving towards possibly actually being four.
[00:40:05] So that's, that's what you want. So we'll just have a normal name. It will just be called open API four.
[00:40:10] We're not doing like cool branding now
[00:40:12] **Lorna Mitchell:** Well,
[00:40:12] a
[00:40:13] **Track 1:** that's cool. '
[00:40:13] **Lorna Mitchell:** cause you're actually walking backwards. I don't know.
[00:40:15] **Track 1:** Yeah. , this is, this is several very casual steps backwards. Brilliant. Well, yeah. Great. I'm glad to hear those changes.
[00:40:22] I mean, one, one, . Small thing in my head is that. There are certain things that open API won't let you do that. I've always been quite happy about, in a
[00:40:31] way, cause like open API will let you perfectly describe a bad API. But there are some of the things you shouldn't be doing that you can't currently describe.
[00:40:40] And so by being able to describe more of those things you shouldn't be doing, I'm a little bit like flexibility is important so that you can get all the old APIs on and then you can edge them in the right direction with, you know automated linters. And, and get them doing the right conventions that way.
[00:40:54] But part of it was also you. Man, why did you do that? Please don't do that. Change that quickly.[00:41:00]
[00:41:00] **Lorna Mitchell:** Yeah, I think that's a, I think
[00:41:02] that's a real concern. And, you know, I want, I wanna represent and respect everyone else's work, but looking at the adoption for
[00:41:08] 3.1, which was a very obvious improvement and upgrade for 3.0 users. some tools were available quite quickly. I know some took some time.
[00:41:19] There's a whole raft of new tools have come out for 3.1. We're really seeing the adoption now. 4.0 doesn't offer anything to existing users.
[00:41:27] **Track 1:** Mm.
[00:41:28] **Lorna Mitchell:** brings more people into the fold, and if you're an existing tools vendor. Which obviously that's my job now. I'm not sure where we're going with that. It's going to be significantly more difficult to build for
[00:41:40] as things look at this very early stage. So I am supporting everything that's happening in the Open a BI initiative. Very excited to see just better. Education, better appreciation in the industry for what we do with Open API three and 3.1 and how it can
[00:41:57] help. And watching what's happening in [00:42:00] four. It takes a long time to write these specifications and for tools to follow. So nobody needs to panic.
[00:42:08] **Track 1:** Yeah. Yeah. It's not appearing anytime now. I mean, even if, even if, didn't you say that mo version four is committed to appearing sometime in 2024?
[00:42:17] Well, that's, that's 12 months long, isn't it? So
[00:42:20] **Lorna Mitchell:** And I don't know, you know, open API initiative does not build tools, and I'm not, it's not clear to me right now who will.
[00:42:27] **Track 1:** Right. Well, that's the thing. So yeah, like in a year's time we could have a spec out and then still no one will use it. 'cause it takes a long time for, for tool and vendors to catch up. Which is why it's important to like, you know, plow on whilst, but some tools have only just upgraded to 3.1. Yeah, this all takes a long time.
[00:42:43] So like, someone needs to be thinking about the future instead of just going, don't change anything. It's scary.
[00:42:47] **Lorna Mitchell:** Me it is
[00:42:48] about doing good rep, good support
[00:42:51] for 3.1. Lots of people are coming into APIs or raising their API
[00:42:56] game now with what's available today. [00:43:00] And I
[00:43:00] think, you know, I work in developer experience. I really care about stuff that you can do today, and so that's my focus.
[00:43:06] **Track 1:** absolutely. Yeah. Gotta do both. But as long as, as long as the new one thinks about migration path, like as long as, as long as it's made in such a way where there is a migration path and, and that can be automated, I think that's pretty important.
[00:43:18] But also.
[00:43:19] **Lorna Mitchell:** is one of the requirements. Yes,
[00:43:21] **Track 1:** Okay, good , because various tooling vendors.
[00:43:24] **Lorna Mitchell:** They got it.
[00:43:25] **Track 1:** Yeah. Well, Mike Ralph's there saying like, he, you know, he, he made swagger to open API and he is gonna make open API three to moonwalk or whatever. Like he, he's on it. But yeah, that, that is important. And then the other thing, like Eric Wild made this really good point at a API days Paris about how
[00:43:43] Async API released a async passer, and it is like the defacto passer. You can pass a document any way you like. You can also use theirs, and I'm sure it's just written in, in TypeScript and nothing
[00:43:54] else, but this thing, this thing exists and, and the majority of tools can use it. And an open [00:44:00] API majority of the tools are TypeScript or no something.
[00:44:03] So I'm, I'm really thinking that like that is the next most important step is for somebody probably Mike, let's be honest, he loves to write some code. Somebody to uh, just volunteered him either way. Somebody to write like an open API passer, that is the default. 'cause there's been lots of these other little ones here and there.
[00:44:18] Like I've just deprecated one of them that I awkwardly inherited from some guy I tried to help and then, and then I got stuck doing all the code and I was like, I don't have time for this. There's a lot of these like awkward ones floating about, but if there can be one sample represent you know implementation.
[00:44:31] Initially written by a person, but as more people use it, more people will help maintain it. And then that can be okay, you've got, you've got your passer that works for 3.1, but there's this other passer over here that works for four and that makes it a lot easier to switch to. 'cause you don't have to rebuild your passer to support four, you just use the thing.
[00:44:49] And then you don't have to worry about all the intricacy, awkward bits of yaml. It's just you have some models to, to work with. I really hope they can do that. And I'll be nagging people to give that a try. Without volunteering myself 'cause I'm crap [00:45:00] at code these days.
[00:45:01] **Lorna Mitchell:** I think it's a tricky one, you know, 'cause I work for a tools vendor now, so I was like, oh, you are gonna build some of the tools. Do you wanna tell me what else you're gonna build so that we don't invest our commercial expertise in
[00:45:12] **Track 1:** Yeah.
[00:45:12] **Lorna Mitchell:** you know, and I'm .I'm not really sure if the proliferation of many tools in open API is a feature or a bug.
[00:45:19] But I think feature, I think the competition has helped because it's very open source, isn't it? It's, it's a,
[00:45:25] it's an open standard. There's loads of different tools. You know, open API tools tells that story loud and clear. You can choose, it's in your tech stack. There's always something. Whereas
[00:45:37] I think if we go to one official version, we're tied down to the speed that the Central initiative works at, which isn't always the same speed the industry does
[00:45:46] **Track 1:** Yeah, I mean, hey, maybe that could be a working group right in, in, instead of it just being , very overworked, Mike and trying to do the thing to make all the vendors happy, who are all getting paid to work on their tools and he's not. Maybe that could be a working group where we're like, let's hash out like what we [00:46:00] need from a, a shared passer.
[00:46:01] And then if anyone in the group ends up not really getting something that. They're happy with and they can just go and make their own however they want. But yeah, definitely it is a difficult line in general with like, should the open API foundation be making all this stuff? 'cause they're like, well we've just made a documentation tool.
[00:46:17] You know, like that would be pretty messed up.
[00:46:19] **Lorna Mitchell:** well, and the members are documentation tool vendors, so that's awkward Async. KPII have the opposite one, and you might have seen this as well from having Async KPI support spectral. Reduc, CLI has Async API support as well, just for linting. We don't have it in docs yet, and honestly there's the Async API community doesn't really talk about anyone else's tools.
[00:46:42] It doesn't have the same ecosystem. They just build their own tools. They're all quite closely coupled. It's the same people.
[00:46:48] **Track 1:** Right.
[00:46:49] **Lorna Mitchell:** Postman pays them. That's what you get. And so it's very, very different despite the fact that those two projects have quite a lot of shared philosophy. They also don't, [00:47:00] and the tools is
[00:47:00] a really big differentiator.
[00:47:02] **Track 1:** That is interesting. Well, still, I'm always excited about the potential for collaboration and at some point I'll be picking your brains about I chatted to all the other API linkers and we're all gonna have a conversation about like coming up with a shared rule set format. And even if it's not one that anyone particularly wants to make their their default, it's just like, can we make some tools that swap them in all directions?
[00:47:21] 'cause that'll be cool. Although I gotta talk to the optic team about, they've just come up with um,
[00:47:26] lint, GPT, where you just write your rules as a, an array of strings and hope that the wizard is consistent. But
[00:47:32] I'm gonna give that to all a try
[00:47:34] **Lorna Mitchell:** I think Optic currently have the best converters, so they understand this problem space, but because.
[00:47:40] **Track 1:** Yeah. Yeah.
[00:47:41] **Lorna Mitchell:** Redoc, CLI, all our linting is very like a ST data structure driven. It's not
[00:47:49] JSON path driven like the others. My, I had a quick look and I was like, oh, this is gonna be really difficult.
[00:47:55] Interrupt because we are not describing, you
[00:47:59] know, [00:48:00] we're like it, oh, you have a response example here. This is what we do with this response examples. It's not like it's this path, this path, this path.
[00:48:08] **Track 1:** Right.
[00:48:09] **Lorna Mitchell:** Turn, turn left at this array. Then take the third success response element. You know, like
[00:48:14] **Track 1:** Yeah. I gotcha. cause it's based on, it's based on OAS kit. Right. And I remember how that works. Like OAS kit just walks through and then goes, oh, I found one of these. Anyone care about this? Yeah, you do. Cool. Run some rules on it. Whereas we're like, go through the rules and then like . Delve into the depths following this arcane direction.
[00:48:29] I shouldn't have opened up this can of worms so late in the podcast.
[00:48:32] We like
[00:48:32] **Lorna Mitchell:** we're gonna still
[00:48:33] **Track 1:** 35 minutes normally, and I yeah, I could, I could talk to you for hours, honestly. Yeah, it it's really great to have you on the show and we'll have to get you back on to talk about other stuff in the future.
[00:48:41] For sure.
[00:48:41] **Lorna Mitchell:** That
[00:48:42] would be awesome.
[00:48:43] **Track 1:** for coming,
[00:48:43] **Lorna Mitchell:** for having me.
[00:48:44] **Track 1:** Cheers. Bye.
[00:48:46] ​