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?
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.