API Evangelist Conversation with Lorna Mitchell, VP of Developer Experience at Redocly

Kin Lane here for another one of my API Evangelist conversations, where I sit down with folks who are doing interesting things with APIs. Let’s not waste any time, let’s dive right in and find out who we have here today. Who are you?

Hi Kin, hi everyone. So my name is Lorna, I have been attempting to explain APIs to developers for a really, really long time. Right now my interest is very much in APIs, improving practice in APIs, working with OpenAPI, and my day job is, I’m VP of developer experience at Redocly.

Big fan of you, big fan of Redoc and what y’all are building with Redocly, and that’s kind of what I want to scratch at. But I’ve been learning from you for years when it comes to the OpenAPI spec, when it comes to AsyncAPI and other specs. So I want to dive right in kind of at the intersection of, what I would say, beyond rules, meaning beyond Spectral, and then beyond rules applied beyond OpenAPI. So that’s kind of the intersection I’m hoping to hit at here. And let’s start with Redocly and dive in on Redocly CLI. What is Redocly CLI?

I’m going to talk for five minutes and then you’re still going to wonder what it does, because it actually does a lot of different things. So Redocly, it’s an open-source multi-tool for all of your API things, and its origin is very much in OpenAPI, but we have really good support now for AsyncAPI and for the newer Arazzo format as well. So you’re going to use Redocly CLI for managing your files. If you have an enormous OpenAPI description and you want to keep that in smaller files, we have a tool for splitting it, you can easily bundle it back together. If you have a bunch of OpenAPIs you can combine them. We have amazing linting that I think we’re going to drill a little bit more into, and how we have built-in rules, configurable rules, and also some of the extensibility in OpenAPI for OpenAPI linting that you can put in, also for the other formats. We have a bunch of decorators, so this is the transform step — as your descriptions, whatever the format, go through a series of changes, they don’t arrive fully formed and perfect, usually there’s work to do before we publish, even if it’s just filtering in or out certain endpoints before you publish.

I think Redoc is most famous for open-source Redoc, which is kind of that original three-panel API reference layout powered by OpenAPI. So yeah, the CLI will drive your docs as well. Little-known feature of Redoc CLI, it also comes with an OpenAPI core library, so you can programmatically include it in your JavaScript or TypeScript applications if you’d like. I like it on CLI, so I typically use it that way.

So it sounds like it’s really a Swiss Army knife kind of API tool, acknowledging that we got multiple parts and pieces laying around that we’re going to be combining. So have you guys really kind of figured out the whole ref thing? Are you guys handling refs in an intelligent way? How are you approaching that?

Yeah, we think we are. I don’t want to get too deep into the internals of this thing, but the way that Redocly handles all of these data structures, and the reason that we can then add the same amazing features to the different data structures, different types, is that we pass everything into a big data structure, and then everything is applied, typically like a visitor pattern, you can go around and visit all the nodes and say, oh, you’re a parameters node, well then we’ll go and look this stuff up and maybe apply this transform. So it’s got this very clear, context-aware sense of where you are and what kind of a thing this is when you’re either linting it, reporting on it, or actually changing it as well. And this is my most fun thing — you know, we added the data structure for Arazzo, and straight away I like, would you like that in JSON? How about Markdown? Because it’s built into an existing linting tool, so it has all of that. I think the refs, yeah, we have a pretty good handle, there are some strange corner cases, and I think we’re always looking to hear what doesn’t work, but in general I would say yeah, we have a pretty good handle on it. And one big thing that we have — so I was a Redoc CLI user in my previous API lives before I came to work on this tool as my day job, and one thing I’ve always enjoyed is, if you do use that split structure, or having your OpenAPI in manageable-sized files where they just refer to each other, you can do your linting in that deconstructed structure so you don’t have to bundle. And the reason that matters is, then you know where the error actually was, because you still have your real file structure. So yes, I think we have pretty good ref support.

Nice, well, I agree with you. I think maybe this is for a future episode, because I can have you back in this new podcast format, and I think the refs, the schema registry, I think there’s a lot of things — I’ve been studying how folks are managing their GitHub repos, and so I’d like to go there with you. But first I want to focus on spec governance. And Spectral rules has pretty much been — the lion’s share focuses on OpenAPI and Spectral rules, and so you’re applying this to AsyncAPI as well as Arazzo spec. So is this unique to how you guys approach things, or do you see this as how governance and everything should work?

Honestly, I think you could drop in Spectral for most of what Redocly has, because they have just shipped the Arazzo support there as well. But whatever you’re doing with Spectral, you can drop in Redoc, there are other linters, and the thing I always say to people, even though I work for a vendor, like, if you have a linting tool that meets your needs, don’t switch from one to the other. Your API standards are really important, however you express those programmatically, linting doesn’t matter. But I think there’s enormous value in having something that can support the new formats but also has the extensibility for you to bring that to fit your API standards even further. I think one thing that I really appreciate is, Redocly CLI has the ability to describe additional types now, this is really important in something like AsyncAPI, which has what feels like a constantly moving target of protocols, and sometimes those protocols can refer to more protocols. So if there is anything that we don’t have in our built-in support, which is in its early days — I think we only shipped the AsyncAPI support about a year ago and they’ve done a major release since, so we’ve got two major versions in there — the fact that we have the plugin architecture, you can add additional types, you can add additional rules, you can add additional transforms, we call them decorators, you can build a very complex pipeline. And I think whether you’re using AsyncAPI, OpenAPI, Arazzo, that’s really important.

