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,
Lorna Mitchell: Hi.
Hello.
Happy to be here.
Track 1: Nice.
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,
but if not.
Lorna Mitchell: I actually don't think I have, I, I have written
for APIs you won't hate, and
I like to write.
I should do that again.
I'm not sure we've done the podcast thing before.
Track 1: alright, well either way welcome.
And for folks who dunno who you are, could you describe a little bit about yourself?
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 open source.
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?
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?
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.
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.
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.
'cause it was always a bit weird trying to hack that into callbacks.
You'd have to like.
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.
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.
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.
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 a sidekick for open API.
Right.
I did
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.
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.
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.
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.
Track 1: Yeah,
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.
But I seem to remember you giving a bunch of feedback about that.
Like why is it constantly complaining that I need to use tags, I don't actually
need to use tags, and that was just in
there for some reason.
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.
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
now.
Track 1: time for an updated blog post.
I think
Lorna Mitchell: definitely.
Well, and we'll just write all the blog posts for
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 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.
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
Track 1: Yeah.
Yeah.
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.
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
can
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,
Lorna Mitchell: Yeah, and it's harder
to reason about which sections should have changed
when it's just one long thing.
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 a preview docs.
These are all good, these aren't new things.
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.
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.
I was like, no, because taking a, taking a giant opiate open, API file.
Like, I feel like no one's doing enough refactoring,
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.
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
and put them into the same file.
And I was like, God damn, that's useful.
So I was really glad to see that even though it's like a,
a undersung kind of feature.
Yeah.
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
team maintains an API each, but you publish it as a single surface
that's actually really messy.
I've seen some horrible merge.
Attempts and
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
repeatably 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.
Track 1: Interesting.
Like, like what?
Make it more tangible for my struggling brain,
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
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.
Do you want to maintain that in your source code?
When you are generating from that, you know,
Track 1: Oh, I see.
Yeah.
Lorna Mitchell: you are maintaining the YAML for the markdown in your source code.
I just, I do understand why people don't enjoy that.
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.
Um,
Lorna Mitchell: Not even have access.
That's really common.
You get frustrated tech writers who could add really great,
you know, descriptive content.
Example values.
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.
Obviously the documentation tools, Redoc and friends are the very good
API Documentation tools are available.
Track 1: Standard BBC response.
Yeah.
Lorna Mitchell: Well, I just feel like, I don't mind which one you use, but please
give me some documentation, you know,
Track 1: Yeah.
Yeah.
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
maintain that in wherever upstream your open API.
Things are coming from.
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.
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
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.
But then maybe you are trying to expand somebody else's published design first.
Stuff 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.
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.
Lorna Mitchell: controversial?
Yeah.
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
not a secret And I think the point there is a good one, that it's
yet another complex structure.
We've got a specification with no tooling at all, and it
requires use of JSO path.
Now, if you've been using Spectral, that is very JSON path heavy.
Track 1: Yeah.
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
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
at re doley we're trying to enable.
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
anyone could theoretically use, whereas decorators is
more of a like redly feature.
And could theoretically be, you know, ji to, to be the same thing.
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.
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?
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.
And so much like what markdown had, like markdown plus and a
million different markdown flavors.
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.
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.
But it's . Almost impossible in any sort of . 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?
And the result will show me what I've done.
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.
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
some stuff off my chest.
Lorna Mitchell: Carry on.
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
this back on the table.
But basically aliases, the idea was 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.
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.
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.
So that meant you couldn't actually use those to help.
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
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.
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
I,
completely recognize the need to not Jason path and therefore
avoid that entirely in overlays.
Right.
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 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.
We don't have to go all the way back in a, in a, in a big organization that's hard
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 overlays, implementations.
One of them is mine.
We can link to it.
It's very hobby.
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
it.
I need to
do
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.
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
was how everything ever happened.
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.
And there's a bunch of other ones and SLAs and, and yeah, so
overlays was, was one of them.
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 implementations to go and do it.
And, and it's cool to hear there's some hobbyist ones or
some implementations out there,
but that, that's the hard part.
We had this problem at stoplight.
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.
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
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.
So
So where are we at
Lorna Mitchell: Good news.
I have a hobbyist thing and I think Mike Sson has something as well.
He donated me a
Tests.
Mine's
open
Track 1: course Mike does brilliant
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.
It is not a coincidence 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
excited because I think it, it really solves a real problem.
Track 1: That is really cool.
And once again, I'm googling mid podcast 'cause I am extremely professional.
But I'm looking at the speakeasy dev.
I'm just seeing AI powered end-to-end API maintenance.
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
then just like changed it to a ref , which is amazing.
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.
Lorna Mitchell: Yeah.
And I think
Track 1: dig in more.
Lorna Mitchell: I'm with you in in team Rolling your eyes.
When it comes to Yeah.
AI is gonna do everything but
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
like quickly give you, quickly give you back some hilarious
and sensible example fields.
For example, I wouldn't let it write
my API, but when I'm
working on examples, it's like, ah, this could be better.
Like,
make me, make me something fun with circus animals.
It can do that.
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
So,
yeah, I, I have
Lorna Mitchell: we can share a link to Redley just published a museum,
API for more or less these reasons.
Also, the
pet store's really outdated.
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.
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.
it it uses a weird amount of, 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
not being fleshed out.
And then, so now the pet store lives in open API three when
like 3.1 came out, 20 20, 20 21.
Lorna Mitchell: 2021.
By the time we press the button, yeah.
Track 1: Yeah, so that's, you know, two, it's nearly, yeah, it's a while.
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.
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.
I don't wanna be scrolling past like sea buckthorn, which we've never planted,
Just to get to like the, the, the subset of the eight species that
are actually in that bloody field.
Right.
'cause we've got like 50 different species we may plant there.
So yeah, like I was just putting that in and I just typed on the, on the sites.
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.
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
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
Lorna Mitchell: No,
Track 1: it's not there yet.
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
four with equal levels of danger.
PP is my original community, but it's moved on.
I wouldn't recognize it if I walked past it in the street.
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
Track 1: Yeah.
Yeah.
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
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.
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 just say, I.
You know orders should have organization.
You don't really need to write a test.
That's, that says orders do have organization,
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
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
and then done it
So.
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.
Track 1: Yeah, one, one devil's advocate there is that it's, it's
just sped up stack overflow, copy pasting, which is, you know, and it
has a bit of knowledge of your system
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.
And so if it's, if it's doing that, but slightly better than, okay.
Lorna Mitchell: It
isn't
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,
and if not early PHP days where a lot of people were doing really dumb stuff
and really dumb stuff was popular
and, and the popularity of something, the frequency of which you see
something doesn't make it better.
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?
Which is good.
And with this it just goes, now take that.
May it'd be fine.
Lorna Mitchell: Accepted answer.
Go for it.
Yeah.
And what you want is you want the most voted answer.
And you also want, did this change recently?
You know, stack Overflow is not a
Track 1: yeah.
Yeah.
It was the correct answer for years Yeah.
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
because they can't take in that context.
Track 1: can I, can I do a, a complaint about oh, it's
my podcast to do what I want?
Lorna Mitchell: I love, please, please continue.
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.
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 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.
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.
Lorna Mitchell: Mm-Hmm.
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.
I, that's, that's sort of thing is where my, my, my bullshit flag goes up.
'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 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.
Like
maybe we could just make better APIs.
Yeah.
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.
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,
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.
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
like you have an implementation and then like some Jason happens, I guess then how
would anyone know anything about this?
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?
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.
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
stoplight we were doing design libraries where you can have like
a repository of open API models you can reuse within your organization.
'cause there was one company that had . 500 different
versions of a flight, which is
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.
So it's literally describe the mess and then like reduce the,
the, the mess and then like reuse those outside of the organization
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.
And then after that, like everyone is more trained, Haos becomes
more useful in that world because
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.
So I, I like that that approach seems to be.
The same as my existing approach.
, I'd have to 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.
'cause it,
some of it doesn't seem very helpful.
Lorna Mitchell: agreed.
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.
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.
Track 1: I was gonna say you vanished for a while and then came back to open
Lorna Mitchell: I did, I had
Track 1: said yay.
Lorna Mitchell: absolutely lovely time doing loads of derell with loads of
open source databases at Ivan, which was
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 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
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.
Track 1: Okay.
Getting people ready for it instead
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
looking at simplifying the structure, making it a bit more resource oriented
and a little bit more approachable as well.
Jason
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.
'cause like paths, some people will say that in a rest API like paths
are the least important thing.
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.
And the homepage is a resource that then like lets you see other
resources you could interact with in various ways and describes how.
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
is that something that's
Lorna Mitchell: so
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
that are less restful.
So
with RPC, where you have one end point and maybe different query parameters or.
Body data makes different actions happen.
You can't represent that right now in
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
path?
Not including query parameters, that's your unique identifier.
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
so yeah, that would be nice if.
Lorna Mitchell: Yeah.
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 different.
If it's, you know, completed orders or incomplete orders,
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
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.
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
without everyone going.
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 people
that were paying attention that it.
Is moving towards possibly actually being four.
So that's, that's what you want.
So we'll just have a normal name.
It will just be called open API four.
We're not doing like cool branding now
Lorna Mitchell: Well,
a
Track 1: that's cool.
' Lorna Mitchell: cause you're actually walking backwards.
I don't know.
Track 1: Yeah.
, this is, this is several very casual steps backwards.
Brilliant.
Well, yeah.
Great.
I'm glad to hear those changes.
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
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.
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.
But part of it was also you.
Man, why did you do that?
Please don't do that.
Change that quickly.
Lorna Mitchell: Yeah, I think that's a, I think
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
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.
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.
Track 1: Mm.
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
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
help.
And watching what's happening in four.
It takes a long time to write these specifications and for tools to follow.
So nobody needs to panic.
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?
Well, that's, that's 12 months long, isn't it?
So
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.
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.
So like, someone needs to be thinking about the future instead of just
going, don't change anything.
It's scary.
Lorna Mitchell: Me it is
about doing good rep, good support
for 3.1.
Lots of people are coming into APIs or raising their API
game now with what's available today.
And I
think, you know, I work in developer experience.
I really care about stuff that you can do today, and so that's my focus.
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.
But also.
Lorna Mitchell: is one of the requirements.
Yes,
Track 1: Okay, good , because various tooling vendors.
Lorna Mitchell: They got it.
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
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
else, but this thing, this thing exists and, and the majority of tools can use it.
And an open API majority of the tools are TypeScript or no something.
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.
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.
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.
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 at code these days.
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
Track 1: Yeah.
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.
But I think feature, I think the competition has helped because
it's very open source, isn't it?
It's, it's a,
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
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
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 need from a, a shared passer.
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.
You know, like that would be pretty messed up.
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.
It doesn't have the same ecosystem.
They just build their own tools.
They're all quite closely coupled.
It's the same people.
Track 1: Right.
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, and the tools is
a really big differentiator.
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?
'cause that'll be cool.
Although I gotta talk to the optic team about, they've just come up with um,
lint, GPT, where you just write your rules as a, an array of strings and
hope that the wizard is consistent.
But
I'm gonna give that to all a try
Lorna Mitchell: I think Optic currently have the best
converters, so they understand this problem space, but because.
Track 1: Yeah.
Yeah.
Lorna Mitchell: Redoc, CLI, all our linting is very like
a ST data structure driven.
It's not
JSON path driven like the others.
My, I had a quick look and I was like, oh, this is gonna be really difficult.
Interrupt because we are not describing, you
know, 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.
Track 1: Right.
Lorna Mitchell: Turn, turn left at this array.
Then take the third success response element.
You know, like
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.
I shouldn't have opened up this can of worms so late in the podcast.
We like
Lorna Mitchell: we're gonna still
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.
For sure.
Lorna Mitchell: That
would be awesome.
Track 1: for coming,
Lorna Mitchell: for having me.
Track 1: Cheers.
Bye.