WEBVTT
NOTE
This file was generated by Descript
00:00:01.320 --> 00:00:04.470
Phil: Hello everyone, and welcome
to another episode of APIs.
00:00:04.470 --> 00:00:08.580
You won't hate the podcast, it's
the audio version Instead of blog
00:00:08.580 --> 00:00:11.340
posts, we're here talking about APIs.
00:00:11.400 --> 00:00:15.210
And today I've got Joel Claremont
with me, who is well known around
00:00:15.210 --> 00:00:19.390
the Laravel PHP community but
might be new to some of you folks.
00:00:19.390 --> 00:00:20.800
So Joel, Hello.
00:00:21.190 --> 00:00:21.940
what's going on?
00:00:23.035 --> 00:00:23.695
Joel Clermont: Not too much.
00:00:23.695 --> 00:00:26.030
Yeah, I've listened to some
of your episodes here and I'm
00:00:26.030 --> 00:00:28.730
like, I am definitely not in
the API dev tooling space.
00:00:28.730 --> 00:00:30.050
That is not my specialty.
00:00:30.480 --> 00:00:34.440
, I'm coming at this more as the,
the, in the trenches practitioner
00:00:34.440 --> 00:00:38.880
building, shipping, supporting
APIs and not, not like the higher
00:00:38.880 --> 00:00:40.770
level tooling person that's
00:00:40.770 --> 00:00:42.210
building things for other people to
00:00:42.450 --> 00:00:43.590
Phil: Well that's, that's fine.
00:00:43.590 --> 00:00:49.530
So we're not, we, we have, because I
have been working in the kind of open API
00:00:49.530 --> 00:00:53.010
dev tooling space, a lot of the content
ends up being quite specific to that.
00:00:53.160 --> 00:00:54.780
And that's not really what this
00:00:54.780 --> 00:00:55.860
podcast is meant to be like.
00:00:55.860 --> 00:00:57.000
If you cast your
00:00:57.000 --> 00:01:00.870
mind back to way back when of
the origins of this, of APOs, you
00:01:00.870 --> 00:01:04.270
weren't hate as a an anything before
it was a community in a podcast.
00:01:04.510 --> 00:01:05.440
I was writing that book.
00:01:05.795 --> 00:01:09.525
Build APIs you won't hate, which was
pretty much how to make rest Dish APIs
00:01:09.620 --> 00:01:11.655
in Laravel and all of it was Laravel.
00:01:11.685 --> 00:01:11.835
So
00:01:11.835 --> 00:01:15.075
it's lovely to be chatting to Laravel
people and I still build APIs in
00:01:15.075 --> 00:01:19.215
Laravel and I think it's important
that we don't, like, I don't want to
00:01:19.215 --> 00:01:23.805
kind of separate out that there's the,
the API community and then like all of
00:01:23.865 --> 00:01:27.285
the, the programmers who are actually
building APIs in various frameworks.
00:01:27.285 --> 00:01:29.115
They're all, it's all overlap overlapping
00:01:29.115 --> 00:01:29.655
circles.
00:01:29.955 --> 00:01:31.385
And, whenever I'm talking to people
00:01:31.415 --> 00:01:31.955
about like.
00:01:32.355 --> 00:01:35.625
One of the main things in, in API derail,
I always try and explain to folks is that
00:01:35.625 --> 00:01:40.575
like if you go to API conferences and
you only ever talk about APIs and you
00:01:40.575 --> 00:01:45.285
sell your products to other people who
care about APIs, it's a very small world.
00:01:45.285 --> 00:01:50.365
But if you go to Laravel, PHB meetups and
and things like that, then there's actual
00:01:50.365 --> 00:01:53.335
people who might end up using your stuff
who have never heard about any of the
00:01:53.335 --> 00:01:56.305
wonderful, lofty things you've been
talking about and really should have.
00:01:56.545 --> 00:01:59.135
So that's kind of why I'm talking
to you today of, yeah, you're
00:01:59.135 --> 00:02:04.635
posting about like how, how you
like to make API specs with Laravel
00:02:04.665 --> 00:02:08.615
or how you don't, so you wrote an
article called I have It right here.
00:02:08.795 --> 00:02:12.275
Why I Don't Like Generating API Specs,
which is written nail on the head.
00:02:12.525 --> 00:02:14.685
do you wanna tell me a
little bit more about this?
00:02:14.685 --> 00:02:17.985
And you said there's a series of
blog posts and like what led to this?
00:02:17.985 --> 00:02:18.465
Tell me more.
00:02:18.740 --> 00:02:22.730
Joel Clermont: Yeah, it, it actually
started like, I think the, so, so, first
00:02:22.730 --> 00:02:26.720
of all, for a little context, I, I have
a site called mastering laravel.io and
00:02:27.050 --> 00:02:30.860
I publish, for some reason, I committed
to a daily newsletter Monday through
00:02:30.860 --> 00:02:33.110
Friday, and I, I cross post to the site.
00:02:33.110 --> 00:02:36.980
But so any, any random thought that
pops into my head, I'm like, oh,
00:02:36.980 --> 00:02:38.090
that could make an email, right?
00:02:38.090 --> 00:02:39.440
So I'll, I'll, I'll write it down.
00:02:40.010 --> 00:02:46.610
And I was working on a project recently
building an API for a Laravel company.
00:02:46.880 --> 00:02:51.100
And we were writing the spec and,
and the client, like they, they're
00:02:51.100 --> 00:02:53.950
an existing product and they're
like, we've never written a spec.
00:02:53.950 --> 00:02:55.510
Like we only have an internal team.
00:02:55.510 --> 00:02:55.570
I.
00:02:56.125 --> 00:02:58.765
And so that kind of started
the discussion, which is
00:02:58.765 --> 00:03:00.745
like, I think it's useful.
00:03:00.865 --> 00:03:05.425
In fact, I know it's useful to have
a spec even if you don't have a giant
00:03:05.425 --> 00:03:08.695
team, even if you don't have like a
separate frontend and backend team.
00:03:08.695 --> 00:03:12.655
I think like even if it's a full
stack small team or a single dev,
00:03:12.860 --> 00:03:14.545
it, it is nice to have a spec.
00:03:14.575 --> 00:03:15.955
It, it sort of keeps you honest.
00:03:15.955 --> 00:03:20.020
And so that, that was the, the start
of the whole discussion in, in the
00:03:20.020 --> 00:03:23.020
newsletter, but then it ultimately led
to, okay, hopefully I've convinced you.
00:03:23.545 --> 00:03:24.895
Now how do I get started?
00:03:24.925 --> 00:03:30.055
And where most developers like to go
is, well, let's use code to do it right?
00:03:30.055 --> 00:03:31.015
Like, that's what we do.
00:03:31.315 --> 00:03:35.235
And I personally have never had
success with that approach outside
00:03:35.265 --> 00:03:39.345
of like demos and a proof of
concept or maybe like breaking
00:03:39.345 --> 00:03:41.175
ground on something to get started.
00:03:41.625 --> 00:03:43.335
But the code first approach.
00:03:44.100 --> 00:03:45.570
Has been problematic for me.
00:03:45.570 --> 00:03:48.090
And so that, that was, that was where
my experience was coming from and I
00:03:48.090 --> 00:03:52.320
was trying to share that, like, it's
not that complicated to like just write
00:03:52.500 --> 00:03:55.350
the file yourself and, and I think
there's actually some benefits to it.
00:03:56.370 --> 00:03:59.340
Phil: I mean, so many developers are
running about, like, everyone has
00:03:59.340 --> 00:04:02.430
to learn Kubernetes and everyone has
to learn these 25 different things.
00:04:02.640 --> 00:04:03.240
Comically.
00:04:03.240 --> 00:04:05.910
Most of those do end up
being slightly overloaded.
00:04:05.940 --> 00:04:07.150
yaml DSLs.
00:04:07.310 --> 00:04:11.340
But the idea of learning this
one other yaml DSL is completely
00:04:11.340 --> 00:04:12.960
unacceptable to anyone
and we'll never do it.
00:04:13.060 --> 00:04:14.280
And, That's pretty funny.
00:04:14.580 --> 00:04:16.890
So just in case, there are
people who haven't heard me
00:04:16.890 --> 00:04:18.600
banging on about open API in the past.
00:04:18.840 --> 00:04:22.890
Joel says spec, he means API
specification, which is one other
00:04:23.010 --> 00:04:27.420
term for like API description
or API design document.
00:04:27.420 --> 00:04:30.490
There's a million different names of
this stuff, but yeah, basically it's
00:04:30.490 --> 00:04:30.730
like.
00:04:30.960 --> 00:04:34.770
I'm gonna, I'm gonna describe the
endpoints and properties and parameters
00:04:34.770 --> 00:04:39.930
and request bodies and all the bits
of the, the interface of the API with
00:04:39.930 --> 00:04:41.910
some sort of machine language, which.
00:04:43.450 --> 00:04:45.040
tools can use generally for docs.
00:04:45.430 --> 00:04:47.620
Pretty handy for mocks
and loads of other stuff.
00:04:47.770 --> 00:04:51.140
And I've built a spectral API scanner.
00:04:51.210 --> 00:04:54.000
So literally you put your open
API in and it goes, oh, that's
00:04:54.000 --> 00:04:54.990
gonna get you hacked buddy.
00:04:54.990 --> 00:04:55.620
Watch out for that.
00:04:55.650 --> 00:04:58.980
There's a million things you can do with,
with an API spec when you've got it.
00:04:59.460 --> 00:05:02.850
But yeah, when, when
left are the developers.
00:05:03.810 --> 00:05:05.130
I'm picking up on what
you said a minute ago.
00:05:05.130 --> 00:05:07.720
Like the, if you leave it to the
developers they're just gonna
00:05:07.720 --> 00:05:08.620
write a whole bunch of code.
00:05:08.740 --> 00:05:11.260
And if you, if they ask you, if
you ask them for documentation,
00:05:11.260 --> 00:05:14.270
they'll go and write down like 10
lines somewhere and it'll be bad.
00:05:14.510 --> 00:05:16.820
So at some point over the last I.
00:05:17.140 --> 00:05:18.470
I don't know, eight five.
00:05:18.650 --> 00:05:21.830
Over the last five years specifically,
I feel like open API has picked
00:05:21.830 --> 00:05:23.510
up in popularity massively.
00:05:23.600 --> 00:05:26.330
And that's partly 'cause people like
me bang on about it all the time.
00:05:26.330 --> 00:05:29.390
But it's bloody useful for
everyone to know what's going on.
00:05:29.690 --> 00:05:33.320
And you've got that machine learnable
format, so you, and, and you've got this,
00:05:33.680 --> 00:05:37.130
this spec where you can generate some
docs and you can use it for contract
00:05:37.130 --> 00:05:40.250
testing in a million things to, and
that helps keep those docs up to date.
00:05:40.970 --> 00:05:42.800
But some folks don't like
00:05:42.800 --> 00:05:43.370
to write.
00:05:43.440 --> 00:05:45.690
That YAML out by hand.
00:05:45.720 --> 00:05:46.740
'cause that is pretty boring.
00:05:47.310 --> 00:05:48.420
There's a bunch of other ways of doing it.
00:05:48.420 --> 00:05:51.930
There was gooeys and things, but people
don't like to write that by hand and
00:05:51.930 --> 00:05:56.190
instead they try a bunch of creative
ways to avoid having to write that.
00:05:56.520 --> 00:05:57.210
You were talking about in
00:05:57.210 --> 00:05:59.730
Laravel, there's a few kind
of Laravel specific tools.
00:05:59.730 --> 00:06:01.920
How, how do, how do
people do it in Laravel?
00:06:01.920 --> 00:06:05.130
How do they get, how do they get
their code spitting out open API
00:06:05.130 --> 00:06:05.970
so they don't have to write it.
00:06:09.195 --> 00:06:12.405
Joel Clermont: Yeah, it's what you might
expect if, if, even if you're not in
00:06:12.405 --> 00:06:16.515
Laravel, you know, where, where there's
some, some element of static analysis
00:06:16.725 --> 00:06:20.775
and then that can be enhanced with
some sort of annotations or like inline
00:06:20.775 --> 00:06:26.805
documentation to, to enhance it further
or to specify like examples of things.
00:06:27.070 --> 00:06:27.290
Phil: Mm.
00:06:28.275 --> 00:06:30.705
Joel Clermont: and I probably
should say like I've.
00:06:31.890 --> 00:06:33.240
At least not super recently.
00:06:33.240 --> 00:06:37.260
I've never actually tried to use
one of those packages in earnest.
00:06:37.260 --> 00:06:40.710
Like, I will try, somebody
will recommend one, and I'll be
00:06:40.710 --> 00:06:41.760
like, oh, I'll give it a shot.
00:06:41.820 --> 00:06:43.260
And I usually get a couple days into it.
00:06:43.260 --> 00:06:47.470
I'm like no, this is, it is just, it
ends up, you're just conforming to a
00:06:47.470 --> 00:06:52.540
different layer of abstraction in the
sa in the same sort of specification.
00:06:52.540 --> 00:06:55.180
And so, it's, it's
really a personal thing.
00:06:55.180 --> 00:06:58.180
Like I'm sure there are teams out there
that do this and it works great and
00:06:58.180 --> 00:07:02.830
I'm sure there are use cases where it,
it's beneficial, but I'm generally not
00:07:02.830 --> 00:07:05.560
working on massive, massive projects.
00:07:05.560 --> 00:07:11.250
You know, like, like maybe there's 50
to a hundred API endpoints and a lot of
00:07:11.250 --> 00:07:13.710
times there might not
even be a public consumer.
00:07:13.810 --> 00:07:14.320
Is it
00:07:15.580 --> 00:07:15.970
okay.
00:07:15.970 --> 00:07:16.990
I mean, it's not stripe.
00:07:17.395 --> 00:07:18.385
Phil: right now, but yeah.
00:07:18.775 --> 00:07:19.195
Fair enough.
00:07:20.050 --> 00:07:23.590
Joel Clermont: Okay, well I'm
counting like get versus post too,
00:07:23.680 --> 00:07:23.980
right?
00:07:23.980 --> 00:07:25.780
So, you know, in terms of
00:07:25.780 --> 00:07:29.080
resources it's probably a lower
number, but, but yeah, it's, it's
00:07:29.080 --> 00:07:34.510
not, I don't work on teams of like
50 developers and you know, that
00:07:34.540 --> 00:07:39.940
like, so there's probably some
efficiencies that become more.
00:07:40.599 --> 00:07:43.630
Important and beneficial where the
trade offs might skew the other
00:07:43.630 --> 00:07:46.030
direction toward code first tooling.
00:07:46.510 --> 00:07:48.340
IJI just am not there and
00:07:48.669 --> 00:07:51.039
I here, maybe this is a
question for you, Phil.
00:07:51.669 --> 00:07:54.999
Are there any tools that you've
seen that do spec generation,
00:07:54.999 --> 00:07:56.590
that actually leverage the spec?
00:07:56.590 --> 00:07:59.410
Like things like refs and, you
know, things like that Or is does
00:07:59.410 --> 00:08:03.580
it end up spitting out some really
flat, verbose document that no
00:08:03.580 --> 00:08:05.020
human would ever write in that way?
00:08:05.305 --> 00:08:06.265
Phil: Yeah, that's the problem.
00:08:06.265 --> 00:08:11.785
Most of those tools will just kind of
just vomit something upwards, which is not
00:08:11.844 --> 00:08:12.805
particularly.
00:08:13.614 --> 00:08:14.215
Helpful.
00:08:14.274 --> 00:08:17.575
I mean, it generally, it, that
sort of stuff doesn't really
00:08:17.575 --> 00:08:20.634
matter if you are just putting it
straight into a documentation tool.
00:08:20.664 --> 00:08:22.465
'cause the documentation
tools will flatten it.
00:08:22.984 --> 00:08:27.034
so yeah, the, the way, the
way that it seems to me is.
00:08:28.250 --> 00:08:33.650
Somebody has said, Hey, we've,
we've started using open API to
00:08:33.859 --> 00:08:37.520
have one kind of documentation
hub, a developer portal, whatever.
00:08:37.849 --> 00:08:41.659
We've got this, we've got this thing,
and we need all the teams to make open
00:08:41.659 --> 00:08:43.099
API and we don't care how you do it.
00:08:43.099 --> 00:08:43.729
I've been that guy.
00:08:43.729 --> 00:08:44.509
I've, I've done that.
00:08:44.679 --> 00:08:47.949
And I'm like, you know, some of them are
like, oh, we've got it all in Postman,
00:08:47.949 --> 00:08:49.714
so we'll convert it into open api.
00:08:49.719 --> 00:08:50.829
I, I'm like, sure, whatever.
00:08:51.099 --> 00:08:54.039
And some of them are like, oh, we've
got open API two or Raml or these
00:08:54.039 --> 00:08:55.689
different old kind of defunct formats.
00:08:55.689 --> 00:08:56.889
And I'm like, whatever, I can
00:08:56.889 --> 00:09:00.099
convert that for you and, and or, you
know, and then eventually you end up
00:09:00.099 --> 00:09:01.719
with open API and everyone's like, great.
00:09:01.719 --> 00:09:04.689
Some of it's weird and some of it's ugly
and some of it's not entirely right.
00:09:04.689 --> 00:09:08.469
But that's a step one is we now have one
documentation hub for the entire thing.
00:09:08.469 --> 00:09:08.859
Great.
00:09:09.229 --> 00:09:09.680
But then over
00:09:09.680 --> 00:09:12.409
time it's a case of like, well, how
do we get this to be more useful?
00:09:12.829 --> 00:09:13.279
And.
00:09:13.454 --> 00:09:15.434
And how do we use this for
more verticals as well?
00:09:15.434 --> 00:09:18.644
Like if you are just shoving it
into docs, then it kind of makes
00:09:18.644 --> 00:09:23.244
that nice stripe, like three coal
API stuff that everyone wants.
00:09:23.244 --> 00:09:23.484
But
00:09:23.784 --> 00:09:27.564
if you try and use it for, you know,
code generation and a bunch of other
00:09:27.564 --> 00:09:30.874
use cases, it, it kind of falls apart
and you can't it gets a bit hard
00:09:30.874 --> 00:09:32.674
to like add stuff to it as well.
00:09:32.674 --> 00:09:32.914
So.
00:09:33.464 --> 00:09:39.794
the one thing I've seen, which helps, if,
so, if you've got a API spec that's being
00:09:39.794 --> 00:09:45.494
kind of just a magic appeared out of your
API one thing, that can be pretty handy.
00:09:45.494 --> 00:09:46.874
Have you heard of open API Overlays?
00:09:48.774 --> 00:09:48.994
Joel Clermont: Mm.
00:09:49.349 --> 00:09:49.619
No.
00:09:50.069 --> 00:09:51.329
Phil: It's this like extension thing.
00:09:51.329 --> 00:09:56.329
So open APIs started doing like working
groups or special interest groups.
00:09:56.639 --> 00:09:58.919
And these special interest
groups create different things.
00:09:58.919 --> 00:10:02.429
So they're doing like workflows so you
can document entire kind of workflows
00:10:02.429 --> 00:10:04.469
of, of API calls and things like that.
00:10:04.769 --> 00:10:08.069
And one of them is overlays
where you can basically.
00:10:08.694 --> 00:10:09.984
It's kind of like a spectral rule set.
00:10:09.984 --> 00:10:12.624
If you're familiar, you kind of
have like a J path and you're like,
00:10:12.924 --> 00:10:17.184
go to this bit of the document and
then like add this or remove this.
00:10:17.574 --> 00:10:23.544
And so you can theoretically have some
horrendously vomited out, open API and
00:10:23.544 --> 00:10:26.094
then be like, and I'm gonna add some
descriptions in here, which are like
00:10:26.094 --> 00:10:29.484
10 paragraphs long and have a bunch of
markdown so you can have your technical
00:10:29.484 --> 00:10:31.704
writers kind of wedging that stuff in.
00:10:32.184 --> 00:10:32.964
And so.
00:10:34.469 --> 00:10:38.429
My, my initial like, no one should ever
do code first ever, because then you have
00:10:38.429 --> 00:10:44.309
this useless thing is, is somewhat kind of
abated a bit where it's like, okay, you,
00:10:44.339 --> 00:10:47.759
you've, you've given us this useless thing
and now some technical writers can jump
00:10:47.759 --> 00:10:52.519
through some quite horrendous hoops to
make it a bit less useless, but that still
00:10:52.519 --> 00:10:55.549
isn't like the most
shining endorsement for it.
00:10:57.034 --> 00:10:59.644
Joel Clermont: you know, like you
mentioned, if if, if the only people
00:10:59.644 --> 00:11:04.834
reading the spec are doing so via
like a generated HTML portal, then
00:11:04.834 --> 00:11:09.154
it, it doesn't probably matter
internally if it's using like refs for
00:11:09.154 --> 00:11:10.624
shared schemas and things like that.
00:11:10.654 --> 00:11:11.014
But
00:11:11.374 --> 00:11:15.124
I, you know, just like I'm thinking and
recommending you write it by hand at
00:11:15.124 --> 00:11:16.504
least once, at least know how to do it.
00:11:16.774 --> 00:11:17.344
I also.
00:11:17.419 --> 00:11:20.419
I think like, I like to look
at the spec by hand too.
00:11:20.419 --> 00:11:20.629
Like
00:11:20.629 --> 00:11:24.559
the, the tool, the tooling is great
to auto generate fancy, nice branded
00:11:24.559 --> 00:11:28.339
documentation, but I, I do find some
value looking at the spec directly and
00:11:28.339 --> 00:11:33.949
then especially seeing, oh, this, you
know, this specific type of request
00:11:33.949 --> 00:11:36.979
or this, you know, form payload is
00:11:36.979 --> 00:11:38.059
used more than one place.
00:11:38.059 --> 00:11:42.049
Like that tells me something about
the overall API design that you don't
00:11:42.049 --> 00:11:43.669
see if it's just all flattened out.
00:11:44.149 --> 00:11:44.569
Phil: Mm.
00:11:45.019 --> 00:11:46.189
Yeah, I mean, that's a useful thing.
00:11:46.189 --> 00:11:49.309
So kind of having intent.
00:11:49.774 --> 00:11:54.364
Written somewhere else outside of
the code, not only helps you spot
00:11:54.604 --> 00:11:58.174
obvious mistakes from a wider pool
of people that don't necessarily
00:11:58.174 --> 00:12:00.184
know how Laravel works but
00:12:00.729 --> 00:12:03.274
it, it just becomes a, it
becomes a lot more useful.
00:12:03.274 --> 00:12:05.194
Like you can have a bunch of
people doing design reviews that
00:12:05.194 --> 00:12:07.804
literally don't know Laravel and
don't know its random conventions.
00:12:07.804 --> 00:12:09.544
And, and it also means that if
00:12:09.544 --> 00:12:12.994
you accidentally have a slip of the
keyboard and, and change some code.
00:12:14.094 --> 00:12:18.024
You didn't necessarily change all of
the annotations that came with it then.
00:12:18.024 --> 00:12:21.609
I, the graphic I used on a blog post
talking about this was like a, a
00:12:21.609 --> 00:12:24.729
drinks cabinet with a labeled that as
milk and it's clearly orange juice.
00:12:24.939 --> 00:12:28.109
Like people kind of confuse
the like proximity with
00:12:28.109 --> 00:12:32.039
accuracy if like these annotations are
somewhat near the code I'm describing.
00:12:32.039 --> 00:12:35.009
So I'm sure someone will definitely
remember to update them both.
00:12:35.699 --> 00:12:36.329
And so.
00:12:36.674 --> 00:12:39.604
Kind of having it in that second
place means you can then kind of you,
00:12:39.604 --> 00:12:42.964
you have those extra checks where
you, you use that open API as an
00:12:42.964 --> 00:12:47.194
assertion in your contract test that
says, does my code match what I think
00:12:47.194 --> 00:12:50.644
it does and what the design review
team think it does, and what everyone
00:12:50.644 --> 00:12:52.174
involved so far has thought it would.
00:12:52.654 --> 00:12:56.184
And so that, that for me is kind of
why I'm a big fan of the approach.
00:12:57.764 --> 00:13:02.324
But it's, it's just really hard to get
a PA developers to do another thing.
00:13:02.904 --> 00:13:04.014
They're like, I'm a coder.
00:13:04.044 --> 00:13:04.464
I write
00:13:04.464 --> 00:13:04.854
code.
00:13:05.224 --> 00:13:06.635
I would like to write some code for
00:13:06.635 --> 00:13:07.025
this.
00:13:07.115 --> 00:13:09.772
And yeah, it's, it's a weird one.
00:13:09.772 --> 00:13:14.172
Joel Clermont: One of the benefits
I think there is in writing the
00:13:14.172 --> 00:13:16.962
spec separate from the code is like.
00:13:17.907 --> 00:13:21.357
Especially if you start with the
spec is it forces you to think
00:13:21.357 --> 00:13:25.587
through the requirements in a level
of detail that you don't often do.
00:13:25.677 --> 00:13:28.437
You know, if you're getting a
requirement from some stakeholder
00:13:28.497 --> 00:13:31.437
and they're like, Hey, I want an
endpoint to do this, this, and that.
00:13:31.977 --> 00:13:33.627
Okay, well, like who can do that?
00:13:33.687 --> 00:13:34.077
You know?
00:13:34.227 --> 00:13:35.517
How long can that field be?
00:13:35.517 --> 00:13:37.407
Like there's all these constraints that.
00:13:37.962 --> 00:13:41.652
Somebody has to make a decision
on, and like that spec becomes the
00:13:41.652 --> 00:13:44.592
forcing function to decide like,
well, what is the maximum length?
00:13:44.592 --> 00:13:46.932
What, what is the format
on this date time?
00:13:46.932 --> 00:13:47.292
Or, you know,
00:13:47.472 --> 00:13:51.072
just things like that that
otherwise you might get to later
00:13:51.072 --> 00:13:52.542
in the middle of implementation.
00:13:52.572 --> 00:13:54.672
And a dev just like, well, I
guess we'll just do it this way.
00:13:54.672 --> 00:13:56.682
And it wasn't actually
discussed or decided on.
00:13:57.762 --> 00:13:59.082
Phil: That's a really good point.
00:13:59.232 --> 00:14:05.142
That's I think where I was heading was
that like the API spec being thought of as
00:14:05.772 --> 00:14:11.688
a documentation mechanism is kind of the
problem here because it's it's basically.
00:14:12.048 --> 00:14:12.768
It's not always a problem.
00:14:12.768 --> 00:14:17.428
There are, there are use cases
where you have an API and you
00:14:17.428 --> 00:14:18.988
need to like play catch up, right?
00:14:18.988 --> 00:14:21.018
There's the there's,
there's API design first.
00:14:21.018 --> 00:14:23.928
There's API code first, and the,
and I've done polls where it's
00:14:23.928 --> 00:14:25.998
like, are using API code first.
00:14:25.998 --> 00:14:26.898
API design first.
00:14:27.313 --> 00:14:29.773
Switching from one to the other
or some awkward combination.
00:14:29.773 --> 00:14:32.323
And every time I do this, every
couple of years, the answer's
00:14:32.323 --> 00:14:33.883
always like 25% of each.
00:14:35.053 --> 00:14:37.273
So people, there are some
teams who are doing code
00:14:37.273 --> 00:14:40.033
first, some are doing design first,
and, and it's just all over the place.
00:14:40.423 --> 00:14:46.633
But yes, like those, those tools that
can help you kind of grab a whole
00:14:46.633 --> 00:14:50.473
bunch of metadata out of your code
through static analysis and maybe
00:14:50.473 --> 00:14:51.793
you add a few other things in there.
00:14:52.618 --> 00:14:54.718
Can really help you get a head start.
00:14:54.748 --> 00:14:55.708
And then you have the open
00:14:55.708 --> 00:14:59.368
API that you can go back and put
assertions into your code base
00:14:59.368 --> 00:15:00.328
to make sure that it's correct.
00:15:00.328 --> 00:15:01.588
And then you can expand that.
00:15:01.888 --> 00:15:04.468
And if you want to add a new
endpoint, then you can design first
00:15:04.468 --> 00:15:06.808
on that, on that open API file.
00:15:06.808 --> 00:15:10.228
You can add a new endpoint that's
completely imaginary, start working on it.
00:15:10.438 --> 00:15:12.418
Have everyone agree whether
that's a good idea or not.
00:15:12.418 --> 00:15:14.248
Whether it solves,
solves the needs or not.
00:15:14.548 --> 00:15:17.698
Run it through a mock generator,
a mock server so that people can
00:15:17.698 --> 00:15:19.498
interact with it before it even exists.
00:15:19.818 --> 00:15:20.748
And then later on.
00:15:21.513 --> 00:15:25.323
Code it and make sure that it
matches the contract test for that.
00:15:25.843 --> 00:15:29.083
But do you think, do you think
that's how everyone should work?
00:15:29.233 --> 00:15:32.918
Joel Clermont: I like your use
case because I, I do join a lot
00:15:32.918 --> 00:15:37.058
of, I'll call 'em legacy projects
where you don't have documentation.
00:15:37.058 --> 00:15:37.508
In fact,
00:15:37.568 --> 00:15:39.698
I hate to say this, sometimes
you don't have tests, right?
00:15:39.698 --> 00:15:39.968
Like,
00:15:40.328 --> 00:15:45.788
and so that I could see as a useful
time to generate something just,
00:15:45.788 --> 00:15:47.018
just to get a starting point.
00:15:47.648 --> 00:15:50.828
And then edit it from there, and then
like, you know, write contract tests
00:15:50.828 --> 00:15:52.838
around the little bits as you go.
00:15:53.168 --> 00:15:57.218
And, and so I, I gotta remember
that because a lot of times when
00:15:57.218 --> 00:16:00.308
I join a project, like decisions
have already been made and now
00:16:00.308 --> 00:16:01.418
you're just trying to catch up.
00:16:01.478 --> 00:16:04.478
And I, I think code generation could
be an excellent use case for that.
00:16:04.478 --> 00:16:07.148
Just to, to get you to
where you wanna go faster.
00:16:07.773 --> 00:16:11.103
And to not have to write all of that
by hand and, and reverse engineer it.
00:16:11.133 --> 00:16:11.763
You know, like try to
00:16:11.763 --> 00:16:15.363
figure out, well what are all
the overlapping validation rules
00:16:15.363 --> 00:16:18.483
or schema constraints in the
database layer or things like that.
00:16:18.603 --> 00:16:20.703
A static analysis can get you 80% there.
00:16:21.413 --> 00:16:21.833
Phil: for sure.
00:16:22.273 --> 00:16:22.778
I think.
00:16:23.198 --> 00:16:26.239
An interesting third way I've come
across, and we've written about
00:16:26.239 --> 00:16:30.469
it a bit on the blog, is kind of
using HTP traffic inspection, right?
00:16:30.779 --> 00:16:34.319
So I've, I've definitely
inherited APIs where no one
00:16:34.319 --> 00:16:35.699
knows how the heck this works.
00:16:35.699 --> 00:16:38.069
You've gotta like decompile the iPhone app
00:16:38.069 --> 00:16:40.409
and there's some third party client
that you can't even look at the
00:16:40.409 --> 00:16:44.399
code of and, and like no one can
get into the compiled Java app on
00:16:44.399 --> 00:16:47.369
some bloody API that people haven't
got the password for anymore.
00:16:47.369 --> 00:16:50.579
It sounds silly, but I've been in these
silly situations that help out a lot of
00:16:50.579 --> 00:16:50.909
struggling
00:16:51.029 --> 00:16:51.269
Joel Clermont: boy.
00:16:51.869 --> 00:16:54.299
Phil: And everyone's like, right,
we've gotta rebuild this API.
00:16:54.299 --> 00:16:57.119
And you're like, what API if I can't
find any of the endpoints, like,
00:16:57.119 --> 00:16:58.469
everyone, check your browser history.
00:16:58.469 --> 00:16:59.129
What are we doing here?
00:16:59.499 --> 00:17:00.669
And so being able to
00:17:00.669 --> 00:17:03.569
kind of wrap it in a, in a
traffic proxy that essentially
00:17:03.569 --> 00:17:04.589
says like all the requests.
00:17:05.034 --> 00:17:07.994
Going in, or you can literally, you
can wedge them into the browser.
00:17:08.244 --> 00:17:10.009
And, and then kind of run
around clicking things.
00:17:10.009 --> 00:17:12.709
There's, there's a bunch of these
different tools for sniffing actual
00:17:12.949 --> 00:17:14.589
traffic going through the system.
00:17:15.069 --> 00:17:15.729
And then
00:17:15.729 --> 00:17:19.739
you can kind of take all of
that and output an open API
00:17:19.829 --> 00:17:21.224
file and say, there you go.
00:17:21.404 --> 00:17:25.147
And I feel like if we're, if we're
talking kind of the catching up
00:17:25.147 --> 00:17:28.597
with design first, then I'm almost,
I'm mu I'm, I generally feel more
00:17:28.597 --> 00:17:33.397
interested in going with the traffic
sniffing approach because it's real.
00:17:33.397 --> 00:17:33.457
I.
00:17:34.007 --> 00:17:36.917
Like you can still look at some, look
at some stuff and, and get it wrong.
00:17:36.917 --> 00:17:39.607
Like if, if when you've got these
complicated dynamic payloads where
00:17:39.607 --> 00:17:42.037
there's this or this or this, that
could come through and you're like,
00:17:42.037 --> 00:17:44.737
it's definitely only this 'cause you've
only seen it come, you know, you haven't
00:17:44.737 --> 00:17:46.207
noticed any null values in there.
00:17:46.207 --> 00:17:48.007
So you said it, it is a required property.
00:17:48.007 --> 00:17:50.407
Mistakes like that can be
made depending on how much
00:17:50.707 --> 00:17:51.997
the sample size goes through.
00:17:52.507 --> 00:17:58.627
But I, I feel like the promise
of having these kind of framework
00:17:58.627 --> 00:18:00.517
integrated static analysis.
00:18:01.012 --> 00:18:06.532
Tools is potentially misleading
unless they can hook into enough
00:18:06.832 --> 00:18:10.612
where you literally don't need
to add other stuff yourself.
00:18:10.612 --> 00:18:14.092
'cause as soon as you ask the humans
to get involved, that's when they're
00:18:14.092 --> 00:18:15.502
just introducing human error.
00:18:16.042 --> 00:18:17.632
Have you come across anything like that?
00:18:17.835 --> 00:18:18.125
Joel Clermont: Yeah.
00:18:18.130 --> 00:18:19.180
Um, Not directly.
00:18:19.210 --> 00:18:20.920
'cause again, I've not worked on a project
00:18:21.250 --> 00:18:23.950
recently that has done the
automated tooling, but, but I've,
00:18:24.490 --> 00:18:26.470
I've experienced drift for sure.
00:18:26.680 --> 00:18:30.280
And, and honestly that's one of my fears
with Code Generation, I, you alluded
00:18:30.280 --> 00:18:33.820
to it earlier, is like if you make
an unintentional change, well, and it
00:18:33.820 --> 00:18:35.710
just regenerates the spec to match it.
00:18:35.740 --> 00:18:38.295
Now your tests are still passing, but I.
00:18:38.770 --> 00:18:42.430
Unless a human catches that in code
review or design review of some sort,
00:18:42.430 --> 00:18:45.940
like you could unintentionally change
your API even in a breaking way,
00:18:45.940 --> 00:18:51.000
which to me is like the worst possible
outcome of of, of, of an API change.
00:18:51.000 --> 00:18:54.120
So I don't know if there's solutions
to that, but yeah, the, either
00:18:54.120 --> 00:18:58.257
the intentional or unintentional
drift is just, just an ongoing
00:18:58.257 --> 00:18:59.547
problem I have experienced,
00:18:59.947 --> 00:19:03.487
With that traffic inspection like
that's super useful for like sort of
00:19:03.487 --> 00:19:04.957
those black box scenarios you were
00:19:04.957 --> 00:19:05.527
describing.
00:19:05.527 --> 00:19:07.447
Like, I'm gonna have
nightmares about that.
00:19:07.447 --> 00:19:12.607
But I, I'm almost wondering too if
like that in conjunction, like when
00:19:12.607 --> 00:19:14.857
you're, when you're, when I'm joining
a project, like I'm coming into some
00:19:14.857 --> 00:19:20.077
project, if I, if I just use static
analysis, that doesn't tell me.
00:19:20.602 --> 00:19:22.072
How much dead code is in there,
00:19:22.222 --> 00:19:22.462
right?
00:19:22.462 --> 00:19:26.332
And like now, maybe I'm wasting a week of
work trying to document and test something
00:19:26.332 --> 00:19:27.672
and then I, ship it to the client.
00:19:27.672 --> 00:19:29.292
They're like, oh, we haven't
used that in five years.
00:19:29.322 --> 00:19:29.712
Like that.
00:19:29.712 --> 00:19:31.392
Well, that was just a
wasted week of effort.
00:19:31.872 --> 00:19:36.582
So I could see pairing the static
analysis with the traffic analysis
00:19:36.612 --> 00:19:38.592
just to like, even to prioritize.
00:19:39.087 --> 00:19:40.827
These are the paths that
get the most traffic.
00:19:40.857 --> 00:19:41.067
Like
00:19:41.067 --> 00:19:42.147
let's focus on those.
00:19:42.507 --> 00:19:44.427
These endpoints, they never got traffic.
00:19:44.667 --> 00:19:47.277
Oh, I'll ask the client even
before I start working on it.
00:19:47.307 --> 00:19:47.757
Oh yeah.
00:19:47.817 --> 00:19:48.777
We can just delete that.
00:19:48.807 --> 00:19:49.047
Right?
00:19:49.047 --> 00:19:53.307
Like, so I could see a hybrid
approach there being useful too.
00:19:53.907 --> 00:19:54.357
Phil: Yeah.
00:19:54.567 --> 00:19:55.107
Interesting.
00:19:55.917 --> 00:19:58.107
The I've seen a few frameworks that are.
00:20:00.162 --> 00:20:03.822
me love the idea of code
first a little bit more.
00:20:04.282 --> 00:20:04.552
I wrote
00:20:04.852 --> 00:20:07.132
an article recently and I can't remember
the names of any of these things.
00:20:07.212 --> 00:20:12.682
I think it's like Hu Hugo Oh,
Hummer in, in Node and Fast.
00:20:12.682 --> 00:20:13.177
API I.
00:20:13.177 --> 00:20:15.172
I'll get some problem links in
the show notes when I remember.
00:20:15.172 --> 00:20:18.162
But there, there are, there's
this kind of new idea of like
00:20:18.192 --> 00:20:20.712
open API Aware frameworks, right?
00:20:20.712 --> 00:20:21.282
Like built.
00:20:21.627 --> 00:20:26.097
Into the core of the framework is
in the past, in the past you've got
00:20:26.097 --> 00:20:27.477
like swagger, PHP, which I hated.
00:20:27.477 --> 00:20:31.137
Like I, I, when I, when I first got
involved with swagger, when I first
00:20:31.137 --> 00:20:33.777
tried to start trying to figure out
how to document an API, I looked
00:20:33.777 --> 00:20:37.257
at swagger, PHP, and went, ah, for
all the reasons we've discussed is
00:20:37.257 --> 00:20:39.057
literally you put a bunch of doc block
00:20:39.057 --> 00:20:41.007
annotations in your code
and hope that it's correct.
00:20:41.427 --> 00:20:43.857
And, and I ran away and then
I ended up doing other things.
00:20:43.857 --> 00:20:46.467
But that's still like the main premise.
00:20:46.737 --> 00:20:50.277
But with modern tools, like like Scribe
is a really cool tool and like props
00:20:50.277 --> 00:20:51.477
to the people that have made this.
00:20:51.777 --> 00:20:53.457
But they, I.
00:20:53.457 --> 00:20:57.567
They've essentially got rid of quite a few
of the annotations because the framework
00:20:57.567 --> 00:21:01.587
is kind of saying that this is a poster
or, or a get, and like they've, they know
00:21:01.587 --> 00:21:02.967
what the URL is from looking at the code.
00:21:02.967 --> 00:21:05.127
They're doing a lot of that
static, static analysis,
00:21:05.427 --> 00:21:08.277
but it's still kind of hacked
into the framework a bit.
00:21:08.817 --> 00:21:11.517
And there's still a certain
amount of duplication.
00:21:11.727 --> 00:21:14.577
And so what I like about
the frameworks that are.
00:21:15.282 --> 00:21:18.972
Coming at this from like the
framework itself will tell you what
00:21:18.972 --> 00:21:23.772
your open API is, because just by
using the framework, we are building
00:21:23.802 --> 00:21:25.152
up all of the bits that you need.
00:21:25.452 --> 00:21:26.442
That seems really cool.
00:21:26.442 --> 00:21:28.872
Like when, when you write
the validation rules for your
00:21:28.872 --> 00:21:33.492
models, they all line up with an
appropriate validation in open API.
00:21:33.762 --> 00:21:39.132
So when you're doing that, it sounds
that that, that to me seems like it
00:21:39.132 --> 00:21:41.262
would be pretty much just fine because.
00:21:42.522 --> 00:21:47.082
The, the main, the main thing of like a PA
design first is it's more about planning.
00:21:47.322 --> 00:21:50.962
You should like plan this thing and
spend a lot more time in the planning
00:21:50.962 --> 00:21:55.012
stage past the whiteboard, but before
you start writing loads of code.
00:21:55.482 --> 00:21:56.832
But if the framework can
00:21:56.832 --> 00:22:00.312
make itself simple enough
that it, the framework is, is.
00:22:00.312 --> 00:22:05.212
Just like a config DSL where you are,
instead of writing open API in yaml,
00:22:05.212 --> 00:22:09.532
you're writing open API in this kind of
a bit of PHB code and it's easy enough to
00:22:09.532 --> 00:22:12.922
read and it makes sense, and then you just
shove a bit of business logic in there
00:22:12.922 --> 00:22:15.622
later that, that to me would be fine.
00:22:15.622 --> 00:22:20.332
That kind of absolves the differences,
removes the differences between open API.
00:22:21.112 --> 00:22:22.912
Well between design first and code first.
00:22:23.342 --> 00:22:25.172
It kind of makes them
become the same thing.
00:22:25.662 --> 00:22:27.972
You just kind of like add your
business logic some other time.
00:22:27.972 --> 00:22:33.342
But none of the tools in Laravel
that I've seen are that, and it's
00:22:33.342 --> 00:22:34.992
quite rare to actually find them.
00:22:35.472 --> 00:22:39.792
And at this point I worry that those
projects are kind of just like hobby
00:22:39.792 --> 00:22:41.802
projects and not a whole thing.
00:22:42.162 --> 00:22:42.642
So
00:22:43.002 --> 00:22:45.762
there's a bit of hope in there, but
I don't think anyone's taken the
00:22:45.762 --> 00:22:47.562
idea too seriously at this point.
00:22:47.562 --> 00:22:47.832
Joel Clermont: Yeah.
00:22:47.917 --> 00:22:51.762
The, the reason this, this came
on my radar recently is there is a
00:22:51.762 --> 00:22:55.542
newer package, like it's not even
at 1.0 in Laravel called Scramble.
00:22:55.632 --> 00:22:55.692
I
00:22:55.692 --> 00:22:57.012
don't, I don't know if
you've seen this one.
00:22:57.062 --> 00:23:00.932
It will look at, like in, in LAR you have
a form request with validation rules.
00:23:00.932 --> 00:23:03.902
It will statically
analyze those rules and.
00:23:04.502 --> 00:23:07.592
Set like max links or field
types or things like that,
00:23:07.802 --> 00:23:10.532
purely based on that with like
zero annotation, which is, I,
00:23:11.342 --> 00:23:13.022
I do like the promise of it.
00:23:13.022 --> 00:23:13.562
I really do.
00:23:13.562 --> 00:23:15.092
Like I, I get the appeal.
00:23:15.722 --> 00:23:20.072
Um, one, one other thing too
I was thinking about is I.
00:23:21.137 --> 00:23:24.377
You know, when you mention whiteboards
and upfront design, like I cringed a
00:23:24.377 --> 00:23:28.367
little bit because like I, I've come
over the years to recognize like you
00:23:28.367 --> 00:23:30.407
never can plan super far in advance.
00:23:30.947 --> 00:23:33.467
And, But I, you know, so one thing
I wanted to clarify is like, even
00:23:33.467 --> 00:23:37.487
with the design first approach,
I generally do it like literally
00:23:37.487 --> 00:23:38.807
end point by end point, right?
00:23:38.807 --> 00:23:42.617
So I, I design it, I write the spec,
we agree on it, I implement it.
00:23:42.997 --> 00:23:45.667
Then we repeat for the next one,
not like, well, let's design the
00:23:45.667 --> 00:23:47.857
entire API and, and see what happens,
00:23:47.857 --> 00:23:50.587
because that, that just
never materializes correctly.
00:23:51.017 --> 00:23:51.317
Phil: man.
00:23:51.317 --> 00:23:54.527
Yeah, it's, it's something that I really,
I need to do a whole episode on this,
00:23:54.527 --> 00:23:58.337
on like, how do you actually plan an
API, because the stuff I said in my book
00:23:58.337 --> 00:23:59.747
was, was pretty immature at the time.
00:23:59.747 --> 00:24:02.147
I think I was like, just think
of all the endpoints you need and
00:24:02.147 --> 00:24:05.147
then like post and get next to
'em or whatever is, is a bit dumb.
00:24:05.677 --> 00:24:09.237
But, but like the phases, the phases,
of of planning and that's like
00:24:09.537 --> 00:24:13.767
literally stakeholder interviews,
which is like a, a, a concept from
00:24:13.767 --> 00:24:15.957
user research and, and, and ux.
00:24:16.337 --> 00:24:21.437
and then kind of taking everyone's
needs and requirements, and not
00:24:21.437 --> 00:24:25.127
necessarily too literally, but
distilling down the essence of what.
00:24:25.287 --> 00:24:29.547
They want and what they need and, and
how multiple different stakeholders
00:24:29.547 --> 00:24:31.107
can ask for different things.
00:24:31.107 --> 00:24:33.597
But finding the middle ground that
will be just fine for everyone, like
00:24:33.597 --> 00:24:34.977
doing all this really complicated work.
00:24:35.477 --> 00:24:39.927
And then another group of people or,
or you, with a different hat on, can
00:24:39.927 --> 00:24:42.477
then start to say, well then these
are the end points that I need.
00:24:42.477 --> 00:24:44.697
But even then, like, is the,
is jumping straight into
00:24:44.697 --> 00:24:46.257
endpoint endpoints premature.
00:24:46.257 --> 00:24:50.027
Like, do, do you need to think a little
bit more about, about kind of the
00:24:50.027 --> 00:24:53.207
workflows and the, and the type of API
that could be used and like, should
00:24:53.207 --> 00:24:56.507
this even be a, a endpoint based API
or should, should it be event driven?
00:24:56.897 --> 00:24:59.927
There's, there's so many stages to the
planning and it's hard to figure out.
00:25:00.257 --> 00:25:03.557
Where you should start and open
API and design the spec first.
00:25:03.557 --> 00:25:05.807
Stuff like it doesn't help
you with any of any of that.
00:25:06.117 --> 00:25:11.187
Like you, literally, your planning
starts with Slack calls and whiteboards
00:25:11.277 --> 00:25:13.627
and like Miro boards and sequence
00:25:13.717 --> 00:25:17.017
sequence flow diagrams and like
chatting to a load of people and
00:25:17.017 --> 00:25:19.957
having a spreadsheet of feedback and
all this crazy stuff that no one,
00:25:20.347 --> 00:25:23.167
no one that I know is really working
on, apart from the tools that I've
00:25:23.167 --> 00:25:24.637
mentioned, but they're like generic.
00:25:25.267 --> 00:25:26.887
And then once someone has says.
00:25:27.172 --> 00:25:32.032
Someone has said, you definitely
need to make a HT PAPI and it
00:25:32.032 --> 00:25:33.382
should probably do these things.
00:25:33.932 --> 00:25:35.672
That's when it's time
to get the open API out.
00:25:35.702 --> 00:25:38.462
'cause you're literally turning the words
they've just said right there of like,
00:25:38.462 --> 00:25:39.992
make an API that does this, this and this.
00:25:39.992 --> 00:25:42.632
Then you kind of are going, well okay,
we'll have that end point, that end
00:25:42.632 --> 00:25:45.032
point and that then end point and.
00:25:45.422 --> 00:25:48.872
Where design first gets really handy
there is you can say, okay, I'm gonna turn
00:25:48.872 --> 00:25:52.262
those words into, like, I'm gonna reshape
them into a little bit of yaml and I'm
00:25:52.262 --> 00:25:54.002
gonna like, the A PO will look like this.
00:25:54.302 --> 00:25:58.412
Then it's much easier to change that
little bit of YAML than it is to go and
00:25:58.412 --> 00:26:00.602
change a whole pile of Laravel code.
00:26:00.602 --> 00:26:04.172
You're like, oh God, now I've got rename
all of my controllers and that means
00:26:04.172 --> 00:26:07.562
I've gotta rename all my models and all
the relationships are gonna be broken.
00:26:07.922 --> 00:26:08.522
And I, you know,
00:26:08.552 --> 00:26:10.112
that's, that's really daft.
00:26:10.112 --> 00:26:10.712
And so
00:26:11.012 --> 00:26:12.212
pretending that.
00:26:12.932 --> 00:26:16.652
Code first is quicker 'cause you just add
some annotations to some code that you
00:26:16.652 --> 00:26:20.552
wrote is predicated on the fact that you
wrote exactly the right code first time.
00:26:20.942 --> 00:26:22.472
And when does that happen?
00:26:24.557 --> 00:26:25.037
Joel Clermont: It doesn't.
00:26:25.037 --> 00:26:25.877
Right, exactly.
00:26:25.877 --> 00:26:26.927
At least not for anything.
00:26:26.932 --> 00:26:27.572
Non-trivial.
00:26:27.572 --> 00:26:29.202
Phil: Yeah, well, alright.
00:26:29.352 --> 00:26:30.642
Pretty decent agreement on that.
00:26:30.972 --> 00:26:31.512
Screw.
00:26:31.962 --> 00:26:32.622
Screw that.
00:26:33.657 --> 00:26:34.167
Joel Clermont: Awesome.
00:26:35.227 --> 00:26:35.742
Phil: That was
00:26:35.787 --> 00:26:38.097
Joel Clermont: See, I I we're far
too reasonable, Phil, in our, in
00:26:38.097 --> 00:26:41.537
our older age and maturity we're,
we're mellowing and we're, we're just
00:26:41.537 --> 00:26:43.097
seeing things much more reasonably.
00:26:43.472 --> 00:26:44.012
Phil: Absolutely.
00:26:44.072 --> 00:26:44.492
Absolutely.
00:26:44.492 --> 00:26:46.772
I haven't had a fight about framework
interoperability in a long time.
00:26:47.322 --> 00:26:48.162
Well, fantastic.
00:26:48.222 --> 00:26:50.902
Let's, let's call that where
can people find more of you?
00:26:50.902 --> 00:26:53.122
You are, you're all over the
internet doing all sorts of things.
00:26:53.122 --> 00:26:54.202
What, what what are you up to?
00:26:54.817 --> 00:26:58.957
Joel Clermont: Yeah, my, my main hub of
activity now is mastering laravel.io.
00:26:59.017 --> 00:27:02.062
You know, on there we have
a podcast for Laravel and PP
00:27:02.067 --> 00:27:03.657
devs, the, the mailing list,
00:27:03.987 --> 00:27:06.597
some books and courses if you
wanna, like, keep me fed, like,
00:27:06.597 --> 00:27:07.887
you know, all, all that good stuff.
00:27:07.887 --> 00:27:10.017
But that's, that's really the
central point for all of it.
00:27:10.467 --> 00:27:10.977
Phil: Nice.
00:27:11.157 --> 00:27:15.097
I will have to I need to get on
that newsletter because I am using
00:27:15.097 --> 00:27:19.297
Laravel more and more and they've
gone, they've gone on like a rampage
00:27:19.297 --> 00:27:22.687
of major versions and I'm like, I, I
remember thinking four and five are
00:27:22.687 --> 00:27:24.607
quite nice and now version eleven's out.
00:27:24.607 --> 00:27:25.957
I'm like, I don't know what's happening.
00:27:25.957 --> 00:27:26.317
Brilliant.
00:27:26.692 --> 00:27:28.132
Joel Clermont: Yeah, it
does tend to move quickly.
00:27:28.530 --> 00:27:28.950
Phil: Cool.
00:27:29.100 --> 00:27:31.830
Alright, well thank you very much and
yeah, pleasure having you on the show.
00:27:31.985 --> 00:27:32.255
Joel Clermont: Yep.
00:27:32.255 --> 00:27:33.035
Talk to you later.
NOTE
This file was generated by Descript
00:00:01.320 --> 00:00:04.470
Phil: Hello everyone, and welcome
to another episode of APIs.
00:00:04.470 --> 00:00:08.580
You won't hate the podcast, it's
the audio version Instead of blog
00:00:08.580 --> 00:00:11.340
posts, we're here talking about APIs.
00:00:11.400 --> 00:00:15.210
And today I've got Joel Claremont
with me, who is well known around
00:00:15.210 --> 00:00:19.390
the Laravel PHP community but
might be new to some of you folks.
00:00:19.390 --> 00:00:20.800
So Joel, Hello.
00:00:21.190 --> 00:00:21.940
what's going on?
00:00:23.035 --> 00:00:23.695
Joel Clermont: Not too much.
00:00:23.695 --> 00:00:26.030
Yeah, I've listened to some
of your episodes here and I'm
00:00:26.030 --> 00:00:28.730
like, I am definitely not in
the API dev tooling space.
00:00:28.730 --> 00:00:30.050
That is not my specialty.
00:00:30.480 --> 00:00:34.440
, I'm coming at this more as the,
the, in the trenches practitioner
00:00:34.440 --> 00:00:38.880
building, shipping, supporting
APIs and not, not like the higher
00:00:38.880 --> 00:00:40.770
level tooling person that's
00:00:40.770 --> 00:00:42.210
building things for other people to
00:00:42.450 --> 00:00:43.590
Phil: Well that's, that's fine.
00:00:43.590 --> 00:00:49.530
So we're not, we, we have, because I
have been working in the kind of open API
00:00:49.530 --> 00:00:53.010
dev tooling space, a lot of the content
ends up being quite specific to that.
00:00:53.160 --> 00:00:54.780
And that's not really what this
00:00:54.780 --> 00:00:55.860
podcast is meant to be like.
00:00:55.860 --> 00:00:57.000
If you cast your
00:00:57.000 --> 00:01:00.870
mind back to way back when of
the origins of this, of APOs, you
00:01:00.870 --> 00:01:04.270
weren't hate as a an anything before
it was a community in a podcast.
00:01:04.510 --> 00:01:05.440
I was writing that book.
00:01:05.795 --> 00:01:09.525
Build APIs you won't hate, which was
pretty much how to make rest Dish APIs
00:01:09.620 --> 00:01:11.655
in Laravel and all of it was Laravel.
00:01:11.685 --> 00:01:11.835
So
00:01:11.835 --> 00:01:15.075
it's lovely to be chatting to Laravel
people and I still build APIs in
00:01:15.075 --> 00:01:19.215
Laravel and I think it's important
that we don't, like, I don't want to
00:01:19.215 --> 00:01:23.805
kind of separate out that there's the,
the API community and then like all of
00:01:23.865 --> 00:01:27.285
the, the programmers who are actually
building APIs in various frameworks.
00:01:27.285 --> 00:01:29.115
They're all, it's all overlap overlapping
00:01:29.115 --> 00:01:29.655
circles.
00:01:29.955 --> 00:01:31.385
And, whenever I'm talking to people
00:01:31.415 --> 00:01:31.955
about like.
00:01:32.355 --> 00:01:35.625
One of the main things in, in API derail,
I always try and explain to folks is that
00:01:35.625 --> 00:01:40.575
like if you go to API conferences and
you only ever talk about APIs and you
00:01:40.575 --> 00:01:45.285
sell your products to other people who
care about APIs, it's a very small world.
00:01:45.285 --> 00:01:50.365
But if you go to Laravel, PHB meetups and
and things like that, then there's actual
00:01:50.365 --> 00:01:53.335
people who might end up using your stuff
who have never heard about any of the
00:01:53.335 --> 00:01:56.305
wonderful, lofty things you've been
talking about and really should have.
00:01:56.545 --> 00:01:59.135
So that's kind of why I'm talking
to you today of, yeah, you're
00:01:59.135 --> 00:02:04.635
posting about like how, how you
like to make API specs with Laravel
00:02:04.665 --> 00:02:08.615
or how you don't, so you wrote an
article called I have It right here.
00:02:08.795 --> 00:02:12.275
Why I Don't Like Generating API Specs,
which is written nail on the head.
00:02:12.525 --> 00:02:14.685
do you wanna tell me a
little bit more about this?
00:02:14.685 --> 00:02:17.985
And you said there's a series of
blog posts and like what led to this?
00:02:17.985 --> 00:02:18.465
Tell me more.
00:02:18.740 --> 00:02:22.730
Joel Clermont: Yeah, it, it actually
started like, I think the, so, so, first
00:02:22.730 --> 00:02:26.720
of all, for a little context, I, I have
a site called mastering laravel.io and
00:02:27.050 --> 00:02:30.860
I publish, for some reason, I committed
to a daily newsletter Monday through
00:02:30.860 --> 00:02:33.110
Friday, and I, I cross post to the site.
00:02:33.110 --> 00:02:36.980
But so any, any random thought that
pops into my head, I'm like, oh,
00:02:36.980 --> 00:02:38.090
that could make an email, right?
00:02:38.090 --> 00:02:39.440
So I'll, I'll, I'll write it down.
00:02:40.010 --> 00:02:46.610
And I was working on a project recently
building an API for a Laravel company.
00:02:46.880 --> 00:02:51.100
And we were writing the spec and,
and the client, like they, they're
00:02:51.100 --> 00:02:53.950
an existing product and they're
like, we've never written a spec.
00:02:53.950 --> 00:02:55.510
Like we only have an internal team.
00:02:55.510 --> 00:02:55.570
I.
00:02:56.125 --> 00:02:58.765
And so that kind of started
the discussion, which is
00:02:58.765 --> 00:03:00.745
like, I think it's useful.
00:03:00.865 --> 00:03:05.425
In fact, I know it's useful to have
a spec even if you don't have a giant
00:03:05.425 --> 00:03:08.695
team, even if you don't have like a
separate frontend and backend team.
00:03:08.695 --> 00:03:12.655
I think like even if it's a full
stack small team or a single dev,
00:03:12.860 --> 00:03:14.545
it, it is nice to have a spec.
00:03:14.575 --> 00:03:15.955
It, it sort of keeps you honest.
00:03:15.955 --> 00:03:20.020
And so that, that was the, the start
of the whole discussion in, in the
00:03:20.020 --> 00:03:23.020
newsletter, but then it ultimately led
to, okay, hopefully I've convinced you.
00:03:23.545 --> 00:03:24.895
Now how do I get started?
00:03:24.925 --> 00:03:30.055
And where most developers like to go
is, well, let's use code to do it right?
00:03:30.055 --> 00:03:31.015
Like, that's what we do.
00:03:31.315 --> 00:03:35.235
And I personally have never had
success with that approach outside
00:03:35.265 --> 00:03:39.345
of like demos and a proof of
concept or maybe like breaking
00:03:39.345 --> 00:03:41.175
ground on something to get started.
00:03:41.625 --> 00:03:43.335
But the code first approach.
00:03:44.100 --> 00:03:45.570
Has been problematic for me.
00:03:45.570 --> 00:03:48.090
And so that, that was, that was where
my experience was coming from and I
00:03:48.090 --> 00:03:52.320
was trying to share that, like, it's
not that complicated to like just write
00:03:52.500 --> 00:03:55.350
the file yourself and, and I think
there's actually some benefits to it.
00:03:56.370 --> 00:03:59.340
Phil: I mean, so many developers are
running about, like, everyone has
00:03:59.340 --> 00:04:02.430
to learn Kubernetes and everyone has
to learn these 25 different things.
00:04:02.640 --> 00:04:03.240
Comically.
00:04:03.240 --> 00:04:05.910
Most of those do end up
being slightly overloaded.
00:04:05.940 --> 00:04:07.150
yaml DSLs.
00:04:07.310 --> 00:04:11.340
But the idea of learning this
one other yaml DSL is completely
00:04:11.340 --> 00:04:12.960
unacceptable to anyone
and we'll never do it.
00:04:13.060 --> 00:04:14.280
And, That's pretty funny.
00:04:14.580 --> 00:04:16.890
So just in case, there are
people who haven't heard me
00:04:16.890 --> 00:04:18.600
banging on about open API in the past.
00:04:18.840 --> 00:04:22.890
Joel says spec, he means API
specification, which is one other
00:04:23.010 --> 00:04:27.420
term for like API description
or API design document.
00:04:27.420 --> 00:04:30.490
There's a million different names of
this stuff, but yeah, basically it's
00:04:30.490 --> 00:04:30.730
like.
00:04:30.960 --> 00:04:34.770
I'm gonna, I'm gonna describe the
endpoints and properties and parameters
00:04:34.770 --> 00:04:39.930
and request bodies and all the bits
of the, the interface of the API with
00:04:39.930 --> 00:04:41.910
some sort of machine language, which.
00:04:43.450 --> 00:04:45.040
tools can use generally for docs.
00:04:45.430 --> 00:04:47.620
Pretty handy for mocks
and loads of other stuff.
00:04:47.770 --> 00:04:51.140
And I've built a spectral API scanner.
00:04:51.210 --> 00:04:54.000
So literally you put your open
API in and it goes, oh, that's
00:04:54.000 --> 00:04:54.990
gonna get you hacked buddy.
00:04:54.990 --> 00:04:55.620
Watch out for that.
00:04:55.650 --> 00:04:58.980
There's a million things you can do with,
with an API spec when you've got it.
00:04:59.460 --> 00:05:02.850
But yeah, when, when
left are the developers.
00:05:03.810 --> 00:05:05.130
I'm picking up on what
you said a minute ago.
00:05:05.130 --> 00:05:07.720
Like the, if you leave it to the
developers they're just gonna
00:05:07.720 --> 00:05:08.620
write a whole bunch of code.
00:05:08.740 --> 00:05:11.260
And if you, if they ask you, if
you ask them for documentation,
00:05:11.260 --> 00:05:14.270
they'll go and write down like 10
lines somewhere and it'll be bad.
00:05:14.510 --> 00:05:16.820
So at some point over the last I.
00:05:17.140 --> 00:05:18.470
I don't know, eight five.
00:05:18.650 --> 00:05:21.830
Over the last five years specifically,
I feel like open API has picked
00:05:21.830 --> 00:05:23.510
up in popularity massively.
00:05:23.600 --> 00:05:26.330
And that's partly 'cause people like
me bang on about it all the time.
00:05:26.330 --> 00:05:29.390
But it's bloody useful for
everyone to know what's going on.
00:05:29.690 --> 00:05:33.320
And you've got that machine learnable
format, so you, and, and you've got this,
00:05:33.680 --> 00:05:37.130
this spec where you can generate some
docs and you can use it for contract
00:05:37.130 --> 00:05:40.250
testing in a million things to, and
that helps keep those docs up to date.
00:05:40.970 --> 00:05:42.800
But some folks don't like
00:05:42.800 --> 00:05:43.370
to write.
00:05:43.440 --> 00:05:45.690
That YAML out by hand.
00:05:45.720 --> 00:05:46.740
'cause that is pretty boring.
00:05:47.310 --> 00:05:48.420
There's a bunch of other ways of doing it.
00:05:48.420 --> 00:05:51.930
There was gooeys and things, but people
don't like to write that by hand and
00:05:51.930 --> 00:05:56.190
instead they try a bunch of creative
ways to avoid having to write that.
00:05:56.520 --> 00:05:57.210
You were talking about in
00:05:57.210 --> 00:05:59.730
Laravel, there's a few kind
of Laravel specific tools.
00:05:59.730 --> 00:06:01.920
How, how do, how do
people do it in Laravel?
00:06:01.920 --> 00:06:05.130
How do they get, how do they get
their code spitting out open API
00:06:05.130 --> 00:06:05.970
so they don't have to write it.
00:06:09.195 --> 00:06:12.405
Joel Clermont: Yeah, it's what you might
expect if, if, even if you're not in
00:06:12.405 --> 00:06:16.515
Laravel, you know, where, where there's
some, some element of static analysis
00:06:16.725 --> 00:06:20.775
and then that can be enhanced with
some sort of annotations or like inline
00:06:20.775 --> 00:06:26.805
documentation to, to enhance it further
or to specify like examples of things.
00:06:27.070 --> 00:06:27.290
Phil: Mm.
00:06:28.275 --> 00:06:30.705
Joel Clermont: and I probably
should say like I've.
00:06:31.890 --> 00:06:33.240
At least not super recently.
00:06:33.240 --> 00:06:37.260
I've never actually tried to use
one of those packages in earnest.
00:06:37.260 --> 00:06:40.710
Like, I will try, somebody
will recommend one, and I'll be
00:06:40.710 --> 00:06:41.760
like, oh, I'll give it a shot.
00:06:41.820 --> 00:06:43.260
And I usually get a couple days into it.
00:06:43.260 --> 00:06:47.470
I'm like no, this is, it is just, it
ends up, you're just conforming to a
00:06:47.470 --> 00:06:52.540
different layer of abstraction in the
sa in the same sort of specification.
00:06:52.540 --> 00:06:55.180
And so, it's, it's
really a personal thing.
00:06:55.180 --> 00:06:58.180
Like I'm sure there are teams out there
that do this and it works great and
00:06:58.180 --> 00:07:02.830
I'm sure there are use cases where it,
it's beneficial, but I'm generally not
00:07:02.830 --> 00:07:05.560
working on massive, massive projects.
00:07:05.560 --> 00:07:11.250
You know, like, like maybe there's 50
to a hundred API endpoints and a lot of
00:07:11.250 --> 00:07:13.710
times there might not
even be a public consumer.
00:07:13.810 --> 00:07:14.320
Is it
00:07:15.580 --> 00:07:15.970
okay.
00:07:15.970 --> 00:07:16.990
I mean, it's not stripe.
00:07:17.395 --> 00:07:18.385
Phil: right now, but yeah.
00:07:18.775 --> 00:07:19.195
Fair enough.
00:07:20.050 --> 00:07:23.590
Joel Clermont: Okay, well I'm
counting like get versus post too,
00:07:23.680 --> 00:07:23.980
right?
00:07:23.980 --> 00:07:25.780
So, you know, in terms of
00:07:25.780 --> 00:07:29.080
resources it's probably a lower
number, but, but yeah, it's, it's
00:07:29.080 --> 00:07:34.510
not, I don't work on teams of like
50 developers and you know, that
00:07:34.540 --> 00:07:39.940
like, so there's probably some
efficiencies that become more.
00:07:40.599 --> 00:07:43.630
Important and beneficial where the
trade offs might skew the other
00:07:43.630 --> 00:07:46.030
direction toward code first tooling.
00:07:46.510 --> 00:07:48.340
IJI just am not there and
00:07:48.669 --> 00:07:51.039
I here, maybe this is a
question for you, Phil.
00:07:51.669 --> 00:07:54.999
Are there any tools that you've
seen that do spec generation,
00:07:54.999 --> 00:07:56.590
that actually leverage the spec?
00:07:56.590 --> 00:07:59.410
Like things like refs and, you
know, things like that Or is does
00:07:59.410 --> 00:08:03.580
it end up spitting out some really
flat, verbose document that no
00:08:03.580 --> 00:08:05.020
human would ever write in that way?
00:08:05.305 --> 00:08:06.265
Phil: Yeah, that's the problem.
00:08:06.265 --> 00:08:11.785
Most of those tools will just kind of
just vomit something upwards, which is not
00:08:11.844 --> 00:08:12.805
particularly.
00:08:13.614 --> 00:08:14.215
Helpful.
00:08:14.274 --> 00:08:17.575
I mean, it generally, it, that
sort of stuff doesn't really
00:08:17.575 --> 00:08:20.634
matter if you are just putting it
straight into a documentation tool.
00:08:20.664 --> 00:08:22.465
'cause the documentation
tools will flatten it.
00:08:22.984 --> 00:08:27.034
so yeah, the, the way, the
way that it seems to me is.
00:08:28.250 --> 00:08:33.650
Somebody has said, Hey, we've,
we've started using open API to
00:08:33.859 --> 00:08:37.520
have one kind of documentation
hub, a developer portal, whatever.
00:08:37.849 --> 00:08:41.659
We've got this, we've got this thing,
and we need all the teams to make open
00:08:41.659 --> 00:08:43.099
API and we don't care how you do it.
00:08:43.099 --> 00:08:43.729
I've been that guy.
00:08:43.729 --> 00:08:44.509
I've, I've done that.
00:08:44.679 --> 00:08:47.949
And I'm like, you know, some of them are
like, oh, we've got it all in Postman,
00:08:47.949 --> 00:08:49.714
so we'll convert it into open api.
00:08:49.719 --> 00:08:50.829
I, I'm like, sure, whatever.
00:08:51.099 --> 00:08:54.039
And some of them are like, oh, we've
got open API two or Raml or these
00:08:54.039 --> 00:08:55.689
different old kind of defunct formats.
00:08:55.689 --> 00:08:56.889
And I'm like, whatever, I can
00:08:56.889 --> 00:09:00.099
convert that for you and, and or, you
know, and then eventually you end up
00:09:00.099 --> 00:09:01.719
with open API and everyone's like, great.
00:09:01.719 --> 00:09:04.689
Some of it's weird and some of it's ugly
and some of it's not entirely right.
00:09:04.689 --> 00:09:08.469
But that's a step one is we now have one
documentation hub for the entire thing.
00:09:08.469 --> 00:09:08.859
Great.
00:09:09.229 --> 00:09:09.680
But then over
00:09:09.680 --> 00:09:12.409
time it's a case of like, well, how
do we get this to be more useful?
00:09:12.829 --> 00:09:13.279
And.
00:09:13.454 --> 00:09:15.434
And how do we use this for
more verticals as well?
00:09:15.434 --> 00:09:18.644
Like if you are just shoving it
into docs, then it kind of makes
00:09:18.644 --> 00:09:23.244
that nice stripe, like three coal
API stuff that everyone wants.
00:09:23.244 --> 00:09:23.484
But
00:09:23.784 --> 00:09:27.564
if you try and use it for, you know,
code generation and a bunch of other
00:09:27.564 --> 00:09:30.874
use cases, it, it kind of falls apart
and you can't it gets a bit hard
00:09:30.874 --> 00:09:32.674
to like add stuff to it as well.
00:09:32.674 --> 00:09:32.914
So.
00:09:33.464 --> 00:09:39.794
the one thing I've seen, which helps, if,
so, if you've got a API spec that's being
00:09:39.794 --> 00:09:45.494
kind of just a magic appeared out of your
API one thing, that can be pretty handy.
00:09:45.494 --> 00:09:46.874
Have you heard of open API Overlays?
00:09:48.774 --> 00:09:48.994
Joel Clermont: Mm.
00:09:49.349 --> 00:09:49.619
No.
00:09:50.069 --> 00:09:51.329
Phil: It's this like extension thing.
00:09:51.329 --> 00:09:56.329
So open APIs started doing like working
groups or special interest groups.
00:09:56.639 --> 00:09:58.919
And these special interest
groups create different things.
00:09:58.919 --> 00:10:02.429
So they're doing like workflows so you
can document entire kind of workflows
00:10:02.429 --> 00:10:04.469
of, of API calls and things like that.
00:10:04.769 --> 00:10:08.069
And one of them is overlays
where you can basically.
00:10:08.694 --> 00:10:09.984
It's kind of like a spectral rule set.
00:10:09.984 --> 00:10:12.624
If you're familiar, you kind of
have like a J path and you're like,
00:10:12.924 --> 00:10:17.184
go to this bit of the document and
then like add this or remove this.
00:10:17.574 --> 00:10:23.544
And so you can theoretically have some
horrendously vomited out, open API and
00:10:23.544 --> 00:10:26.094
then be like, and I'm gonna add some
descriptions in here, which are like
00:10:26.094 --> 00:10:29.484
10 paragraphs long and have a bunch of
markdown so you can have your technical
00:10:29.484 --> 00:10:31.704
writers kind of wedging that stuff in.
00:10:32.184 --> 00:10:32.964
And so.
00:10:34.469 --> 00:10:38.429
My, my initial like, no one should ever
do code first ever, because then you have
00:10:38.429 --> 00:10:44.309
this useless thing is, is somewhat kind of
abated a bit where it's like, okay, you,
00:10:44.339 --> 00:10:47.759
you've, you've given us this useless thing
and now some technical writers can jump
00:10:47.759 --> 00:10:52.519
through some quite horrendous hoops to
make it a bit less useless, but that still
00:10:52.519 --> 00:10:55.549
isn't like the most
shining endorsement for it.
00:10:57.034 --> 00:10:59.644
Joel Clermont: you know, like you
mentioned, if if, if the only people
00:10:59.644 --> 00:11:04.834
reading the spec are doing so via
like a generated HTML portal, then
00:11:04.834 --> 00:11:09.154
it, it doesn't probably matter
internally if it's using like refs for
00:11:09.154 --> 00:11:10.624
shared schemas and things like that.
00:11:10.654 --> 00:11:11.014
But
00:11:11.374 --> 00:11:15.124
I, you know, just like I'm thinking and
recommending you write it by hand at
00:11:15.124 --> 00:11:16.504
least once, at least know how to do it.
00:11:16.774 --> 00:11:17.344
I also.
00:11:17.419 --> 00:11:20.419
I think like, I like to look
at the spec by hand too.
00:11:20.419 --> 00:11:20.629
Like
00:11:20.629 --> 00:11:24.559
the, the tool, the tooling is great
to auto generate fancy, nice branded
00:11:24.559 --> 00:11:28.339
documentation, but I, I do find some
value looking at the spec directly and
00:11:28.339 --> 00:11:33.949
then especially seeing, oh, this, you
know, this specific type of request
00:11:33.949 --> 00:11:36.979
or this, you know, form payload is
00:11:36.979 --> 00:11:38.059
used more than one place.
00:11:38.059 --> 00:11:42.049
Like that tells me something about
the overall API design that you don't
00:11:42.049 --> 00:11:43.669
see if it's just all flattened out.
00:11:44.149 --> 00:11:44.569
Phil: Mm.
00:11:45.019 --> 00:11:46.189
Yeah, I mean, that's a useful thing.
00:11:46.189 --> 00:11:49.309
So kind of having intent.
00:11:49.774 --> 00:11:54.364
Written somewhere else outside of
the code, not only helps you spot
00:11:54.604 --> 00:11:58.174
obvious mistakes from a wider pool
of people that don't necessarily
00:11:58.174 --> 00:12:00.184
know how Laravel works but
00:12:00.729 --> 00:12:03.274
it, it just becomes a, it
becomes a lot more useful.
00:12:03.274 --> 00:12:05.194
Like you can have a bunch of
people doing design reviews that
00:12:05.194 --> 00:12:07.804
literally don't know Laravel and
don't know its random conventions.
00:12:07.804 --> 00:12:09.544
And, and it also means that if
00:12:09.544 --> 00:12:12.994
you accidentally have a slip of the
keyboard and, and change some code.
00:12:14.094 --> 00:12:18.024
You didn't necessarily change all of
the annotations that came with it then.
00:12:18.024 --> 00:12:21.609
I, the graphic I used on a blog post
talking about this was like a, a
00:12:21.609 --> 00:12:24.729
drinks cabinet with a labeled that as
milk and it's clearly orange juice.
00:12:24.939 --> 00:12:28.109
Like people kind of confuse
the like proximity with
00:12:28.109 --> 00:12:32.039
accuracy if like these annotations are
somewhat near the code I'm describing.
00:12:32.039 --> 00:12:35.009
So I'm sure someone will definitely
remember to update them both.
00:12:35.699 --> 00:12:36.329
And so.
00:12:36.674 --> 00:12:39.604
Kind of having it in that second
place means you can then kind of you,
00:12:39.604 --> 00:12:42.964
you have those extra checks where
you, you use that open API as an
00:12:42.964 --> 00:12:47.194
assertion in your contract test that
says, does my code match what I think
00:12:47.194 --> 00:12:50.644
it does and what the design review
team think it does, and what everyone
00:12:50.644 --> 00:12:52.174
involved so far has thought it would.
00:12:52.654 --> 00:12:56.184
And so that, that for me is kind of
why I'm a big fan of the approach.
00:12:57.764 --> 00:13:02.324
But it's, it's just really hard to get
a PA developers to do another thing.
00:13:02.904 --> 00:13:04.014
They're like, I'm a coder.
00:13:04.044 --> 00:13:04.464
I write
00:13:04.464 --> 00:13:04.854
code.
00:13:05.224 --> 00:13:06.635
I would like to write some code for
00:13:06.635 --> 00:13:07.025
this.
00:13:07.115 --> 00:13:09.772
And yeah, it's, it's a weird one.
00:13:09.772 --> 00:13:14.172
Joel Clermont: One of the benefits
I think there is in writing the
00:13:14.172 --> 00:13:16.962
spec separate from the code is like.
00:13:17.907 --> 00:13:21.357
Especially if you start with the
spec is it forces you to think
00:13:21.357 --> 00:13:25.587
through the requirements in a level
of detail that you don't often do.
00:13:25.677 --> 00:13:28.437
You know, if you're getting a
requirement from some stakeholder
00:13:28.497 --> 00:13:31.437
and they're like, Hey, I want an
endpoint to do this, this, and that.
00:13:31.977 --> 00:13:33.627
Okay, well, like who can do that?
00:13:33.687 --> 00:13:34.077
You know?
00:13:34.227 --> 00:13:35.517
How long can that field be?
00:13:35.517 --> 00:13:37.407
Like there's all these constraints that.
00:13:37.962 --> 00:13:41.652
Somebody has to make a decision
on, and like that spec becomes the
00:13:41.652 --> 00:13:44.592
forcing function to decide like,
well, what is the maximum length?
00:13:44.592 --> 00:13:46.932
What, what is the format
on this date time?
00:13:46.932 --> 00:13:47.292
Or, you know,
00:13:47.472 --> 00:13:51.072
just things like that that
otherwise you might get to later
00:13:51.072 --> 00:13:52.542
in the middle of implementation.
00:13:52.572 --> 00:13:54.672
And a dev just like, well, I
guess we'll just do it this way.
00:13:54.672 --> 00:13:56.682
And it wasn't actually
discussed or decided on.
00:13:57.762 --> 00:13:59.082
Phil: That's a really good point.
00:13:59.232 --> 00:14:05.142
That's I think where I was heading was
that like the API spec being thought of as
00:14:05.772 --> 00:14:11.688
a documentation mechanism is kind of the
problem here because it's it's basically.
00:14:12.048 --> 00:14:12.768
It's not always a problem.
00:14:12.768 --> 00:14:17.428
There are, there are use cases
where you have an API and you
00:14:17.428 --> 00:14:18.988
need to like play catch up, right?
00:14:18.988 --> 00:14:21.018
There's the there's,
there's API design first.
00:14:21.018 --> 00:14:23.928
There's API code first, and the,
and I've done polls where it's
00:14:23.928 --> 00:14:25.998
like, are using API code first.
00:14:25.998 --> 00:14:26.898
API design first.
00:14:27.313 --> 00:14:29.773
Switching from one to the other
or some awkward combination.
00:14:29.773 --> 00:14:32.323
And every time I do this, every
couple of years, the answer's
00:14:32.323 --> 00:14:33.883
always like 25% of each.
00:14:35.053 --> 00:14:37.273
So people, there are some
teams who are doing code
00:14:37.273 --> 00:14:40.033
first, some are doing design first,
and, and it's just all over the place.
00:14:40.423 --> 00:14:46.633
But yes, like those, those tools that
can help you kind of grab a whole
00:14:46.633 --> 00:14:50.473
bunch of metadata out of your code
through static analysis and maybe
00:14:50.473 --> 00:14:51.793
you add a few other things in there.
00:14:52.618 --> 00:14:54.718
Can really help you get a head start.
00:14:54.748 --> 00:14:55.708
And then you have the open
00:14:55.708 --> 00:14:59.368
API that you can go back and put
assertions into your code base
00:14:59.368 --> 00:15:00.328
to make sure that it's correct.
00:15:00.328 --> 00:15:01.588
And then you can expand that.
00:15:01.888 --> 00:15:04.468
And if you want to add a new
endpoint, then you can design first
00:15:04.468 --> 00:15:06.808
on that, on that open API file.
00:15:06.808 --> 00:15:10.228
You can add a new endpoint that's
completely imaginary, start working on it.
00:15:10.438 --> 00:15:12.418
Have everyone agree whether
that's a good idea or not.
00:15:12.418 --> 00:15:14.248
Whether it solves,
solves the needs or not.
00:15:14.548 --> 00:15:17.698
Run it through a mock generator,
a mock server so that people can
00:15:17.698 --> 00:15:19.498
interact with it before it even exists.
00:15:19.818 --> 00:15:20.748
And then later on.
00:15:21.513 --> 00:15:25.323
Code it and make sure that it
matches the contract test for that.
00:15:25.843 --> 00:15:29.083
But do you think, do you think
that's how everyone should work?
00:15:29.233 --> 00:15:32.918
Joel Clermont: I like your use
case because I, I do join a lot
00:15:32.918 --> 00:15:37.058
of, I'll call 'em legacy projects
where you don't have documentation.
00:15:37.058 --> 00:15:37.508
In fact,
00:15:37.568 --> 00:15:39.698
I hate to say this, sometimes
you don't have tests, right?
00:15:39.698 --> 00:15:39.968
Like,
00:15:40.328 --> 00:15:45.788
and so that I could see as a useful
time to generate something just,
00:15:45.788 --> 00:15:47.018
just to get a starting point.
00:15:47.648 --> 00:15:50.828
And then edit it from there, and then
like, you know, write contract tests
00:15:50.828 --> 00:15:52.838
around the little bits as you go.
00:15:53.168 --> 00:15:57.218
And, and so I, I gotta remember
that because a lot of times when
00:15:57.218 --> 00:16:00.308
I join a project, like decisions
have already been made and now
00:16:00.308 --> 00:16:01.418
you're just trying to catch up.
00:16:01.478 --> 00:16:04.478
And I, I think code generation could
be an excellent use case for that.
00:16:04.478 --> 00:16:07.148
Just to, to get you to
where you wanna go faster.
00:16:07.773 --> 00:16:11.103
And to not have to write all of that
by hand and, and reverse engineer it.
00:16:11.133 --> 00:16:11.763
You know, like try to
00:16:11.763 --> 00:16:15.363
figure out, well what are all
the overlapping validation rules
00:16:15.363 --> 00:16:18.483
or schema constraints in the
database layer or things like that.
00:16:18.603 --> 00:16:20.703
A static analysis can get you 80% there.
00:16:21.413 --> 00:16:21.833
Phil: for sure.
00:16:22.273 --> 00:16:22.778
I think.
00:16:23.198 --> 00:16:26.239
An interesting third way I've come
across, and we've written about
00:16:26.239 --> 00:16:30.469
it a bit on the blog, is kind of
using HTP traffic inspection, right?
00:16:30.779 --> 00:16:34.319
So I've, I've definitely
inherited APIs where no one
00:16:34.319 --> 00:16:35.699
knows how the heck this works.
00:16:35.699 --> 00:16:38.069
You've gotta like decompile the iPhone app
00:16:38.069 --> 00:16:40.409
and there's some third party client
that you can't even look at the
00:16:40.409 --> 00:16:44.399
code of and, and like no one can
get into the compiled Java app on
00:16:44.399 --> 00:16:47.369
some bloody API that people haven't
got the password for anymore.
00:16:47.369 --> 00:16:50.579
It sounds silly, but I've been in these
silly situations that help out a lot of
00:16:50.579 --> 00:16:50.909
struggling
00:16:51.029 --> 00:16:51.269
Joel Clermont: boy.
00:16:51.869 --> 00:16:54.299
Phil: And everyone's like, right,
we've gotta rebuild this API.
00:16:54.299 --> 00:16:57.119
And you're like, what API if I can't
find any of the endpoints, like,
00:16:57.119 --> 00:16:58.469
everyone, check your browser history.
00:16:58.469 --> 00:16:59.129
What are we doing here?
00:16:59.499 --> 00:17:00.669
And so being able to
00:17:00.669 --> 00:17:03.569
kind of wrap it in a, in a
traffic proxy that essentially
00:17:03.569 --> 00:17:04.589
says like all the requests.
00:17:05.034 --> 00:17:07.994
Going in, or you can literally, you
can wedge them into the browser.
00:17:08.244 --> 00:17:10.009
And, and then kind of run
around clicking things.
00:17:10.009 --> 00:17:12.709
There's, there's a bunch of these
different tools for sniffing actual
00:17:12.949 --> 00:17:14.589
traffic going through the system.
00:17:15.069 --> 00:17:15.729
And then
00:17:15.729 --> 00:17:19.739
you can kind of take all of
that and output an open API
00:17:19.829 --> 00:17:21.224
file and say, there you go.
00:17:21.404 --> 00:17:25.147
And I feel like if we're, if we're
talking kind of the catching up
00:17:25.147 --> 00:17:28.597
with design first, then I'm almost,
I'm mu I'm, I generally feel more
00:17:28.597 --> 00:17:33.397
interested in going with the traffic
sniffing approach because it's real.
00:17:33.397 --> 00:17:33.457
I.
00:17:34.007 --> 00:17:36.917
Like you can still look at some, look
at some stuff and, and get it wrong.
00:17:36.917 --> 00:17:39.607
Like if, if when you've got these
complicated dynamic payloads where
00:17:39.607 --> 00:17:42.037
there's this or this or this, that
could come through and you're like,
00:17:42.037 --> 00:17:44.737
it's definitely only this 'cause you've
only seen it come, you know, you haven't
00:17:44.737 --> 00:17:46.207
noticed any null values in there.
00:17:46.207 --> 00:17:48.007
So you said it, it is a required property.
00:17:48.007 --> 00:17:50.407
Mistakes like that can be
made depending on how much
00:17:50.707 --> 00:17:51.997
the sample size goes through.
00:17:52.507 --> 00:17:58.627
But I, I feel like the promise
of having these kind of framework
00:17:58.627 --> 00:18:00.517
integrated static analysis.
00:18:01.012 --> 00:18:06.532
Tools is potentially misleading
unless they can hook into enough
00:18:06.832 --> 00:18:10.612
where you literally don't need
to add other stuff yourself.
00:18:10.612 --> 00:18:14.092
'cause as soon as you ask the humans
to get involved, that's when they're
00:18:14.092 --> 00:18:15.502
just introducing human error.
00:18:16.042 --> 00:18:17.632
Have you come across anything like that?
00:18:17.835 --> 00:18:18.125
Joel Clermont: Yeah.
00:18:18.130 --> 00:18:19.180
Um, Not directly.
00:18:19.210 --> 00:18:20.920
'cause again, I've not worked on a project
00:18:21.250 --> 00:18:23.950
recently that has done the
automated tooling, but, but I've,
00:18:24.490 --> 00:18:26.470
I've experienced drift for sure.
00:18:26.680 --> 00:18:30.280
And, and honestly that's one of my fears
with Code Generation, I, you alluded
00:18:30.280 --> 00:18:33.820
to it earlier, is like if you make
an unintentional change, well, and it
00:18:33.820 --> 00:18:35.710
just regenerates the spec to match it.
00:18:35.740 --> 00:18:38.295
Now your tests are still passing, but I.
00:18:38.770 --> 00:18:42.430
Unless a human catches that in code
review or design review of some sort,
00:18:42.430 --> 00:18:45.940
like you could unintentionally change
your API even in a breaking way,
00:18:45.940 --> 00:18:51.000
which to me is like the worst possible
outcome of of, of, of an API change.
00:18:51.000 --> 00:18:54.120
So I don't know if there's solutions
to that, but yeah, the, either
00:18:54.120 --> 00:18:58.257
the intentional or unintentional
drift is just, just an ongoing
00:18:58.257 --> 00:18:59.547
problem I have experienced,
00:18:59.947 --> 00:19:03.487
With that traffic inspection like
that's super useful for like sort of
00:19:03.487 --> 00:19:04.957
those black box scenarios you were
00:19:04.957 --> 00:19:05.527
describing.
00:19:05.527 --> 00:19:07.447
Like, I'm gonna have
nightmares about that.
00:19:07.447 --> 00:19:12.607
But I, I'm almost wondering too if
like that in conjunction, like when
00:19:12.607 --> 00:19:14.857
you're, when you're, when I'm joining
a project, like I'm coming into some
00:19:14.857 --> 00:19:20.077
project, if I, if I just use static
analysis, that doesn't tell me.
00:19:20.602 --> 00:19:22.072
How much dead code is in there,
00:19:22.222 --> 00:19:22.462
right?
00:19:22.462 --> 00:19:26.332
And like now, maybe I'm wasting a week of
work trying to document and test something
00:19:26.332 --> 00:19:27.672
and then I, ship it to the client.
00:19:27.672 --> 00:19:29.292
They're like, oh, we haven't
used that in five years.
00:19:29.322 --> 00:19:29.712
Like that.
00:19:29.712 --> 00:19:31.392
Well, that was just a
wasted week of effort.
00:19:31.872 --> 00:19:36.582
So I could see pairing the static
analysis with the traffic analysis
00:19:36.612 --> 00:19:38.592
just to like, even to prioritize.
00:19:39.087 --> 00:19:40.827
These are the paths that
get the most traffic.
00:19:40.857 --> 00:19:41.067
Like
00:19:41.067 --> 00:19:42.147
let's focus on those.
00:19:42.507 --> 00:19:44.427
These endpoints, they never got traffic.
00:19:44.667 --> 00:19:47.277
Oh, I'll ask the client even
before I start working on it.
00:19:47.307 --> 00:19:47.757
Oh yeah.
00:19:47.817 --> 00:19:48.777
We can just delete that.
00:19:48.807 --> 00:19:49.047
Right?
00:19:49.047 --> 00:19:53.307
Like, so I could see a hybrid
approach there being useful too.
00:19:53.907 --> 00:19:54.357
Phil: Yeah.
00:19:54.567 --> 00:19:55.107
Interesting.
00:19:55.917 --> 00:19:58.107
The I've seen a few frameworks that are.
00:20:00.162 --> 00:20:03.822
me love the idea of code
first a little bit more.
00:20:04.282 --> 00:20:04.552
I wrote
00:20:04.852 --> 00:20:07.132
an article recently and I can't remember
the names of any of these things.
00:20:07.212 --> 00:20:12.682
I think it's like Hu Hugo Oh,
Hummer in, in Node and Fast.
00:20:12.682 --> 00:20:13.177
API I.
00:20:13.177 --> 00:20:15.172
I'll get some problem links in
the show notes when I remember.
00:20:15.172 --> 00:20:18.162
But there, there are, there's
this kind of new idea of like
00:20:18.192 --> 00:20:20.712
open API Aware frameworks, right?
00:20:20.712 --> 00:20:21.282
Like built.
00:20:21.627 --> 00:20:26.097
Into the core of the framework is
in the past, in the past you've got
00:20:26.097 --> 00:20:27.477
like swagger, PHP, which I hated.
00:20:27.477 --> 00:20:31.137
Like I, I, when I, when I first got
involved with swagger, when I first
00:20:31.137 --> 00:20:33.777
tried to start trying to figure out
how to document an API, I looked
00:20:33.777 --> 00:20:37.257
at swagger, PHP, and went, ah, for
all the reasons we've discussed is
00:20:37.257 --> 00:20:39.057
literally you put a bunch of doc block
00:20:39.057 --> 00:20:41.007
annotations in your code
and hope that it's correct.
00:20:41.427 --> 00:20:43.857
And, and I ran away and then
I ended up doing other things.
00:20:43.857 --> 00:20:46.467
But that's still like the main premise.
00:20:46.737 --> 00:20:50.277
But with modern tools, like like Scribe
is a really cool tool and like props
00:20:50.277 --> 00:20:51.477
to the people that have made this.
00:20:51.777 --> 00:20:53.457
But they, I.
00:20:53.457 --> 00:20:57.567
They've essentially got rid of quite a few
of the annotations because the framework
00:20:57.567 --> 00:21:01.587
is kind of saying that this is a poster
or, or a get, and like they've, they know
00:21:01.587 --> 00:21:02.967
what the URL is from looking at the code.
00:21:02.967 --> 00:21:05.127
They're doing a lot of that
static, static analysis,
00:21:05.427 --> 00:21:08.277
but it's still kind of hacked
into the framework a bit.
00:21:08.817 --> 00:21:11.517
And there's still a certain
amount of duplication.
00:21:11.727 --> 00:21:14.577
And so what I like about
the frameworks that are.
00:21:15.282 --> 00:21:18.972
Coming at this from like the
framework itself will tell you what
00:21:18.972 --> 00:21:23.772
your open API is, because just by
using the framework, we are building
00:21:23.802 --> 00:21:25.152
up all of the bits that you need.
00:21:25.452 --> 00:21:26.442
That seems really cool.
00:21:26.442 --> 00:21:28.872
Like when, when you write
the validation rules for your
00:21:28.872 --> 00:21:33.492
models, they all line up with an
appropriate validation in open API.
00:21:33.762 --> 00:21:39.132
So when you're doing that, it sounds
that that, that to me seems like it
00:21:39.132 --> 00:21:41.262
would be pretty much just fine because.
00:21:42.522 --> 00:21:47.082
The, the main, the main thing of like a PA
design first is it's more about planning.
00:21:47.322 --> 00:21:50.962
You should like plan this thing and
spend a lot more time in the planning
00:21:50.962 --> 00:21:55.012
stage past the whiteboard, but before
you start writing loads of code.
00:21:55.482 --> 00:21:56.832
But if the framework can
00:21:56.832 --> 00:22:00.312
make itself simple enough
that it, the framework is, is.
00:22:00.312 --> 00:22:05.212
Just like a config DSL where you are,
instead of writing open API in yaml,
00:22:05.212 --> 00:22:09.532
you're writing open API in this kind of
a bit of PHB code and it's easy enough to
00:22:09.532 --> 00:22:12.922
read and it makes sense, and then you just
shove a bit of business logic in there
00:22:12.922 --> 00:22:15.622
later that, that to me would be fine.
00:22:15.622 --> 00:22:20.332
That kind of absolves the differences,
removes the differences between open API.
00:22:21.112 --> 00:22:22.912
Well between design first and code first.
00:22:23.342 --> 00:22:25.172
It kind of makes them
become the same thing.
00:22:25.662 --> 00:22:27.972
You just kind of like add your
business logic some other time.
00:22:27.972 --> 00:22:33.342
But none of the tools in Laravel
that I've seen are that, and it's
00:22:33.342 --> 00:22:34.992
quite rare to actually find them.
00:22:35.472 --> 00:22:39.792
And at this point I worry that those
projects are kind of just like hobby
00:22:39.792 --> 00:22:41.802
projects and not a whole thing.
00:22:42.162 --> 00:22:42.642
So
00:22:43.002 --> 00:22:45.762
there's a bit of hope in there, but
I don't think anyone's taken the
00:22:45.762 --> 00:22:47.562
idea too seriously at this point.
00:22:47.562 --> 00:22:47.832
Joel Clermont: Yeah.
00:22:47.917 --> 00:22:51.762
The, the reason this, this came
on my radar recently is there is a
00:22:51.762 --> 00:22:55.542
newer package, like it's not even
at 1.0 in Laravel called Scramble.
00:22:55.632 --> 00:22:55.692
I
00:22:55.692 --> 00:22:57.012
don't, I don't know if
you've seen this one.
00:22:57.062 --> 00:23:00.932
It will look at, like in, in LAR you have
a form request with validation rules.
00:23:00.932 --> 00:23:03.902
It will statically
analyze those rules and.
00:23:04.502 --> 00:23:07.592
Set like max links or field
types or things like that,
00:23:07.802 --> 00:23:10.532
purely based on that with like
zero annotation, which is, I,
00:23:11.342 --> 00:23:13.022
I do like the promise of it.
00:23:13.022 --> 00:23:13.562
I really do.
00:23:13.562 --> 00:23:15.092
Like I, I get the appeal.
00:23:15.722 --> 00:23:20.072
Um, one, one other thing too
I was thinking about is I.
00:23:21.137 --> 00:23:24.377
You know, when you mention whiteboards
and upfront design, like I cringed a
00:23:24.377 --> 00:23:28.367
little bit because like I, I've come
over the years to recognize like you
00:23:28.367 --> 00:23:30.407
never can plan super far in advance.
00:23:30.947 --> 00:23:33.467
And, But I, you know, so one thing
I wanted to clarify is like, even
00:23:33.467 --> 00:23:37.487
with the design first approach,
I generally do it like literally
00:23:37.487 --> 00:23:38.807
end point by end point, right?
00:23:38.807 --> 00:23:42.617
So I, I design it, I write the spec,
we agree on it, I implement it.
00:23:42.997 --> 00:23:45.667
Then we repeat for the next one,
not like, well, let's design the
00:23:45.667 --> 00:23:47.857
entire API and, and see what happens,
00:23:47.857 --> 00:23:50.587
because that, that just
never materializes correctly.
00:23:51.017 --> 00:23:51.317
Phil: man.
00:23:51.317 --> 00:23:54.527
Yeah, it's, it's something that I really,
I need to do a whole episode on this,
00:23:54.527 --> 00:23:58.337
on like, how do you actually plan an
API, because the stuff I said in my book
00:23:58.337 --> 00:23:59.747
was, was pretty immature at the time.
00:23:59.747 --> 00:24:02.147
I think I was like, just think
of all the endpoints you need and
00:24:02.147 --> 00:24:05.147
then like post and get next to
'em or whatever is, is a bit dumb.
00:24:05.677 --> 00:24:09.237
But, but like the phases, the phases,
of of planning and that's like
00:24:09.537 --> 00:24:13.767
literally stakeholder interviews,
which is like a, a, a concept from
00:24:13.767 --> 00:24:15.957
user research and, and, and ux.
00:24:16.337 --> 00:24:21.437
and then kind of taking everyone's
needs and requirements, and not
00:24:21.437 --> 00:24:25.127
necessarily too literally, but
distilling down the essence of what.
00:24:25.287 --> 00:24:29.547
They want and what they need and, and
how multiple different stakeholders
00:24:29.547 --> 00:24:31.107
can ask for different things.
00:24:31.107 --> 00:24:33.597
But finding the middle ground that
will be just fine for everyone, like
00:24:33.597 --> 00:24:34.977
doing all this really complicated work.
00:24:35.477 --> 00:24:39.927
And then another group of people or,
or you, with a different hat on, can
00:24:39.927 --> 00:24:42.477
then start to say, well then these
are the end points that I need.
00:24:42.477 --> 00:24:44.697
But even then, like, is the,
is jumping straight into
00:24:44.697 --> 00:24:46.257
endpoint endpoints premature.
00:24:46.257 --> 00:24:50.027
Like, do, do you need to think a little
bit more about, about kind of the
00:24:50.027 --> 00:24:53.207
workflows and the, and the type of API
that could be used and like, should
00:24:53.207 --> 00:24:56.507
this even be a, a endpoint based API
or should, should it be event driven?
00:24:56.897 --> 00:24:59.927
There's, there's so many stages to the
planning and it's hard to figure out.
00:25:00.257 --> 00:25:03.557
Where you should start and open
API and design the spec first.
00:25:03.557 --> 00:25:05.807
Stuff like it doesn't help
you with any of any of that.
00:25:06.117 --> 00:25:11.187
Like you, literally, your planning
starts with Slack calls and whiteboards
00:25:11.277 --> 00:25:13.627
and like Miro boards and sequence
00:25:13.717 --> 00:25:17.017
sequence flow diagrams and like
chatting to a load of people and
00:25:17.017 --> 00:25:19.957
having a spreadsheet of feedback and
all this crazy stuff that no one,
00:25:20.347 --> 00:25:23.167
no one that I know is really working
on, apart from the tools that I've
00:25:23.167 --> 00:25:24.637
mentioned, but they're like generic.
00:25:25.267 --> 00:25:26.887
And then once someone has says.
00:25:27.172 --> 00:25:32.032
Someone has said, you definitely
need to make a HT PAPI and it
00:25:32.032 --> 00:25:33.382
should probably do these things.
00:25:33.932 --> 00:25:35.672
That's when it's time
to get the open API out.
00:25:35.702 --> 00:25:38.462
'cause you're literally turning the words
they've just said right there of like,
00:25:38.462 --> 00:25:39.992
make an API that does this, this and this.
00:25:39.992 --> 00:25:42.632
Then you kind of are going, well okay,
we'll have that end point, that end
00:25:42.632 --> 00:25:45.032
point and that then end point and.
00:25:45.422 --> 00:25:48.872
Where design first gets really handy
there is you can say, okay, I'm gonna turn
00:25:48.872 --> 00:25:52.262
those words into, like, I'm gonna reshape
them into a little bit of yaml and I'm
00:25:52.262 --> 00:25:54.002
gonna like, the A PO will look like this.
00:25:54.302 --> 00:25:58.412
Then it's much easier to change that
little bit of YAML than it is to go and
00:25:58.412 --> 00:26:00.602
change a whole pile of Laravel code.
00:26:00.602 --> 00:26:04.172
You're like, oh God, now I've got rename
all of my controllers and that means
00:26:04.172 --> 00:26:07.562
I've gotta rename all my models and all
the relationships are gonna be broken.
00:26:07.922 --> 00:26:08.522
And I, you know,
00:26:08.552 --> 00:26:10.112
that's, that's really daft.
00:26:10.112 --> 00:26:10.712
And so
00:26:11.012 --> 00:26:12.212
pretending that.
00:26:12.932 --> 00:26:16.652
Code first is quicker 'cause you just add
some annotations to some code that you
00:26:16.652 --> 00:26:20.552
wrote is predicated on the fact that you
wrote exactly the right code first time.
00:26:20.942 --> 00:26:22.472
And when does that happen?
00:26:24.557 --> 00:26:25.037
Joel Clermont: It doesn't.
00:26:25.037 --> 00:26:25.877
Right, exactly.
00:26:25.877 --> 00:26:26.927
At least not for anything.
00:26:26.932 --> 00:26:27.572
Non-trivial.
00:26:27.572 --> 00:26:29.202
Phil: Yeah, well, alright.
00:26:29.352 --> 00:26:30.642
Pretty decent agreement on that.
00:26:30.972 --> 00:26:31.512
Screw.
00:26:31.962 --> 00:26:32.622
Screw that.
00:26:33.657 --> 00:26:34.167
Joel Clermont: Awesome.
00:26:35.227 --> 00:26:35.742
Phil: That was
00:26:35.787 --> 00:26:38.097
Joel Clermont: See, I I we're far
too reasonable, Phil, in our, in
00:26:38.097 --> 00:26:41.537
our older age and maturity we're,
we're mellowing and we're, we're just
00:26:41.537 --> 00:26:43.097
seeing things much more reasonably.
00:26:43.472 --> 00:26:44.012
Phil: Absolutely.
00:26:44.072 --> 00:26:44.492
Absolutely.
00:26:44.492 --> 00:26:46.772
I haven't had a fight about framework
interoperability in a long time.
00:26:47.322 --> 00:26:48.162
Well, fantastic.
00:26:48.222 --> 00:26:50.902
Let's, let's call that where
can people find more of you?
00:26:50.902 --> 00:26:53.122
You are, you're all over the
internet doing all sorts of things.
00:26:53.122 --> 00:26:54.202
What, what what are you up to?
00:26:54.817 --> 00:26:58.957
Joel Clermont: Yeah, my, my main hub of
activity now is mastering laravel.io.
00:26:59.017 --> 00:27:02.062
You know, on there we have
a podcast for Laravel and PP
00:27:02.067 --> 00:27:03.657
devs, the, the mailing list,
00:27:03.987 --> 00:27:06.597
some books and courses if you
wanna, like, keep me fed, like,
00:27:06.597 --> 00:27:07.887
you know, all, all that good stuff.
00:27:07.887 --> 00:27:10.017
But that's, that's really the
central point for all of it.
00:27:10.467 --> 00:27:10.977
Phil: Nice.
00:27:11.157 --> 00:27:15.097
I will have to I need to get on
that newsletter because I am using
00:27:15.097 --> 00:27:19.297
Laravel more and more and they've
gone, they've gone on like a rampage
00:27:19.297 --> 00:27:22.687
of major versions and I'm like, I, I
remember thinking four and five are
00:27:22.687 --> 00:27:24.607
quite nice and now version eleven's out.
00:27:24.607 --> 00:27:25.957
I'm like, I don't know what's happening.
00:27:25.957 --> 00:27:26.317
Brilliant.
00:27:26.692 --> 00:27:28.132
Joel Clermont: Yeah, it
does tend to move quickly.
00:27:28.530 --> 00:27:28.950
Phil: Cool.
00:27:29.100 --> 00:27:31.830
Alright, well thank you very much and
yeah, pleasure having you on the show.
00:27:31.985 --> 00:27:32.255
Joel Clermont: Yep.
00:27:32.255 --> 00:27:33.035
Talk to you later.