And with those newer non-OpenAPI formats, we tried not to rush with mandating lots of built-in rules and recommended standards and stuff, because we know we have early adopters that we work with that are excited to have this functionality, we’re looking to hear their feedback and see what they build. We have a project called the Redocly CLI cookbook — it’s an open-source tool, it’s a public repository, people share their extensions, and so we have our customers and users community learning from each other. I think that’s been a really big win, where it’s not all on us to kind of show what can be done. I see some great use cases from the community and from our customers, and I’m like, could you just share that in the cookbook, and then everyone can use it.

Yeah, I like that, because I think there’s too much attention on, oh well, you just go download these Spectral rules and you fire them up in your operations and you’re done with governance, governance just works. And I think what you’re saying is, it’s more of an iterative process, it’s a community, it’s something you have to evolve and grow. But it sounds like you guys have — I’ve hit the wall with Spectral rules as far as, I know the limitations in and out, and of course I can do custom rules, but it sounds like Redocly CLI has many different directions I can go when it comes to this extensibility.

Yeah, you definitely can, and I think that’s super important. I’m already on record as saying that I thoroughly recommend that you do not use anybody’s recommended rule set, because one size doesn’t fit all. There are common patterns, there are good practices, you share a lot of this good advice, but downloading an existing rule set and not really starting from your own API standards needs, I think it’s a mistake, and I think everybody should be at least combining different sets of built-in rules or borrowed examples to build the right standards for them.

Yeah, and so what’s next, what would you say the future holds — and I don’t say just from a Redocly CLI, like what’s next for OpenAPI, what’s next for governance in general, what’s your view on what’s needed?

So in Redocly CLI, just because I was just talking about it, I’ll round that conversation off by saying we have some new built-in Arazzo rules coming for you, and the way that all those different formats combine, allowing you to set up rules for each type of API description as well as individual ones, and maybe grouping rule sets, I think there’s more work to do there, some stuff is planned, or I’ve seen it, and some stuff I think we need. So you can kind of expect those things to come as well.

In OpenAPI itself, so I’m on the technical steering committee for OpenAPI, I spend a lot of time there, I love being a maintainer on a project that everybody uses, whether they love it, hate it, ignore it, like, it’s fine. Coming up pretty soon we’re going to have some patch releases on the main OpenAPI specification, so if you are using 3.0 or 3.1, we have patch releases which will be the least exciting thing ever, because that’s the point of a patch release, we don’t change things, but there’s lots of additional examples, text clarification, and those things, mostly driven by issues that we’ve received since those versions were released, which is a few years ago now, so shiny new release. I expect there also to be a minor release, 3.2, in the coming months, that does have some small changes, you’ll see some additional optional fields coming in, there’s some pretty cool stuff if you are using any of the webhooks or tags, that is one to keep an eye on, and maybe I can come back and give you the full rundown when we commit to that release. You may have heard about Moonwalk, the OpenAPI 4.0 plans, those are still plans, and I think we’ll hear more about that as it takes shape.

And what else is going on? Arazzo is released already. And I also expect another new standard from OpenAPI soon, which is Overlays. So Overlays solves the problem where you have an OpenAPI description that isn’t perfect, it needs to change in some way, maybe you need to remove some endpoints, change a description, maybe you’re translating your API reference documentation, there’s a bunch of modifications, those need to be repeatable, because when the API changes, the API description changes, and you probably need to reapply those. Overlays solves that problem. We’ve had a draft for 1.0 for a really long time, but no official release, there are some tools that support it already, and so we’re making that release official, and you’ll see the 1.0.0 soon.

That makes me very happy to hear. I love the Arazzo movement, I love to hear Overlays. These, for those of us who like, been involved and been watching, part of it, these things take time, as you know. How do people get more involved, what are the opportunities for people who aren’t familiar with OpenAPI and OpenAPI Initiative, how can they get involved?

The best place to start is the OpenAPI Initiative website, so we’re openapis.org, and that has links to everything that you need. There’s learn.openapis.org, which has a bunch of resources, and that is great if you are learning more. We have spec.openapis.org if you want to look up the spec for the specifications as we publish them. We’re very active on GitHub, our org is OAI, so come and find us, everything’s done in the open, it’s an open standard. And there’s also a very lively Slack community for OpenAPI, and you can get an invite to that and find out when all our public meetings are, again from the main website, openapis.org.

Awesome. Definitely get involved if you’re interested in OpenAPI, I feel like there’s kind of a whole renewed set of energy around it I’m seeing with the Arazzo, and I think the Overlays is going to continue that momentum. So definitely get involved. I’m going to have you back, we’re going to talk more about OpenAPI, but this one I wanted to keep about rules, and I think we covered most of it, but I appreciate you coming by, Lorna, always good to see you.

Thank you, thank you.

All right, definitely OpenAPI talk, I’ll get Lorna back in a month or two, and I think also the parts and pieces and refs and schema registry, the Swiss Army knife thing. I’m doing a lot of work and I’m drowning in those details right now, so I think I’m going to have to have Lorna back and help help me learn some there. All right, thanks everyone, I appreciate y’all tuning in.