Over Engineered

00:00:07.56
Chris Morrell
All right, welcome back to over-engineered, the podcast where we asked the question, what's the absolute best way to do things we have an already perfectly acceptable solution for. Uh, today I am here with Steve McDougall and we're going to be talking a little bit about APIs. Um, but before we get into it, Steve, do you want to do a quick introduction of yourself?

00:00:28.23
Steve McDougall
Yeah, hey, I'm Steve McDougall. Most people know me as just Steve King. I do APIs. I'm a developer advocate at a company called Treble, and I spend a lot of my time focusing on educational content.

00:00:45.68
Chris Morrell
Sweet. um Well, this is this is fun. this isn't This is another episode where we kind of got connected through through someone suggesting this on Twitter. And I don't know, this this whole podcast for me is essentially just an excuse to like meet new people and talk about interesting things that are interesting to me for longer than I usually have time to to talk about those things. ah So this is kind of like,

00:01:11.66
Steve McDougall
is a good edge excuse.

00:01:13.47
Chris Morrell
Yeah, the the excellent outcome of that. And ah yeah, i I'm interested to see where this comes because ah before we we decided to record, I was pretty upfront that like I'm not a huge believer in like going all in on APIs. So I think we're coming from very different perspectives.

00:01:33.92
Steve McDougall
We really are

00:01:34.26
Chris Morrell
um And I think that's gonna be interesting. and And also we just discovered the the look on your face when I said I wasn't a ah ah view guy. You you you looked surprised.

00:01:44.67
Steve McDougall
I know. I was horrified.

00:01:51.75
Chris Morrell
Yeah, i don't I don't know why. I mean, when we were deciding what sort of, you know, bigger stack we were gonna use for for when we were what we needed to do really like sophisticated UIs, um I think most of the decision just came down to there's more there's more available in the React world. So ah certainly when we were deciding, there was just more available in the React world.

00:02:18.62
Steve McDougall
Yeah.

00:02:20.05
Chris Morrell
ah you know, pretty much any component that you need, someone's going to already have built like a really nice, accessible version of it.

00:02:27.56
Steve McDougall
Yeah, 100%.

00:02:27.80
Chris Morrell
And at the time that wasn't as true for view, although I think that's, that's changing now. Now most things, there's a really good view.

00:02:33.28
Steve McDougall
Yes, come on in leaps and bounds, actually. I've been diving quite deep recently, and I've kind of stumbled over lots of hidden gems.

00:02:36.39
Chris Morrell
Yeah.

00:02:42.19
Chris Morrell
Interesting. But yeah, i I also have to say like the whole, um,

00:02:49.34
Chris Morrell
the way view components are put together, just never like fit with my brain. I like, I don't know, I like JSX. I like the way it just, I don't know, it's just like XML and JavaScript, you know, it's not, you're not learning like VIF and I don't know, all these like special attributes and stuff.

00:03:07.44
Steve McDougall
Yeah.

00:03:07.61
Chris Morrell
It's it's funny, cause I know that's that's what makes it appealing to a lot of other people, so.

00:03:11.89
Steve McDougall
Yeah, no, 100%. It's kind of what drew me to it when I first started with Vue, because I mean, I used Vue when it was, you know, alpha RC1 as a way to get away from jQuery.

00:03:22.98
Chris Morrell
Okay.

00:03:24.37
Steve McDougall
So I kind of jumped on it and stuck with it.

00:03:24.99
Chris Morrell
huh

00:03:29.59
Chris Morrell
It's funny too, because I love, I love Alpine so much and Alpine is effectively view, like view light, you know, uh, in a lot of ways.

00:03:37.78
Steve McDougall
Yeah.

00:03:39.99
Chris Morrell
So it's, it's funny that I say that the the syntax doesn't appeal to me because when I'm writing Alpine code, I'm like, Oh, this is the best thing. But I think for me.

00:03:48.75
Steve McDougall
It's all about context, right?

00:03:50.97
Chris Morrell
It is, it's very much about context. It's like Alpine, the syntax feels right. Cause you're just kind of like sprinkling it into existing HTML. Whereas if I'm, if I need to build a really sophisticated UI, um, I feel like I go into a different mindset.

00:04:01.76
Steve McDougall
Yeah.

00:04:09.08
Chris Morrell
Yeah, I definitely think that's true.

00:04:11.98
Steve McDougall
I need to be fair, I haven't built a sophisticated UI in so many years. So I'll leave that decision to people who actually know what they're doing.

00:04:21.53
Chris Morrell
Well, I don't know who who knows if what I build is sophisticated, but it's something, um,

00:04:27.11
Steve McDougall
Most of the time I build a form and a card and I'm like, okay, I've i've done front end, I'm happy.

00:04:33.06
Chris Morrell
there you go. So yeah, you are you're you're all about APIs.

00:04:38.88
Steve McDougall
I am.

00:04:39.19
Chris Morrell
um and when you So like where' what's the intersection of that and your Laravel sort of experience? is that Is that mostly how you're implementing APIs? Or do you do all sorts of different things? I don't know. where Where does that play out?

00:04:54.78
Steve McDougall
Yeah, it really varies. I mean, I got into APIs through slim PHP, then implemented APIs in Laravel for so many years.

00:05:03.21
Chris Morrell
OK.

00:05:07.47
Steve McDougall
But these days, you know if I'm building an ah API with Laravel, it's usually attached to an application.

00:05:15.66
Chris Morrell
Mm-hmm, sure.

00:05:15.91
Steve McDougall
If I'm building like a standalone API, I'm typically reaching for something like Golang or um like Honno is another good one in the TypeScript world. um I've used that a couple of times now.

00:05:29.13
Chris Morrell
Okay, yeah, I'm not familiar with that.

00:05:31.42
Steve McDougall
Yeah, dude it's it's quite nice. Laravel, obviously it's super powerful when you need to do more than just the basics.

00:05:39.92
Chris Morrell
Mm-hmm.

00:05:39.97
Steve McDougall
So if if I need an application that also needs an API, also needs an admin panel, then I'll go full in on something like the tool stack and add an API to it as well.

00:05:50.89
Chris Morrell
Okay, um so you you came in kind of guns blazing saying ah that that you you sort of get behind this idea that SPAs are still the way to go, that the the push towards inertia or live wire or just regular old blade um is not your preferred approach.

00:06:06.27
Steve McDougall
Yeah.

00:06:15.56
Chris Morrell
and

00:06:15.61
Steve McDougall
Definitely.

00:06:16.54
Chris Morrell
That is ah kind of astounding to me. So I'd love to hear more. like ah let's let's hear your Let's hear your pitch.

00:06:24.52
Steve McDougall
I mean, I suppose I'm still stuck on the whole, you know, the Jamstack was a huge thing for us in in the industry. And I don't think we fully realized the potential of what the the Jamstack could be. You know, and these days, so many, there's so many use cases and needs for an API that

00:06:51.65
Steve McDougall
adding it as an after afterthought always causes more frustrations than anything. So i I like to build out my API, and then maybe I'll throw nuxed on the front end, then maybe I'll do a CLI, maybe I'll do a mobile app, or or something as always, extra tools I'm adding to to applications that I build to make using that that product or that service a little bit easier, whether that's a Raycast extension or a CLI tool. There's always a way that I want to add extra productivity boosts over just go to this web page and click these buttons.

00:07:35.56
Chris Morrell
um And I mean, so when you say JAMstack, you're you're really just talking about like the JavaScript API, what is it? A JavaScript API markup?

00:07:45.73
Steve McDougall
Markdown.

00:07:46.31
Chris Morrell
Is that the M? Yeah.

00:07:47.60
Steve McDougall
Markdown although to Yeah, i'd probably say mdx over markdown these days just because you kind of want to add some some level of uh components inside that markdown as well sometimes

00:07:48.51
Chris Morrell
Oh, markdown.

00:07:53.06
Chris Morrell
Mm-hmm.

00:07:59.77
Chris Morrell
Sure. Yeah, I mean, you know we we were just talking about this on and on a previous episode. the or This has kind of been the theme of the last couple episodes, and I've i've probably said this a couple times, but I'll say it again. I still totally buy the, or I don't know, I still see the dream of like, everything is JavaScript, right?

00:08:24.36
Steve McDougall
Yeah.

00:08:24.91
Chris Morrell
Because in, you know, this is what I keep on coming back to, and this is kind of a thing that I kept on coming back to when the whole sort of nonsense with Ryan Florence was going on a couple of weeks ago, is like, you know, in the end, browsers run JavaScript, right?

00:08:44.47
Steve McDougall
Yeah.

00:08:45.16
Chris Morrell
that is And the browser is the constant that we all have to deal with.

00:08:46.40
Steve McDougall
Yeah.

00:08:48.97
Chris Morrell
um So i I totally, totally get the appeal of a world where you're just writing, you know, you're just writing JavaScript everywhere. um

00:09:00.00
Steve McDougall
Yeah. And from a kind of a business perspective, like if JavaScript is running everywhere, the way that you're gonna extend your capabilities is to plug into an API, either a third party or a self-hosted. And then from a, yeah, I'm a developer advocate. I spend so much of my time creating content, which is predominantly marked down. So for me, something like JAMstack still

00:09:30.75
Steve McDougall
it's still really useful.

00:09:32.63
Chris Morrell
Sure. Yeah. I think, I think something that, uh, uh, one of my, my teammates and I were talking about yesterday sort of, um, just idly, uh, idly talking about the episode today is. And I think that this gets missed in the conversation a lot of times around these topics is sort of team size and, uh, composition, I think has a lot more to do with these decisions than we, we tend to acknowledge because I think, um, you know, a lot of the promise of, of, uh, you know, sort of API first design, um,

00:10:03.69
Steve McDougall
Yeah, massively gone.

00:10:21.86
Chris Morrell
comes down to, you know, you're, you're going to be implementing different consumers of your API. Maybe you're doing a mobile, mobile app and a web app, or you're, you've got a big enough team.

00:10:28.06
Steve McDougall
Yeah.

00:10:31.92
Steve McDougall
or you've got partners that are going to leverage your API. you know If you're building a developer at tool, for example, you need an API and you need a good API.

00:10:34.87
Chris Morrell
Yep. Yep.

00:10:40.56
Steve McDougall
Otherwise, they're going to try. yeah Everybody's had that experience where they've tried to work with an API, found it frustrating and said, you know what, I'm going to go use this one instead because it's easier.

00:10:53.66
Chris Morrell
Yeah. Yeah. I mean, anything that, anything that's, you know, where you're trying to work with developers, having good integrations is going to be a huge, huge boon for sure.

00:11:07.42
Steve McDougall
yeah

00:11:08.53
Chris Morrell
um But yeah, I mean, I think, I think that some of the conversation around like, A lot of this stuff, both ah on the API side and on the JavaScript side, ah in the Laravel community specifically comes down to, I you know i think a lot of Laravel developers, um my impression is, or the the folks that I interact with, um it's a lot of small, effective teams, right?

00:11:30.60
Steve McDougall
Yeah.

00:11:36.22
Chris Morrell
It's like one, two, three people who are building or maintaining an entire product, right?

00:11:36.81
Steve McDougall
Yeah.

00:11:43.54
Steve McDougall
A lot of boot scrap is basically right.

00:11:45.92
Chris Morrell
A lot of bootstrappers, but also I think even when you get out of the bootstrapping phase, I mean, you know my organization's been around for 20 plus years and we still, and and almost everything that we do is enabled by web technology of some sort.

00:11:54.83
Steve McDougall
Yeah.

00:12:02.19
Chris Morrell
And we're still you know a team of three developers and you know and only two of the developers are full-time because I have lots of other responsibilities in the organization.

00:12:02.14
Steve McDougall
Yeah.

00:12:12.82
Chris Morrell
um So, you know, we're able and we're able to do that because, um, of our approach in a lot of ways, like if we, if, if it was a couple of bigger, siloed teams, we'd have to, we'd have to be thinking about it very differently, but we wouldn't be able to be as nimble as we are.

00:12:34.23
Steve McDougall
Yeah.

00:12:38.18
Chris Morrell
Um, or I think as impactful as we are, uh,

00:12:42.84
Steve McDougall
Definitely.

00:12:43.08
Chris Morrell
with that approach, but it comes with trade-offs.

00:12:43.71
Steve McDougall
And I think you know you your industry and your experience kind of dictates whether something like API first is going to be useful. It's not useful for everyone. It's super useful for those who need it. But for probably about 80% of the developers they They're probably not going to adopt API first because most of the time API is an afterthought for them.

00:13:11.81
Chris Morrell
Yeah. Yeah, I mean, I think that API first feels a little bit like, like, I don't know. To me, it feels a little bit like Um, building for scale from the beginning though, it's like so many developers get caught up in this idea of, Oh, well, I need to make this work for a billion concurrent requests.

00:13:31.87
Steve McDougall
Yeah. Yeah.

00:13:42.42
Chris Morrell
Right. And it's like, when you get to, you know, a thousand concurrent requests, you're going to have all sorts of other stuff that you need to sort out, you know, you'll, you'll figure it out when you get there.

00:13:43.35
Steve McDougall
Yeah.

00:13:51.09
Steve McDougall
You've got to worry about other things first, and you know you're your your reinvention of the to-do app isn't going to need that level of scale.

00:14:00.96
Chris Morrell
But it it also feels to me, I think this is this is part of it for me is like the the API first mentality sometimes feels the same way. It's like, well, I need to build an API. I need to build and dog food an API because what if I build a mobile app and what if we have third party integrations? And it's like, well, I don't know, when you're ready to build a mobile app,

00:14:23.95
Steve McDougall
What it don't.

00:14:26.87
Chris Morrell
the the needs of that app in in terms of the API it's going to consume, like you don't know what it's going to need yet.

00:14:34.65
Steve McDougall
Yeah.

00:14:35.10
Chris Morrell
And you don't know what third party integrations are going to need. Like I get your point that it can feel like an afterthought, but I also think in a lot of ways, in my experience, if you try to Optimize for those things early before you really have a use case for them. You end up just like spending a lot of time building something that ends up not being the right thing anyway. I don't know.

00:15:01.04
Steve McDougall
Yeah.

00:15:01.37
Chris Morrell
Do you think that's, that's it all true in your experience?

00:15:02.97
Steve McDougall
No, I totally personally agree. I mean, there there's been so many times when I've built an API and then went to use it with something afterwards. It just, it all just felt wrong. And I wanted to use someone else's API instead of my own.

00:15:16.97
Chris Morrell
Right.

00:15:19.70
Steve McDougall
So it was one of those, you know, certain situations API first is absolutely great, but 80% of the people, they they won't need it. They won't want it. They won't benefit from it. you know It works well at that enterprise level where you've got you know so many different teams all wanting to integrate with the same API, whether that's a web team, the Android team, the iOS team, yeah some other team that also needs to integrate with that service.

00:15:32.87
Chris Morrell
Yeah.

00:15:50.18
Steve McDougall
you know very API first in those situations, make it makes the most sense.

00:15:56.51
Chris Morrell
Yeah.

00:15:56.59
Steve McDougall
But i yeah I still don't design my APIs using an open API spec. I generate my open API spec once I've built my API.

00:16:07.21
Chris Morrell
Um, um it it almost feels to me like it's, it's kind of similar to TDD almost like for me, TDD can be incredible.

00:16:17.51
Steve McDougall
Yeah.

00:16:20.29
Chris Morrell
I mean, I've, I've, I've had just like amazing sort of mind blowing development sessions where I'm just like, I wrote out all these tests and then I'm just getting them green and everything's perfect. But.

00:16:32.55
Steve McDougall
So I go for something what I call TPD, which is Test Proven Development. I've totally made up praise where, because half the time when I'm writing tests, I have no idea what I want the code to actually do. So I end up writing the code, then writing tests and then tweaking and refactoring.

00:16:45.62
Chris Morrell
Right.

00:16:51.76
Chris Morrell
Well, and and that feels kind of similar to the API stuff in that. If you know, if you're really confident in what you need the outcome to be, writing the test first can be really, really, really useful. And it feels like it would be similar with the API stuff.

00:17:06.54
Steve McDougall
Yeah.

00:17:08.77
Chris Morrell
If you're really confident in what consuming this API is gonna feel like, then, um you know, build build that, right?

00:17:09.25
Steve McDougall
Yeah.

00:17:19.62
Chris Morrell
And go with it.

00:17:19.83
Steve McDougall
Yeah. 100%.

00:17:21.47
Chris Morrell
um But if you don't,

00:17:21.56
Steve McDougall
I mean, a lot of the time when I design an API, I will, I kind of integrate with it while I'm building it so that I can feel the frustrations of the API as I'm building it so I can act on act on it a lot quicker.

00:17:35.66
Chris Morrell
Mm hmm.

00:17:35.68
Steve McDougall
And that, yeah, that might be through some HTTP client or it might be through, you know, a Raycast extension that I just throw together just so that I can test it, depending on the implementation need.

00:17:44.94
Chris Morrell
Mm hmm.

00:17:46.74
Steve McDougall
But I do try my best to, you know, approach it like I would test because yeah you can draw a lot of parallels.

00:17:57.42
Chris Morrell
Yeah, yeah, although that's always tricky because I years ago, we integrated with this, um, it was a, it doesn't, it doesn't matter. We, we integrated with this, this API that was clearly someone, someone built it with this like principle of like build the API, you know, dog food, your own API that, that the, that they were building their API and building the primary UI for this tool hand in hand.

00:18:31.76
Chris Morrell
And.

00:18:31.74
Steve McDougall
Yeah.

00:18:33.51
Chris Morrell
the The thing that was so awful about it was all it meant was that the API ended up being 100% coupled to their specific use case.

00:18:37.15
Steve McDougall
Yeah.

00:18:43.64
Chris Morrell
I mean, even down to the naming of the inputs and outputs matching the the names of the fields in, you know, in their UI.

00:18:53.22
Steve McDougall
Yeah.

00:18:53.73
Chris Morrell
um And so, you know, it's like, that's a great idea that, you you know, consume your API as you're building it, unless unless it ends up meaning that you just build an API that's custom tailored to just your one specific use case.

00:19:08.82
Steve McDougall
Yeah, I mean, I actually spoke about that in, when I spoke at Larraconi, you in Portugal, you know, APIs need to be designed for the purpose, not, you know, it's not a ah one size fits all with an API, you might have an internal API, and then you have, you know, external parts to the API or admin aspects to the API. So you really need to kind of design the API that you need, not just builds these kind of CRUD interfaces and call it an API.

00:19:42.98
Steve McDougall
Because a lot of the time you're building those out based on your needs, not the person who's going to use your API.

00:19:43.18
Chris Morrell
ah Right.

00:19:50.51
Chris Morrell
So but it sounds to me like all this aside, your take is, you know, if you if you got to pick, you would you would write out an API and then build build an SPA if you were starting from something from scratch today.

00:20:05.85
Steve McDougall
100%. Yeah, I mean, yeah.

00:20:08.15
Chris Morrell
So what

00:20:10.66
Chris Morrell
what about that you know what What about that really appeals to you and and you know what are you what do you think are some of the major benefits of that approach in this and sort of in the day this day and age?

00:20:24.05
Steve McDougall
So, I mean, i'll talk I'll talk about it from the kind of opposite end. Like a lot of the time I'll build a live wire tool stack application and I hit a point in the development where I've got to start trying to be overly creative to try and get the UI to do things that I want it to do because we don't have JavaScript.

00:20:44.94
Chris Morrell
Mm-hmm Sure Mm

00:20:50.19
Steve McDougall
you know and then okay so I use Alpine but then I'm ending up writing lots of JavaScript that is usually badly written by myself but it's not organized it's not componentized it's it's not benefiting from the yeah ven newer JavaScript ecosystem. so okay I go over and I try inertia and then that's all great and I get and you know i get a couple of steps yeah closer to where I want to be with my application, but then I'm missing all of the modern front-end tooling that could also benefit my application.

00:21:08.64
Chris Morrell
-hmm

00:21:28.99
Steve McDougall
so If I go straight for an API and go for

00:21:30.68
Chris Morrell
Can you, wait, can you give an example of that? I'm not i' not quite sure I follow on the the tooling piece.

00:21:36.26
Steve McDougall
Yeah, like mono repos and um yeah nux, for example, there's nux layers, there's nux modules.

00:21:43.49
Chris Morrell
Okay.

00:21:44.78
Steve McDougall
um And then if you're kind of looking outside of nux, you've got things like um learner for the, like the mono repo builds where you can have component libraries and applications that are kind of all baked into that one repo with that more mature front end tooling, which allows you to

00:21:51.51
Chris Morrell
Hmm, okay, sure.

00:22:04.86
Steve McDougall
you know, work with each component in isolation as well as within the context of the application. So by adopting an API and

00:22:11.75
Chris Morrell
Mmhmm.

00:22:17.66
Steve McDougall
adopting something like you know nuxed with nuxed layers or monorepo approach you're getting the best of both worlds because your front end tooling is the best it can be and then your back end tooling is also the best it can be because where PHP really shines is with database interactions, with that kind of that stateless request response lifecycle. So you're kind of getting the best of both worlds at that point.

00:22:49.60
Chris Morrell
h Yeah, I mean, I can see, you know, the the moment that you have sort of multiple sophisticated interactions that are all sort of layered on top of each other inside of the page, that definitely is where

00:23:09.44
Chris Morrell
the livewire or inertia approach gets a little bit trickier because they they tend to be like full component level, full page level.

00:23:19.77
Steve McDougall
Yeah.

00:23:20.82
Chris Morrell
Although I know you know i know that that's not 100% true of livewire, but I'm not super fluent in you know building anything super sophisticated in livewire. So i I don't know for sure. um

00:23:34.22
Steve McDougall
Yeah, I mean, I've tried to build some pretty complicated things in Livewire, and, you know, that was mainly Livewire too, and there was always some form of kind of compromise that I had to make to achieve what I needed to um and again the same thing with inertia but that's because I was yeah I'm i'm trying to do it within the context of a

00:23:51.99
Chris Morrell
Mm hmm.

00:24:00.79
Steve McDougall
a Laravel application at that point. I'm not able to benefit from this tool or that tool or this new thing that the React team have just released. That's only focusing on Next and Vercel because that's kind of like the front-end feeding ground now. So yeah you're missing out on a lot of yeah potential great bits of tooling that you could use by trying to smush these two things together when you could benefit from just letting them be good at what they're actually good at.

00:24:19.73
Chris Morrell
Right.

00:24:36.29
Chris Morrell
So what's your take on, um you know, I feel like the two other approaches in the JavaScript world are either um GraphQL or, you know, recently you got ready React server components, you've got More, I think a bunch of different interesting approaches, you know, before ah server components for cell had a version of, you know, server executed code that sat inside of the component.

00:25:04.68
Steve McDougall
Yeah.

00:25:06.64
Chris Morrell
I know that um ah remix has that same concept as well. Um, where you're kind of blur, in that case, you're kind of blurring the line between the client, the server, and, and there's not really this API layer so much.

00:25:20.57
Steve McDougall
yeah

00:25:23.51
Chris Morrell
Um, and then, you know, in the graphic QL side, it's just a, you know, a different, a different approach to to querying and and passing information around.

00:25:33.66
Steve McDougall
Yeah, so I mean, from a like a server component perspective, I mean, the way that I've always seen JavaScript on the server is just like someone's written a HTTP server in jQuery and it just instantly makes me shudder. I know that's not the case, but it just feels like we're trying too hard to get JavaScript to run everywhere that we we we haven't stopped to ask ourselves, should it? um

00:26:08.68
Steve McDougall
that and I suppose with GraphQL, like yeah it was designed at Facebook to fit a very specific problem 10 to 15 years ago when 3G was the fastest we had and we were worrying about you know other things in the technical industry and you know now you know we've got 5G in a lot of places 4G I mean I'm in rural Wales, so yeah I don't have the fastest internet connection in the world.

00:26:45.17
Steve McDougall
um But yeah I still get 4G in most places.

00:26:45.32
Chris Morrell
Mhmm.

00:26:49.26
Steve McDougall
And then there's HTTP2 and HTTP3, which means that we've got bidirectional transport, which means that the problems that GraphQL was designed to kind of overcome don't exist anymore. The only real application is that people can be a little bit more choosy on the data that they want back specifically. But JSON API spec also allows that through REST. So it's, you know, there's certain situations where GraphQL is the right choice.

00:27:27.54
Chris Morrell
Sure.

00:27:27.66
Steve McDougall
There's not many across where I've thought this would really benefit from GraphQL.

00:27:28.72
Chris Morrell
Yeah, I mean.

00:27:35.84
Chris Morrell
that's That's my take as well. I mean, I remember when GraphQL first started to gain popularity. ah I got why everyone was excited about it. you know that this ah you know It felt like a really interesting, expressive way to ask for data from the server.

00:27:58.47
Steve McDougall
Yeah.

00:27:58.70
Chris Morrell
and you know the idea of sort of just saying exactly what you need and letting the server take care of that is, is very appealing. um And, you know, I think it does, it solves, it solves some interesting problems, sometimes around versioning and deprecating ah data and stuff like that because you

00:28:09.12
Steve McDougall
Yeah.

00:28:16.84
Steve McDougall
Yeah.

00:28:22.21
Steve McDougall
yeah

00:28:22.77
Chris Morrell
you know you have a little bit more flexibility to just say, yeah, both ways are fine. you know Until no one's using the old way, we'll just keep it around because we can just have the new way and it's fine.

00:28:28.52
Steve McDougall
Yeah.

00:28:33.90
Steve McDougall
Definitely.

00:28:34.04
Chris Morrell
um Which obviously other API approaches you you can do, but I think GraphQL ah tends to make that better.

00:28:40.31
Steve McDougall
Yeah, GraphQL really got got it right when they introduced things like deprecated and things like that. I definitely think that works well, but To put it in as blunt a way as a British person could do, it just feels like I'm programmatically filling in an advanced search form field to to ask for something from an API.

00:29:03.34
Chris Morrell
Yeah, well, ah yeah, that's that's that's basically what I was getting to is I i get all that and and there are good things, but every time I have to consume a GraphQL API now, I just shudder.

00:29:03.40
Steve McDougall
yeah it Advanced search over HTTP.

00:29:21.31
Steve McDougall
Yeah.

00:29:21.61
Chris Morrell
Because, I mean, especially if you're not dealing with GraphQL in JavaScript where the, the you know, the the SDKs and and sort of

00:29:27.78
Steve McDougall
Yes.

00:29:33.89
Chris Morrell
Developer tools are there consuming, you know, consuming a rest API in any language is basically easy and supported. Right.

00:29:43.78
Steve McDougall
yeah

00:29:44.32
Chris Morrell
But, um, you know, maybe to a fault, I don't know, but I am certainly just, uh, an absolute slave to my ID in terms of syntax highlighting and auto complete.

00:29:54.55
Steve McDougall
Oh, so am I. Like, i I can't do anything if I'm not in PHP Storm.

00:29:56.16
Chris Morrell
And, uh,

00:30:00.09
Chris Morrell
ah Right, yeah. And PHPStorm has great GraphQL support, but it doesn't, ah you know, there isn't sort of like a canonical way to do graphic GraphQL queries in PHP. So, you know, you're not getting you're not getting inline syntax highlighting unless you you write all your queries in separate separate GraphQL files and then like load those files.

00:30:12.83
Steve McDougall
No.

00:30:23.70
Steve McDougall
and then copy and paste them or load them in or something. Yeah, you it never feels like a complete picture.

00:30:26.21
Chris Morrell
yeah

00:30:30.94
Chris Morrell
Yeah, yeah, yeah. And it just doesn't feel like it was made for anything but that one use case.

00:30:36.91
Steve McDougall
Yeah.

00:30:38.56
Chris Morrell
So I mean, and and i think I think the world has has moved on for the most part. I mean, there are some very popular tools that still use it. you know I know that GitHub's primary API is GraphQL. I know Linear's API is GraphQL.

00:30:51.07
Steve McDougall
Yeah.

00:30:52.12
Chris Morrell
like There are lots of very big, successful, effective tools that that use GraphQL. um But i don't you don't see it as the first choice everywhere all the time, like it was a few years ago.

00:31:07.67
Steve McDougall
No. I'm seeing a lot more people adopting like TRPC over GraphQL these days.

00:31:14.90
Chris Morrell
h Yeah, i see i've seen I've seen a lot of conversation around new RPC protocols, but I'm not familiar with with them at all. So what is TRPC?

00:31:27.11
Steve McDougall
It's basically... um Just TypeScript remote procedural calls, I believe. It's like GRPC for TypeScript. eight's you know It makes a lot of sense if you're in a microservices space, but if you're not, then you're just adding lots of tooling and build steps to join in with the cool kids.

00:31:37.35
Chris Morrell
Okay.

00:31:51.51
Chris Morrell
Sure. It's, I mean, it's interesting because, you know, RPC, the, the principle between ip RPC behind RPC, um, that appeals to me the most is it's essentially just another function call or you know it it feels like another function call. right you're you just There just happens to be a network in between you and the function call.

00:32:20.76
Steve McDougall
Yeah.

00:32:22.23
Chris Morrell
um But it's interesting because ah sometimes having that much flexibility is is actually a problem, right, in terms of of consistency and and sort of knowing where things are. And and that that you know that's a complaint that I have about GraphQL as well.

00:32:38.64
Steve McDougall
Yeah.

00:32:43.12
Chris Morrell
um It's just like, You know, with rest, there are very specific conventions that almost everyone agrees about, right?

00:32:53.13
Steve McDougall
Yeah.

00:32:53.62
Chris Morrell
um In terms of thinking about things as resources and we have specific verbs that we use to deal with those resources.

00:32:56.73
Steve McDougall
Yeah.

00:32:59.07
Steve McDougall
There's rest principles for a reason, right?

00:33:01.78
Chris Morrell
Yeah. Um, and when you get back to, you know, RPC, you know, we've had this Prince, we've had this idea for ages, like how many people have had to deal with like a soap, a soap API back in the day.

00:33:13.99
Steve McDougall
Yeah.

00:33:16.75
Chris Morrell
Right.

00:33:16.77
Steve McDougall
Yeah.

00:33:17.11
Chris Morrell
It's the same, same idea. Um, you, huh?

00:33:20.75
Steve McDougall
Just reimagined by Google. just reimagined by Google.

00:33:25.89
Chris Morrell
Right right, but it's like you know you you that that level of flexibility just means that Everyone can do it differently Which is not necessarily great um Right

00:33:37.38
Steve McDougall
Yeah. Yeah, it definitely throws a spanner in the works if, you know, as soon as you need more than just yourself to use it.

00:33:52.14
Chris Morrell
um

00:33:54.81
Chris Morrell
Yeah. I think that, um, you know, I think that I'm trying to remember it's, it's Adam Waffen who did the, um, the talk, the layer con talk years ago ah about, um, about the, I think, I think I could be getting this wrong, but sort of there, there was a, a really sort of central talk in the Laravel community about

00:34:17.52
Steve McDougall
Yeah.

00:34:21.36
Chris Morrell
um embracing those sort of restful, cruddy um design ideas just across your application. um and And it really did come back to just like that idea of if everyone follows these same basic conventions, then when you come back to your code five years later or when a new developer who's familiar with the conventions comes in, it's easier to find things. And, um you know, I think that that's another one of those, one of those ideas that really is dependent on the size and composition of your team, because, you know, if you're working on your own little thing, who cares?

00:34:50.67
Steve McDougall
Yeah.

00:35:01.19
Steve McDougall
Yeah, definitely.

00:35:04.49
Chris Morrell
You know, do whatever you want.

00:35:05.02
Steve McDougall
yeah You do what you want to do because you're only affecting yourself.

00:35:09.56
Chris Morrell
Yeah.

00:35:09.73
Steve McDougall
I think a lot of my kind of opinions and approaches they They kind of built up over time based on me just being a developer, just like everyone else, we grow our own opinions. But i was I've been an engineering manager and an engineering kind of technical leader for quite a while and onboarding new team members, you know acquiring products and taking that into a team. You see a lot of pain points.

00:35:43.46
Steve McDougall
in the kind of day-to-day development workflow.

00:35:44.35
Chris Morrell
Yeah.

00:35:46.34
Steve McDougall
And you start to kind of get really picky about, it okay, this is how we write code. This is why we write code this way. Here's 12 pages on Notion, why we write code this way. um you You start to kind of obsess over it, I guess. But once you've kind of seen the pain of a larger team, you kind of just get stuck in that way of okay I've got to write it this way because if I ever hire someone to do it or if I come back to it in five years I want to make sure that is all done in this nice square box that I understand as this is how code works

00:36:29.14
Chris Morrell
Yeah, yeah, there's there's a lot of value to that. um And it's, you know, I think it's a lesson, I think you're right, it's a lesson everyone kind of learns in their own way. um and And you kind of decide how to prioritize that in different ways, whether it's, you know, code standards or, or um you know, embracing tooling that kind of enforces different rules or,

00:36:58.39
Steve McDougall
Yeah.

00:36:59.98
Chris Morrell
Yeah, there's a, there's a lot there. I actually think I might, we, I might be recording an episode on like, uh, custom custom linters for, for, uh, uh, projects because that's a whole, that's whole a whole other thing.

00:37:09.06
Steve McDougall
nice

00:37:13.97
Chris Morrell
Um,

00:37:14.21
Steve McDougall
Yeah, I worked on somewhere. I used to work at a Laravel partner. I was the engineering manager at JMP24, one of the UK partners, and they had like, they've got two or three different open source packages, solely focused to their coding standards.

00:37:22.98
Chris Morrell
Okay.

00:37:33.89
Chris Morrell
hu

00:37:33.88
Steve McDougall
Because you know in in that agency world where you jump in from project to project and you know when you're a Laravel partner, you've got a certain level of quality that you've got to keep. So like documenting and automating parts of that makes a lot of sense.

00:37:45.22
Chris Morrell
Yeah.

00:37:51.26
Steve McDougall
So yeah.

00:37:51.74
Chris Morrell
Yeah, for sure. And I mean, when you're working with other developers, um, You know, the last thing that I want to waste anyone's time with is like a code review. That's just like, Oh, this is fine, but it's not how we do it. You know, like, yeah.

00:38:09.39
Steve McDougall
Oh, that's not quite PSR 12, please change this.

00:38:14.26
Chris Morrell
Yeah. I mean, yeah.

00:38:14.71
Steve McDougall
Yeah.

00:38:17.49
Chris Morrell
Huh. So do you have, okay.

00:38:18.21
Steve McDougall
I'm a huge fan of like, but I use a PER standard, not PSR 12, newer version, but, you know, I'm a huge fan of tooling to achieve that. the a amount of time you in yeah my career where I've had PRs or could you add an extra space here or that should be on a new line or you know it's just like that's just wasted so long and as soon as you introduce like CI testing as well okay you're gonna

00:38:32.10
Chris Morrell
Yes, for sure.

00:38:50.87
Steve McDougall
make me waste 45 minutes potentially on a larger application for all the tests to run to make sure it passes but to then say, I prefer if you put if you, you know, wrote this statement, yeah, put this on a new line or something pretty ridiculous, you know, it starts to get a little bit crazy.

00:39:04.92
Chris Morrell
Put this on a new line.

00:39:11.25
Chris Morrell
Yeah.

00:39:17.13
Steve McDougall
and then your productivity dips and okay, I've managed to to yeah push code up four times today, but it's all been as ah for the same PR to try and appease some invisible standards that weren't documented or there's no automated testing.

00:39:17.91
Chris Morrell
so

00:39:34.20
Chris Morrell
Yeah, yeah, for sure.

00:39:35.55
Steve McDougall
I think everyone's felt that pain.

00:39:36.85
Chris Morrell
Um, I think everyone has, uh, you know, any, or anyone who's worked, you know, worked at a team with multiple people and, and, and and somebody has, has opinions, right?

00:39:46.78
Steve McDougall
Yes.

00:39:49.71
Chris Morrell
Which is, which is most places.

00:39:52.20
Steve McDougall
Yeah.

00:39:52.41
Chris Morrell
Um, uh, going back to the API stuff, I, I did wonder, um, you know, When, when you think about API design. Are there any, um you know, are there any hard and fast rules that you just always follow that you're just like, this is, this is something that I don't care what it is I'm building I don't care who it is it's going to use it. um This is how it's done.

00:40:23.07
Chris Morrell
and and And what comes to mind for me is things like versioning, authentication, standard response formats. I don't know if there's anything else like that.

00:40:33.21
Steve McDougall
yeah Yeah, I mean, I kind of have like a ah playbook, I guess. you know I don't actually version my APIs. um

00:40:42.87
Chris Morrell
Okay.

00:40:44.32
Steve McDougall
That's probably a whole other podcast episode. Something that I did version my APIs for such a long time and Phil Sturgeon kind of showed me the light of why I don't need to and now I don't.

00:40:59.06
Chris Morrell
Okay, I want to get back to that.

00:40:59.42
Steve McDougall
Well, I know that.

00:41:01.56
Chris Morrell
I'm i'm i'm very interested, but if you have other other things, let's we'll come back to it. I won't forget.

00:41:06.58
Steve McDougall
Yeah, no, I can drop you a link on that one. Phil Sturgenlotter blog ah for where I work about API versioning um and why you don't need it.

00:41:14.29
Chris Morrell
All right,

00:41:17.66
Steve McDougall
um The short version is that HTTP, um they've introduced new ah RFCs for things like the sunset headers.

00:41:19.94
Chris Morrell
what's the short ah short version?

00:41:32.01
Steve McDougall
So your tooling should be be able to pick that up these days so that you can mark an endpoint as deprecated or you can mark you know things as deprecating using HTTP headers.

00:41:33.00
Chris Morrell
Okay.

00:41:46.82
Chris Morrell
Interesting. How does that work on the consuming side?

00:41:53.33
Steve McDougall
um I suppose like if you're consuming an API,

00:42:02.52
Steve McDougall
I don't know. I'm assuming you need to be using some form of official SDK, really, the for the whole big picture to work nicely.

00:42:10.86
Chris Morrell
Mm hmm.

00:42:13.91
Steve McDougall
But if you're doing kind of a flame together integration, then I suppose monitoring is the only way to keep an eye on that.

00:42:25.30
Chris Morrell
Mm hmm. Yeah, it just, you know, I think there's there's two ends of the spectrum. There's like.

00:42:31.00
Steve McDougall
Yeah.

00:42:31.75
Chris Morrell
Uh, we're going to, we're going to improve our API and sunset features and you just have to get with it is one side.

00:42:39.85
Steve McDougall
Yeah.

00:42:41.32
Chris Morrell
And then there's like the Stripe side of we're going to support every version of our API that's ever existed for all of time.

00:42:47.42
Steve McDougall
Yeah.

00:42:49.97
Steve McDougall
Yeah, crazy.

00:42:50.40
Chris Morrell
And it's wild.

00:42:51.57
Steve McDougall
Absolutely crazy. but Okay, so I've actually got a question for you this time.

00:42:54.24
Chris Morrell
Yes.

00:42:57.02
Chris Morrell
Okay.

00:42:58.16
Steve McDougall
When's the last time that you built an API, versioned it and had to change the version? or do you always get a V1, stick on it until you make a mistake and go to V2?

00:43:11.87
Chris Morrell
ah Yeah, I mean, I think it tends to be, ah there's V1 and then at a certain point you need to change the shape of a request or a response significantly. So you copy the entire thing into V2 and make that change.

00:43:31.09
Steve McDougall
Yeah.

00:43:33.22
Chris Morrell
And then you get there and and a while later you need to change the shape of something again and you copy it all over to a V3. um you know In an ideal world, ah you know I would be using something that does some sort of schema transformation like like Stripe does where you can support everything with just the latest API.

00:43:52.17
Steve McDougall
Yeah.

00:43:56.10
Chris Morrell
That hasn't been the case. um you know But yeah we certainly have had to release new versions, but it usually is um you know it usually is exactly that. it's like um and And I say we copy everything over, we we don't, like it just falls falls through to whatever whatever is available whatever the most recent implementation that matches that version is. But we're on v3, v4 of a couple of the APIs that we publish for partners.

00:44:22.71
Steve McDougall
Yeah.

00:44:30.23
Chris Morrell
um And i you know I think for me, the value there is, um You know, the cost of integrating is not, it's not free. And if the existing API works for somebody, uh, but doesn't work for new use cases, as long as maintaining both of them isn't a huge, huge burden, I'd rather just offer both, you know.

00:44:57.46
Steve McDougall
Yeah, I definitely think there's something to be said about that transforming layer um and it's something that I've been toying with for a while is is building a package that allows me to do stripe style kind of versioning on the data so that I can transform

00:45:17.86
Chris Morrell
Yeah.

00:45:19.39
Steve McDougall
any data going out and coming in to kind of marked built versions. So I can say, okay, so version X is this and I just detect from the header and just pass it off to a package that just does it for me.

00:45:26.42
Chris Morrell
huh

00:45:36.66
Chris Morrell
Yeah, that would be very cool. We do a, we do a version of that for some internal data. you know, where giemas the schema has changed over time. um And, you know, essentially any time it's like these these objects are fetched from the database, we just look at what the schema version is and migrate it to the latest on the fly, rather than having to migrate that like migrate all the data at once.

00:46:01.91
Steve McDougall
Yeah.

00:46:06.80
Chris Morrell
um And you know for the most part, it's it's not that hard of a problem to solve. right You're essentially just passing it through like a middleware stack.

00:46:15.25
Steve McDougall
Yeah.

00:46:17.45
Chris Morrell
right um the only The only real challenge is effectively um you know you have to account for data b not existing, always, like forever.

00:46:18.49
Steve McDougall
Yeah.

00:46:31.81
Steve McDougall
yeah

00:46:32.41
Chris Morrell
In, in the implementation of your API, like you always have to account for, well, five years ago, this field did not exist. And therefore, even if the new API, like implementation requires it, if it's coming through the old version, there's still chances going to be null. ah And that's something to just wrap your head around, but I'm already kind of bought into that way of thinking because of ah dealing with event sourcing where you know essentially you're you're in a place where you're that data just exists as it existed at the time, and that's that's just the end of it.

00:46:52.84
Steve McDougall
Yeah.

00:47:04.92
Steve McDougall
Yeah.

00:47:13.50
Chris Morrell
So once you wrap your head around that, I don't think it's that hard. I think it'd be very cool for someone to have like a ah really solid, um you know, a solid system that felt like middleware that just worked really nicely with, with an all air valve application.

00:47:26.61
Steve McDougall
Yes.

00:47:30.72
Steve McDougall
Yeah, but the hardest part that I found is matching the developer experience to a point where it feels worth doing.

00:47:31.03
Chris Morrell
I encourage you to follow through.

00:47:39.94
Chris Morrell
Okay.

00:47:43.34
Chris Morrell
Uh, the developer experience in terms of the, the API developer or the, the like integration developer.

00:47:46.70
Steve McDougall
In terms of just.

00:47:49.87
Steve McDougall
Just Laravel in general, just when I'm building something with Laravel, my kind of a standard that I aim towards is that I want this to feel like it belongs as part of Laravel. So anything that I build as a package, like if it doesn't feel like Taylor or one of the team could have wrote it, then I've still got some work to do on that.

00:48:02.22
Chris Morrell
Yeah, for sure.

00:48:13.48
Chris Morrell
Sure. Yeah.

00:48:14.51
Steve McDougall
Probably an impossible standard to hold myself to, but it's one of those things that you just can't help sometimes.

00:48:20.93
Chris Morrell
Um, do you think, I mean, I can see two potential, um, like two potential approaches. One would, one would be, uh, essentially like migrations, right? You'd have a parent class that has an up and a down.

00:48:35.09
Steve McDougall
Yeah.

00:48:39.06
Chris Morrell
And the op just takes data in the format of the previous version and returns data in the format of that version.

00:48:39.29
Steve McDougall
yep Yeah.

00:48:47.21
Chris Morrell
um And down would be the opposite, right? Takes the response from the server in the current format and turns it into the response that would have existed for the prior format.

00:48:57.19
Steve McDougall
Yeah.

00:48:57.54
Chris Morrell
um Or there's the middleware approach where it's sort of a single, you know, a single object that receives the data and the the callable for what to do with it next. And then, you know, you have both sides of it in one implementation.

00:49:11.54
Steve McDougall
Yeah, exactly.

00:49:17.42
Chris Morrell
I don't know.

00:49:18.50
Steve McDougall
It's an interesting problem to solve and I don't know if there's a right or wrong way to to solve it, if I'm honest.

00:49:18.94
Chris Morrell
Do you?

00:49:25.46
Steve McDougall
I've been dabbling with it for about six or seven months and I've still not made up my mind.

00:49:25.62
Chris Morrell
Yeah.

00:49:30.33
Chris Morrell
Mm hmm. So if you were if you were to do versions, do you think that goes in the yeah URL? Do you think that goes in a header? Do you think that goes in a query parameter? Where do you think that belongs?

00:49:46.63
Steve McDougall
I think with...

00:49:50.88
Steve McDougall
If it's a REST API, I think it belongs in the yeah URL because the yeah URL is built up as RESTful resources. So you know you want to go to a specific version of it or yeah a sub-resource of a resource. Everything's kind of directed based on the URL path. So for versioning in a REST API, I think it belongs in that yeah URL.

00:50:20.67
Chris Morrell
And so do you think that that means that

00:50:25.06
Chris Morrell
that should that it shouldn't be transparent to the developer either. like Because I can imagine, you know I've tinkered with both versioning routes and doing like localization of routes where essentially um you know you introduce middleware that parses out that like first prefix of the path and then

00:50:50.18
Steve McDougall
Yeah.

00:50:51.51
Chris Morrell
uh, replaces it so that the rest of the application doesn't even see that there was like a V1 at the beginning or an EN-US s or whatever at the beginning. All it sees is the final, like the path that extends that. And there's some sort of global context that becomes available. That's like, this request is for, you know, Canadian, French Canadian, or this, this request is for version three, but that the routing kind of

00:51:17.65
Steve McDougall
Yeah. I like to be very direct with that. It's very it it a strong decision. yeah i In my code, yeah i will the namespace matches like the the URL path for a V3 or a V2, and then I have controllers

00:51:37.23
Chris Morrell
Mm hmm.

00:51:40.25
Steve McDougall
that are V3 controllers or controllers that would be a V2 controller, for example.

00:51:45.13
Chris Morrell
Mm hmm.

00:51:45.79
Steve McDougall
And it means that, yes, your application is kind of growing over time, but if you're kind of monitoring or and and observing your API, you know when you can duplicate things.

00:51:56.49
Chris Morrell
Sure. But I guess if there was some sort of layer that does this transformation for you, Effectively, your application no longer has to have an understanding of the version, right? It only cares about the latest the latest version and that transformation layer.

00:52:18.65
Steve McDougall
but Yeah, exactly. I only care about the latest version and I'll have some level of kind of... have some kind of, I suppose, request factory methods that will go, okay, so you're sending this to me in version 1.0.0 and I'm currently operating on 1.2.0, so I'm just gonna transform the data before passing it through the kind of validation, so it all happens in that middleware layer based off of that header.

00:52:48.21
Chris Morrell
Yeah. Yeah. And in that case, you think it would make sense for it to be a header.

00:52:53.91
Steve McDougall
Yeah, 100%.

00:52:56.47
Chris Morrell
Yeah, I can see that.

00:52:59.74
Chris Morrell
I can see that. And I think that's how, that's how Stripe does it.

00:53:04.74
Steve McDougall
Yeah.

00:53:04.92
Chris Morrell
Right. That's, it's all a header. Yeah.

00:53:06.80
Steve McDougall
Yeah, it all done through a header. And I believe Amazon, parts of Amazon do it, or at least their SDKs do.

00:53:16.04
Chris Morrell
Mm-hmm.

00:53:17.90
Steve McDougall
And some of the larger yeah larger organizations will do it that way.

00:53:22.53
Chris Morrell
Yeah. And do you, do you think the, uh, the like V one V two V three approach makes sense? Or do you think the, like, you know, both of those examples, stripe ended AWS. It's like the, you know, 20, 24 0 1 0 1 API or whatever, you know, it's, it's, it's paid into the date that it was released.

00:53:42.68
Steve McDougall
Yeah.

00:53:43.52
Chris Morrell
Um, do you have any preference there?

00:53:47.71
Steve McDougall
um

00:53:51.38
Steve McDougall
I don't think I've formed an opinion on that yet, to be honest. I think know it depends on the company itself.

00:53:57.63
Chris Morrell
Yeah.

00:54:04.64
Steve McDougall
like If it's a large company like Stripe, they're going to build up for a release candidate. So they're going to yeah have a version number based on that specific release. And a smaller company, that's yeah two or three developers, your release candidate is, I'm off tomorrow, so I'm going to release today.

00:54:15.80
Chris Morrell
yeah

00:54:24.00
Steve McDougall
you know There's no massive buildup, right?

00:54:28.47
Chris Morrell
Right. Yeah. I've always gone back and forth on it because I, I find that the, you know, the discoverability of the API versions when they're just a date is worse. Right.

00:54:46.64
Steve McDougall
Yeah.

00:54:47.40
Chris Morrell
Um, you know, we're, we're dealing with this right now with Stripe where it's like. You know, there's the version that we were working against and then there's the latest version. And it's just like understanding how big of a gap there is between the two of them is not obvious.

00:55:07.53
Steve McDougall
yeah

00:55:08.68
Chris Morrell
It's like, it are these one version apart and they just didn't release a new version for, you know, 14 months or whatever, or are there 30 versions between the two, you know?

00:55:16.52
Steve McDougall
yeah the date thing it's yeah the the date things never made sense to me i mean I get the approach, it's it's like their internal build number, so you know it was built of this date, so that's the version number, but you know I'd rather have to remember, okay, so I'm on build 1.23.45, okay, great, I know I'm on that one.

00:55:29.86
Chris Morrell
Yeah.

00:55:42.96
Steve McDougall
Instead of what date did I release that, it's a little bit easier to remember.

00:55:43.71
Chris Morrell
h

00:55:47.79
Chris Morrell
Right. Right. That's interesting. I i didn't even think of, uh, Yeah, you could you could essentially use like semantic versioning for your API version um because there are some changes that are purely additive that don't require, um you know don't that are aren't a breaking change.

00:56:01.66
Steve McDougall
Yeah.

00:56:12.34
Chris Morrell
They don't necessarily need a new new version release, but there's something interesting about saying, oh, this is a 1.2.5 release, you know?

00:56:13.40
Steve McDougall
yeah

00:56:20.36
Steve McDougall
Yeah. It's a minor fix to the API.

00:56:24.15
Chris Morrell
yeah Yeah, that's cool. I like that.

00:56:28.56
Chris Morrell
um so other yeah Other than versioning, or there are there other things that are just principles that apply to all API design that you've developed opinions about?

00:56:28.54
Steve McDougall
It's definitely something I've looked into.

00:56:42.71
Steve McDougall
Yeah, um all APIs should be authenticated in my eyes. um you know Even if it's a read-only public API, you still want to authenticate because you want to be able to yeah know block API tokens if there's abuse, or you want to be able to kind of track user behavior to see if anyone's exceeding terms and conditions.

00:57:06.19
Chris Morrell
hu

00:57:06.13
Steve McDougall
um Then, obviously, there's authorization on top of that, which is kind of like a no-brainer, I guess. pagination, 100% pagination on an API. um you know yeah yeah

00:57:19.60
Chris Morrell
And you think every response should be paginated, whether there's, you know, you always expect there to be.

00:57:20.27
Steve McDougall
and the

00:57:24.12
Steve McDougall
ah collection Collection responses only. um

00:57:28.89
Chris Morrell
Mm-hmm.

00:57:29.64
Steve McDougall
If it's like a collection response, like you're getting a list of objects, then you paginate it of why's don't. Because the problem with not doing it is, you know, if you're going to then adopt something like JSON API, for example, as a standard, and you want to be able to optionally include sub-resources, how far down the rabbit hole do you want to go? Because they could go seven levels deep on each relationship and You know, they, you know, originally your payload size was maybe 32 kilobytes.

00:58:05.21
Steve McDougall
You ah yeah you've included seven relationships and suddenly, you know, your payload's too large. You're getting the wrong response back from the server and things aren't working. ah Because a lot of the time people won't stream the response.

00:58:17.54
Chris Morrell
Sure.

00:58:19.96
Steve McDougall
They'll just but return the response and give it your back.

00:58:24.60
Chris Morrell
Right.

00:58:27.20
Chris Morrell
Yeah, I mean, that makes sense. It's like, um it it makes me think of the, you know, going back to GraphQL, if you're using Relay, the nodes and edges and cursors and all that stuff, like,

00:58:44.59
Steve McDougall
Yeah.

00:58:45.99
Chris Morrell
It does add a little bit more noise to an API when things are really simple. It's like, you know, I'm only ever going to get three of these back.

00:58:51.99
Steve McDougall
Yeah.

00:58:55.77
Chris Morrell
Why does it have to have all this pagination information? But being consistent from the get go with that, i I totally buy, you know, then you're never in a position where you have to change it down the road because suddenly there's more stuff than you expected.

00:58:59.33
Steve McDougall
Yeah.

00:59:08.88
Steve McDougall
yeah

00:59:12.16
Steve McDougall
Yeah, exactly. I mean, sometimes, depending on your API, you know just a simple limit and offset kind of pagination works.

00:59:22.14
Chris Morrell
Mm

00:59:22.38
Steve McDougall
Other times, you want cursor pagination. Other times, you just want page navigation. it yeah All of that depends on what API ah you're building, what the endpoints are, what's the purpose of them. and yeah yeah it It's what I call kind of like the API journey. you know You've got like user journeys on the front end, I think, heavily around kind of the API journeys. yeah What is the developer trying to do when they come to this endpoint?

00:59:48.42
Chris Morrell
hmm

00:59:50.27
Steve McDougall
How can I make their job easier? What can I give them? What can I also include so that we don't have to make subsequent requests? It's all very contextual at that point. um

01:00:00.67
Chris Morrell
So you don't you don't have like an opinion that it's just to always be cursor based so that that decision is just always made.

01:00:09.46
Steve McDougall
No, it massively depends on the purpose of your API, in my eyes.

01:00:14.39
Chris Morrell
Yeah.

01:00:16.04
Steve McDougall
Some some APIs will benefit from different different approaches depending on their need and the use case.

01:00:24.36
Chris Morrell
Yeah, for sure. So when you when you say often authentication and authorization,

01:00:25.99
Steve McDougall
um

01:00:30.69
Chris Morrell
Uh, do you think like OAuth is just always the way to go and token based, uh, permissions, uh,

01:00:38.55
Steve McDougall
No, I mean, i I'm, ah yeah, I'm still happy to throw a JWT token out. um But, you know, for me, if I'm building a Laravel API, I'll just go straight for Sanctum and I'm happy.

01:00:45.35
Chris Morrell
Okay.

01:00:53.78
Steve McDougall
There's time where I'll need to reach the OAuth, but not many.

01:00:58.60
Chris Morrell
okay

01:00:59.94
Steve McDougall
It's really not that many times. I mean, unless you need the full weight of what OAuth offers, simple API token auth through something like Laravel Sanctum is more than enough.

01:01:13.33
Chris Morrell
And Sanctum is just like a bearer token. Is that and all it is?

01:01:16.36
Steve McDougall
Yeah, it's basically is a little bit like JWT, but a bit better.

01:01:23.35
Chris Morrell
Okay. Interesting. That's interesting. Yeah. I would have thought, I mean, and and this, this speaks to my sort of, uh, lack of experience in this space. Cause I, you know, I just don't, I don't deal with API design very often or or consuming APIs. or building APIs that need to be consumed by other people. um So I would have just assumed that OAuth 2 was just like the standard now, but that's interesting that you say it's not. like

01:01:55.11
Steve McDougall
Yeah, it's like, I mean, we at Treble where I work, we know we've we've consumed yeah billions upon billions of API requests because we're an observability platform and yeah the vast majority aren't using any sort of OAuth.

01:02:14.00
Chris Morrell
Okay. Huh. Yeah, that's fascinating.

01:02:17.07
Steve McDougall
And ah Yeah, we we really we we released a really interesting report a few months ago. um The most popular day to send an API request is a Wednesday. And the most popular place to send an API request from is Richmond, Virginia. yeah

01:02:37.69
Chris Morrell
I guess is that where, uh, AWS us East one is, is that.

01:02:42.67
Steve McDougall
I'm assuming so, yeah.

01:02:44.88
Chris Morrell
That makes sense, right?

01:02:46.32
Steve McDougall
Yeah.

01:02:46.69
Chris Morrell
Yeah. That's funny. Yeah. I guess that's, that's just like, I would have never thought of that, but that's an interesting point. I betcha. Yeah. Where, where the, the major data centers are is going to drive so much of the, uh,

01:02:59.77
Steve McDougall
Yeah. Apparently people do a lot of data synchronization on Wednesdays from Virginia. That's all I know.

01:03:07.58
Chris Morrell
Right. That's so funny. Is there anything else that comes to mind, um, in terms of just like, you know, uh, things that you just always want to tick off the box, uh, when you're, when you're first implementing?

01:03:22.28
Steve McDougall
Yeah, cash, cash, cash, cash, cash, cash, everything.

01:03:24.53
Chris Morrell
Okay.

01:03:27.16
Steve McDougall
And I'm not talking about like throwing sparsely youth response cash because that's not always enough.

01:03:27.69
Chris Morrell
Okay.

01:03:32.81
Steve McDougall
You know, you want to cash, yeah, have a good cash strategy for the data and then add the correct cash headers. You know, is this public, is it driver?

01:03:43.89
Chris Morrell
Yeah.

01:03:45.02
Steve McDougall
What's the age of a cash? And, you know, adding an e-tag

01:03:48.14
Chris Morrell
Yep.

01:03:50.09
Steve McDougall
can yeah massively reduce that response time. um Also like idempotency, do you need it on your API? what's you know what's What is the kind of potential side effect of someone sending the API request twice? what What's, you know, is it going to, yeah it makes sense a lot in payments.

01:04:11.21
Chris Morrell
Sure.

01:04:15.06
Steve McDougall
You don't want to end up double paying for something, but in other implementations, does it make sense to also add it? Does it not? What's, you know, where's the right place to put that? And I suppose they're they're the things that I always consider when I'm building an API.

01:04:33.44
Chris Morrell
Yeah, I mean, getting caching right is, is such a hard, such a hard, hard thing.

01:04:37.97
Steve McDougall
Yeah.

01:04:39.42
Chris Morrell
And I, this is, this is a little bit of a pet peeve of mine. and I think, um, cash headers, uh, are just like such, I mean, I was going to say low hanging fruit, but it's not exactly low hanging fruit because. It should be simple, but it's not at all because, you know, the browser, the browser implementation of headers, of how caching is done has changed so much over the years that I feel like the resources out there for what, what the best practices are, um, are so inconsistent, you know, like what,

01:05:17.70
Steve McDougall
Yeah.

01:05:23.61
Chris Morrell
Do you use cache control? Do you use, um, you know, last modified if like, you know, all these different, you know, the pragma, no cache, all, all these different ways of telling the, the, either telling the server, this is what I'm looking for or telling the client, this is what I know about this thing.

01:05:32.63
Steve McDougall
yeah

01:05:45.64
Chris Morrell
You know, um, it's so tricky.

01:05:47.26
Steve McDougall
Yeah, the standards have changed so much over the years. I think there's definitely definitely space for some educational content around that. I think you've given me an idea of some content to write on my flight this weekend.

01:05:56.69
Chris Morrell
I agree.

01:06:00.75
Chris Morrell
There you go. Well, here, here I will say, um, the distinction between week, uh, you know, uh, what a week e-tag is. I think that that's like one of those things that, uh, you let alone just wrapping your head around e-tags and then it's like, oh, well, if you pass the e-tag incorrectly, like it might actually not be interpreted the way you intended, you know?

01:06:27.23
Steve McDougall
Yeah.

01:06:29.36
Chris Morrell
And then the other one that I think is is always interesting is like, you know, the shared headers versus the private headers, right? Like,

01:06:40.93
Steve McDougall
Yeah.

01:06:41.85
Chris Morrell
being able to tell intermittent like intermediate proxies one thing and tell the browser another thing. There's so much there.

01:06:47.97
Steve McDougall
Yeah.

01:06:50.16
Chris Morrell
Um, that can be really, really powerful and improve response times tremendously.

01:06:53.47
Steve McDougall
yeah

01:06:55.96
Steve McDougall
yeah but optimizing your API request says so much that you can do and yeah yeah you can

01:06:56.21
Chris Morrell
Um,

01:07:02.56
Chris Morrell
Yeah.

01:07:04.75
Steve McDougall
yeah configure your Cloudflare CDN, but then you can also configure your API itself. And then you could also configure, from my perspective, a JAMstack application. You could start to use like um cached requests on the front end. So there's so much you can do to squeeze out that extra performance.

01:07:28.95
Chris Morrell
hu Yeah, I mean, um and that's a whole other that's a whole other thing that you see pretty commonly on the, ah you know, SPA side is things like SWR, right, stale, wall, revalidate, or, you know, that there's that that same sort of, there's the the whole class of cache control headers around

01:07:44.54
Steve McDougall
Yeah.

01:07:55.30
Chris Morrell
you know What do you do if it's stale? What do you do if it's if the server is not responding? like Can you use and ah you know something that's expired if you can't talk to the server yet?

01:07:59.73
Steve McDougall
Yeah.

01:08:05.44
Chris Morrell
um

01:08:05.41
Steve McDougall
Yeah.

01:08:06.53
Chris Morrell
and that can

01:08:06.60
Steve McDougall
And again, all of that boils back down to context and purpose. know Is the experience of your application going to be massively impacted if the server goes offline? If it does, then do you want to go for that stale data?

01:08:25.56
Chris Morrell
Yep.

01:08:25.67
Steve McDougall
yeah Is something going potentially going to go wrong if they use that stale data?

01:08:26.47
Chris Morrell
Yeah.

01:08:29.80
Steve McDougall
yeah If you're building a to-do app, Yeah, definitely not. If you're building banking, then okay, you really need to be careful with that one.

01:08:39.03
Chris Morrell
Yeah. You need to understand, understand what the implications are.

01:08:42.35
Steve McDougall
Yeah.

01:08:43.59
Chris Morrell
Yeah. Yeah, I remember I went, I went deep down this rabbit hole at one point and I just, I just pulled up my notes cause I, there was one that I was curious about, which is the expires header versus the max age header. Um, I'm, I'm always like, which one is it?

01:08:57.68
Steve McDougall
Yeah.

01:09:03.67
Chris Morrell
And my note here says cash control max age is better that you should just always use that.

01:09:03.66
Steve McDougall
but Yeah.

01:09:10.66
Chris Morrell
But. I feel like I recently ran into something that was making the argument that the expires header was actually just easier to deal with. So it's it so it can be so frustrating.

01:09:20.47
Steve McDougall
i mean it If you're getting data from an API, you want to know how long that data is going to be valid for us so at some point. right Certain applications, it won't matter.

01:09:30.32
Chris Morrell
Yep.

01:09:32.43
Steve McDougall
A social API. Well, by the time you got your response back from a Twitter API, there's going to be 100 new tweets that you could fetch. But you know in your average business level application, how long is this data valid for that business?

01:09:42.88
Chris Morrell
Right.

01:09:53.18
Steve McDougall
you know How long do you want to be able to keep that and making decisions based on that context always makes sense?

01:10:02.08
Chris Morrell
So, um, do you think it makes sense to, to always, you know, run behind something like a cloud flare or, or, uh, some sort of HTTP cache CDN type service?

01:10:14.38
Steve McDougall
Yeah, 100%. I mean, always run behind yeah some level of kind of proxy of some description, whether that's Cloudflare or an API gateway, whatever it might be. you know it It adds layers layers on top of your API, which helps to protect your API from yeah potential DDoS attacks and potential kind of attackers to your API looking for vulnerabilities.

01:10:44.83
Chris Morrell
Sure. ah And like, do you think when you're talking about cash strategies, um, Do you, do you look at like explicit cache invalidation? Like, uh, you know, if you're, if you're behind a cloud flare, are you ever looking at, okay, you know, on my model saved event, I'm going to actually fire a cache invalidation request to cloud flare to tell it to like invalidate a certain cache.

01:11:18.43
Chris Morrell
Um, you know, even if the expires headers.

01:11:18.39
Steve McDougall
Yeah, I 100% look at doing that in certain situations. Like certain situations, it makes a lot of sense to do that. But yeah it sounds like a bit of a kind of crap answer, but it depends.

01:11:27.46
Chris Morrell
Yeah.

01:11:32.37
Steve McDougall
you know Business use case always dictates so many of the answers that we look for, um which is why we can never get the answers we actually want.

01:11:33.14
Chris Morrell
ah Sure.

01:11:39.24
Chris Morrell
Yeah.

01:11:42.70
Steve McDougall
But, you know, general good practice.

01:11:42.85
Chris Morrell
Right.

01:11:46.05
Steve McDougall
I'm going to cache as much as I can. And if I'm controlling cache through a proxy like Cloudflare, then I'm probably going to either, I know that x you know every six hours I need to invalidate cash because of this business rule, or I only need to invalidate cash when this happens, then I will trigger yeah know an API request or something off to Cloudflare to invalidate cash at certain points. Otherwise, yeah know Cloudflare, cash it until I tell you not to, basically.

01:12:15.22
Chris Morrell
Yeah.

01:12:22.59
Chris Morrell
Right. Yeah. I, I, I'm realizing that. I mean, I did a whole episode with, um, in landsmen about caching. And one of the things that we talked about that I, I still am finding myself really, uh, gravitating towards is just like.

01:12:45.66
Chris Morrell
cash aggressively and invalidate even more aggressively.

01:12:49.88
Steve McDougall
Yes.

01:12:50.10
Chris Morrell
you know like I think that there's a lot of cases where um you know I have definitely reached for just like, if anything changes, just just flush the whole cash.

01:12:51.04
Steve McDougall
Yeah.

01:13:03.54
Steve McDougall
Yeah. hundred so That's kind of my typical approach is, you know, in Laravel, for example, I'm going to get

01:13:04.69
Chris Morrell
and then

01:13:11.56
Steve McDougall
all of this data and I'm going to cache it every time. Don't care if I need to cache it or not, I'm going to cache it because it's going to speed it up. you know yeah A good API is going to respond fast, so the next person is going to have a faster response time. And then you know listen to those eloquent events and invalidate cache and have specific cache keys throughout your application. Typically, I maintain an enum in my variable application, which will have a list of cache keys. yeah I've got an enum for cache keys and I just select which one when i'm yeah when I'm working through it and then if I need to add a new one I add another case to my enum and then I set that through it and it just kind of keeps things organized but then I know I can okay to invalidate cache for this very specific thing.

01:13:42.43
Chris Morrell
Mm.

01:14:04.06
Steve McDougall
and then anyone else who's working with me, they know that there's this cache enum and they don't have to guess strings based on context. So, yeah.

01:14:12.99
Chris Morrell
Yeah. Um, when you're caching API responses, are you, are you caching sort of individual layers and then composing them together or caching the final response, right? Especially when you're talking about nested resources like, um, Okay.

01:14:28.89
Steve McDougall
hi

01:14:32.16
Steve McDougall
yeah so I will cache, typically I'll just cache like the result of a query. If I'm doing something like um something where I'm including sub-resources, I will build up that cache string based on the query.

01:14:51.53
Chris Morrell
Mm

01:14:53.52
Steve McDougall
So, you know, the chances of another person straight away requesting all projects including you know, the project owner and the project lead, you know, certain contexts, that's quite high. You know, I, I'm Jira, people are going to be requesting that a lot because I've got a really crazy ass interface that's going to send too many requests.

01:15:17.75
Chris Morrell
hmm.

01:15:22.04
Steve McDougall
So, you know, I can, you know, cache that quite, quite often. um Again, it depends, you know, if your application is one of these applications, that's a lot more kind of dynamic and fast, then you're going to want to have yeah really drilled down into those kind of potential cache keys and how you might name them. yeah Is it faster to cache that entire response or is it faster to cache part of the response and then kind of side load through a yeah the other parts in afterwards?

01:16:00.43
Steve McDougall
Do you want to look at something like a Vulkan by um the people behind API platform where you can actually send those resources after the fact, in which case you could cache them as well?

01:16:00.52
Chris Morrell
Mhm.

01:16:09.84
Chris Morrell
Mhm. Mhm.

01:16:13.13
Steve McDougall
you know, I can cache what they've asked for. I know what else they've asked for, but I can send that afterwards using um a, I think it's a 103 status. So it's like, um you also ask for this. Here you go. is I think it's early or something.

01:16:31.04
Chris Morrell
Okay. Yes.

01:16:32.97
Steve McDougall
ah

01:16:33.19
Chris Morrell
Yeah. Yeah. yeah

01:16:34.76
Steve McDougall
So, you know, Depending on what you're using and depending on your use case. There's so many ways you could be smart about caching your data Which is why it's always such a hard topic and anytime anyone asks me, you know What cache strategy would you take for this?

01:16:43.68
Chris Morrell
Yeah.

01:16:50.95
Steve McDougall
It's like well, it it depends, you know, what are you trying to do? What is your business goals? How often is this application used and you know, you can't just say Hmm, I know two weeks. There you go. Catch it for two weeks. You'll be fine. Yeah you Unfortunately, you can't do that.

01:17:06.77
Chris Morrell
This is the exact number of seconds that's correct.

01:17:09.47
Steve McDougall
Yeah, exactly. Let me just get on my calculator for you. ah you know Caching strategy is it's as unique as business offerings.

01:17:21.32
Chris Morrell
Sure.

01:17:21.40
Steve McDougall
know you You've got to kind of match it to what you're offering at some point.

01:17:28.62
Chris Morrell
Yeah. No, that makes sense. Um, in terms of the API response, it is it, I mean, is Jason schema or is that, yeah, Jason schema is just like the, the standard format everyone uses now.

01:17:43.01
Steve McDougall
So yeah ahja's Jason's schema is like a schema definition of what your response should look like. You're on about the Jason API specification, which is the format of the response. So you've got like um the the ID, the type, and the attributes, and the relationships all in a specific, this is how your response should look, fill in your data. um

01:18:10.55
Chris Morrell
Okay.

01:18:12.77
Steve McDougall
I sometimes use that. Other times, i more often, I actually lean on HAL, which is like a HAL, H-A-L, which is hypermedia.

01:18:20.64
Chris Morrell
On what hypertext application language.

01:18:25.68
Steve McDougall
I can never remember what it stands for. Every time I say it, I just think of, you know, that's the one. um Because for me, it feels like it leverages HTTP a little bit better.

01:18:33.81
Chris Morrell
Okay. I've never heard of this.

01:18:40.18
Steve McDougall
um But certain use cases, you want something like JSON-LD, or you might want yeah know JSON API spec. So again, something I spoke about at my Larracon talk was you know specifications. I think I spoke like 10 minutes about it.

01:18:57.59
Chris Morrell
Mm hmm.

01:18:59.38
Steve McDougall
It's like you know you could go for something like JSON API and 80% of you know scenarios that would be perfect but other situations this is better but as long as you're consistent the specification is a little bit like the single responsibility principle yes it's great in theory but it doesn't fit every scenario

01:19:25.12
Chris Morrell
Aha. Yeah, okay, that's interesting. I mean, i that this is another one where I would have just assumed that that one approach, one out.

01:19:34.26
Steve McDougall
No, it's more about consistent yeah consistency over which standard.

01:19:34.55
Chris Morrell
um

01:19:41.09
Steve McDougall
but If you're going to use a standard, embrace that standard.

01:19:41.50
Chris Morrell
Okay. So what's the, um what is it about how that speaks to you over the JSON a API spec?

01:19:56.42
Steve McDougall
um

01:19:59.85
Steve McDougall
I think I just like the way that you know you get embeds. I'm embedding, also embedding this object over, this is my object with its attributes. And it just kind of feels more tailored towards HTTP. I'm building a HTTP API. yeah know um I want to respond ah you know as hypertext. I don't want to respond as some kind of formed mess that's perfect for a specific React application. you know I want to respond in a specific way in a way that you know general HTTP tooling will kind of lean towards.

01:20:48.81
Chris Morrell
Interesting. Yeah. I'll have to look at it because I, you know, I'm, I'm not particularly, uh, I've never heard of it before. So, um, okay.

01:20:57.68
Steve McDougall
It's a lot more flexible than something like JSON API, but you know, it's also a bit older, but I do personally prefer it.

01:21:09.91
Chris Morrell
Um, it's funny because I, so I feel like this dates me, but I, I.

01:21:20.78
Chris Morrell
we We have a standard API response at an Apache and it includes the HTTP status code because i remember ah I remember a time when you weren't necessarily guaranteed at the JavaScript side to always get the HTTP response code in your response.

01:21:24.05
Steve McDougall
Yeah.

01:21:29.05
Steve McDougall
Yeah.

01:21:41.92
Steve McDougall
Yeah. I remember those days.

01:21:43.65
Chris Morrell
um

01:21:46.45
Chris Morrell
And I assume that that is not an issue anymore and that's not common practice, but.

01:21:49.15
Steve McDougall
No.

01:21:52.16
Chris Morrell
um Yeah.

01:21:52.37
Steve McDougall
Now, I mean, I still see ah so many APIs passing back the status code as part of the request body. um Personally, I can't stand it. And I know that we do it at Treble with some of our APIs.

01:22:06.00
Chris Morrell
Mm hmm.

01:22:06.26
Steve McDougall
um But I'm not in the engineering team. So I, you know, there's only so picky it can be. um But yeah yeah, you don't need to repeat yourself.

01:22:19.22
Chris Morrell
Right.

01:22:19.78
Steve McDougall
know

01:22:20.05
Chris Morrell
Right. You've already returned the status.

01:22:20.30
Steve McDougall
okay Yeah, exactly. Oh, okay. If we're going to go that far, we may as well also, you know, say, oh, this is actually Jason that you're consuming. And, oh, it's also UTF-8. You know, how, how far down the line do you want to go?

01:22:32.92
Chris Morrell
Yeah.

01:22:34.25
Steve McDougall
Do you want to repeat all of our headers in the payload as well?

01:22:37.66
Chris Morrell
Yeah. Yeah. I get that. I mean, I don't know that. That I feel less strongly about. i do The other thing that we have in all of in all of our standard responses is um every response has an okay root level property that's just true false.

01:22:55.04
Steve McDougall
Yeah.

01:22:57.41
Chris Morrell
And um i I love it because it's just like, no matter what you're doing, you always just have one very terse quick way to see like, is this a good outcome or a bad outcome?

01:23:03.09
Steve McDougall
yeah

01:23:08.82
Steve McDougall
Yeah.

01:23:11.71
Chris Morrell
you know

01:23:12.09
Steve McDougall
I suppose, but I mean, the status code will tell you that a lot of the time, but I do get it.

01:23:17.07
Chris Morrell
Oh, sure it will.

01:23:17.64
Steve McDougall
I mean, I'm speaking from a kind of, I spend more time building when consuming APIs.

01:23:22.35
Chris Morrell
Mm hmm.

01:23:22.60
Steve McDougall
So, you know, I'm going to have a slightly different opinion to someone who spends more time integrating with APIs.

01:23:29.85
Chris Morrell
Sure.

01:23:29.98
Steve McDougall
But to me and my brain, you know, I've given you the status code.

01:23:34.72
Chris Morrell
Yeah.

01:23:34.88
Steve McDougall
No, I have given you a 202 or a 201. You know what that means. Let's carry on. um

01:23:41.83
Chris Morrell
Right.

01:23:42.80
Steve McDougall
but you know I suppose as someone who's more back-end engineer everything to me is a little bit more binary.

01:23:53.23
Chris Morrell
Sure.

01:23:53.75
Steve McDougall
you know is very much kind of, yeah, it's a 201, you're fine, or 202, we'll deal with it later. um it's you know my I'm very specific in my API for status codes, like if I've created the object, yeah I'll send the created response back. If I haven't created the object, but I dispatched a background job, That could fail, but that's outside of the remit of that request response lifecycle because it's stateless.

01:24:23.78
Steve McDougall
So I'll i'll tell you that I've accepted your request. I haven't created your resource because it's not in the database yet. If you instantly send another request, you're going to get a 404. So have a 202.

01:24:35.85
Chris Morrell
Right.

01:24:37.69
Steve McDougall
I will create it, depending on how busy the queue is. you know

01:24:41.77
Chris Morrell
Right.

01:24:44.76
Chris Morrell
Yeah. That, I mean, I, I fundamentally agree with that. I think, um, you know, in my. Uh, in my day to day, there's really only, I mean, honestly, there's really only three status codes for status codes that I ultimately ever really use. Um, you know, that's not true when I'm getting.

01:25:07.23
Steve McDougall
Let's see if I can guess them. 200.

01:25:11.10
Chris Morrell
Yeah.

01:25:11.87
Steve McDougall
201.

01:25:13.98
Chris Morrell
Nope.

01:25:16.85
Steve McDougall
You send a 200 on a create response. Damn it. Okay, so 200. I'm going to say that there is also 401 and 403.

01:25:31.05
Chris Morrell
That's true. You know what? You're right. Those are two others. Yep. I mean, yep. You're, you, you've skipped, you've skipped two, but.

01:25:39.80
Steve McDougall
422 I'd say you probably return that from the validation and processable entity and possibly a 400 for a bad request or worst case you'll do a 405 because you know if someone's trying to request something from you know a get request from a post endpoint but you know framework yeah

01:25:46.64
Chris Morrell
Hmm.

01:26:00.91
Chris Morrell
Right. Well, the, the API will, I mean, the, the framework will do that for you.

01:26:05.31
Steve McDougall
yeah

01:26:06.15
Chris Morrell
Right. And that's, true I mean, yeah, the the framework will do. A lot of the 400 level responses kind of on your behalf.

01:26:13.93
Steve McDougall
Yeah.

01:26:15.94
Chris Morrell
So those are ones that I don't necessarily think about, you know, I was going to say 200 301, three or one three two and four or four. Those are the, those are the response codes that like. I would say a typical backend Laravel app, because even even on a you know ah create request to a Laravel app, that's usually gonna result in a 302 response ah redirect to the created resource.

01:26:31.48
Steve McDougall
yeah

01:26:41.25
Steve McDougall
Yeah, I mean, you It will probably redirect if it's say yeah a web app, not a web API.

01:26:48.06
Chris Morrell
Yeah, so like 201, you know,

01:26:52.01
Steve McDougall
Yeah.

01:26:52.65
Chris Morrell
Maybe if you had pressed me, I would have been able to tell you what that was, but I don't know that I would, uh, you know, I just, I, I very rarely have to think in and status codes other than, is this a permanent or non-permanent redirect?

01:27:02.63
Steve McDougall
Yeah.

01:27:07.12
Chris Morrell
You know, that's like the the thing, the only status code that I really think about.

01:27:07.40
Steve McDougall
yeah yeah Yeah, one of my open source packages is basically just a really big PHP enum with all the different status codes. um which you know

01:27:20.13
Chris Morrell
Like with their names.

01:27:21.84
Steve McDougall
Yeah, literally with their names. And I've also added doc blocks with like links to the references of them in, that I think it was in the Mozilla docs. it' like So if you want to know about this, you can click yeah you can literally, from your IDE, click through and click through to the Mozilla docs based on what response code you're giving back in your controller.

01:27:32.74
Chris Morrell
Mm-hmm.

01:27:44.19
Chris Morrell
That's pretty cool. That's pretty cool. that's those are I mean, I think that all of those are constants on the response object in Laravel 2, but I don't know if they have references to the docs. They probably don't.

01:27:57.30
Steve McDougall
They are, I mean, they they kind of extend the symphony response, so they they are part of a symphony response. They are constants on there, and I believe it does have most, if not all of them, and I'm not 100% sure if they've got dog links.

01:28:07.74
Chris Morrell
Yeah.

01:28:15.76
Steve McDougall
um I built it because yeah I also use it in some of my other packages which are outside of the framework, like my PHP SDK library, um which is like a ah framework for building SDKs in PHP.

01:28:16.14
Chris Morrell
yeah

01:28:31.16
Chris Morrell
Oh, interesting.

01:28:32.21
Steve McDougall
Having status codes within there is great, but I'm not pulling in symphony, I'm not pulling in Laravel stuff, so I needed a way to be able to kind of use that where I need it.

01:28:43.01
Chris Morrell
Mm-hmm. That's such an interesting, that's such an interesting space. That's, it's the type of thing that, um, feels like it should be solvable, but I'm not certain that it is the, like, is there a way to provide like generic SDK tooling for just anybody?

01:29:06.42
Steve McDougall
Yes, I solved that.

01:29:08.33
Chris Morrell
Hmm.

01:29:09.81
Steve McDougall
I created a package for that.

01:29:09.88
Chris Morrell
Sure he did. as As has everyone else though.

01:29:12.59
Steve McDougall
i

01:29:15.22
Steve McDougall
Exactly. um Everybody solved it. What are you on about? Now, I found a way that works for me. um And it kind of leverages PSRs and you know RESTful standards, basically, is the idea behind it.

01:29:33.28
Chris Morrell
You see, that's the problem though, is in my experience, you know, as a, as a primarily backend developer, I can tell you immediately with absolute certainty, is this SDK Taylor made, or is it built on top of something else that's file that's just like following some sort of standard because like.

01:30:00.13
Chris Morrell
When I'm consuming an SDK, I want it to feel perfectly fluent and absolutely tailored to the domain of the the thing that I'm working with.

01:30:08.23
Steve McDougall
Yeah.

01:30:12.65
Chris Morrell
I don't want to be thinking in, you know, HTTP verbs or, you know, cruddy terms.

01:30:12.70
Steve McDougall
Yeah. Yeah.

01:30:18.71
Chris Morrell
I want to just say, do the thing that this does.

01:30:19.45
Steve McDougall
Yeah. yeah

01:30:22.33
Chris Morrell
You know what I mean?

01:30:23.40
Steve McDougall
And that's what I aimed for with my kind of SDK package was that yeah I basically just wrapped up for a whole kind of transport and building layer.

01:30:23.82
Chris Morrell
And like.

01:30:35.81
Steve McDougall
And then yeah I basically give abstract classes and traits and say, OK, build your SDK like that, include the traits where you need them, and build the API you need with this set of tools.

01:30:48.71
Chris Morrell
Mm hmm.

01:30:49.49
Steve McDougall
for your package and your SDK. And for me, it's worked. um I've used it in several places. I've built the Laravel and Voyager PHP SDK with it, and it seems to be working OK.

01:31:02.41
Chris Morrell
Mm hmm.

01:31:04.52
Steve McDougall
I haven't had any complaints, and it's got like 78,000 downloads. So I must have done something, right? Either that or it was downloaded a lot and never used.

01:31:13.20
Chris Morrell
Sure.

01:31:15.01
Steve McDougall
yeah know Stats are stats.

01:31:19.51
Chris Morrell
Yeah. I mean, I, I, I'm going to take a look because I, I constantly think like, you know, it it feels like this should be a solved problem, but every time I go about it, you know, I was just recently, I i recently was tinkering with, um, building a linear SDK for PHP, because there really isn't.

01:31:46.15
Steve McDougall
Nice.

01:31:46.88
Chris Morrell
there's um There are a couple attempts, but none of them feel great to me.

01:31:52.75
Steve McDougall
Isn't it a GraphQL API as well?

01:31:55.52
Chris Morrell
It is a GraphQL API. which yeah Well, i'll I'll send you the link afterwards.

01:31:56.67
Steve McDougall
That's what stopped me doing it, I think, because I use linear a lot as well.

01:32:03.79
Chris Morrell
It's an interesting project. um

01:32:05.72
Steve McDougall
Nice. Yeah, I'll definitely check it out.

01:32:07.14
Chris Morrell
talk, I mean, talk about the the the one upside of GraphQL in this, in this use case, is um it's very the spec, I mean, the the um introspection stuff. gives you a lot of flexibility.

01:32:25.85
Steve McDougall
Yeah.

01:32:25.93
Chris Morrell
And so um in the case of Linear's API, I was able to do kind of this crazy transformation where I parse the GraphQL, um the like the GraphQL file from Linear.

01:32:41.81
Steve McDougall
Yeah.

01:32:42.05
Chris Morrell
into an AST and then I transform the AST from this the GraphQL tree to a PHP parser tree so that and then render those that AST to code.

01:32:45.02
Steve McDougall
Yeah.

01:32:55.21
Steve McDougall
yeah

01:33:00.36
Chris Morrell
So ultimately, you know in a single execution, I am able to auto generate um classes that exist for every single entity in the the linear API, um you know, with full 100% type coverage, you know.

01:33:13.47
Steve McDougall
Yeah. See, that stuff is cool. I mean, you could do the same with an open API spec, though, in in reality. And, you know, people do do it, but it's not as easy.

01:33:27.22
Chris Morrell
Yeah, I mean, if there's a good, if there's a really good open API parser that gives you a, you know, something to walk a tree to walk. Um, but I definitely know, I mean, I'm trying to think of.

01:33:37.85
Steve McDougall
Yeah.

01:33:42.90
Chris Morrell
There are a couple of SDKs that I use that like, you know, you know that they're auto-generated from it a spec file somewhere and it feels like it, you know, you you open up, you go into the code and everything is just like, huh?

01:33:51.29
Steve McDougall
Yeah. Yeah.

01:33:56.46
Steve McDougall
Twilio is a perfect example.

01:34:00.59
Steve McDougall
Twilio was a perfect example, yeah.

01:34:00.95
Chris Morrell
Twilio? Yeah. That, that makes sense. Yeah. i'm I'm blanking out on the one that there's one that I deal with all the time that every time I source dive, I'm just like, ah, None of this means anything, you know?

01:34:12.94
Steve McDougall
Yeah.

01:34:14.75
Chris Morrell
there It's all...

01:34:15.44
Steve McDougall
This was released last week and it's using PHP 4 features. What's going on?

01:34:20.14
Chris Morrell
ah Right, exactly.

01:34:21.16
Steve McDougall
Yeah.

01:34:22.04
Chris Morrell
Yeah. But it's an interesting space. It's an interesting space.

01:34:27.11
Steve McDougall
Oh, definitely.

01:34:28.01
Chris Morrell
All right, what's...

01:34:28.53
Steve McDougall
I do some freelance work for a company called SpeakEasy who do SDK generation.

01:34:28.79
Chris Morrell
yeah Okay.

01:34:35.30
Steve McDougall
And the way they've approached it is they've basically built like and an AST template engine for each language that they generate to so that they'll pass an open API spec.

01:34:47.70
Chris Morrell
Okay.

01:34:49.83
Steve McDougall
and then they'll build out an SDK based on the template and that template can change.

01:34:52.89
Chris Morrell
Mm

01:34:55.29
Steve McDougall
So something new gets introduced or they find a better way to do something, they'll build out it build it out slightly differently.

01:34:56.09
Chris Morrell
-hmm.

01:35:02.99
Steve McDougall
um I've done some consulting on how their PHP generation should work and that sort of stuff and their SDKs are the better of the generated ones I've seen.

01:35:15.44
Chris Morrell
ahha Yeah, I mean, it's, it's definitely, it's definitely a ah balance because, you know, if you don't have unlimited money and you want to provide an SDK for a bunch of different languages, you have to, you know, you have to accept.

01:35:29.73
Steve McDougall
Yeah.

01:35:31.03
Chris Morrell
You have to accept it.

01:35:31.27
Steve McDougall
Yeah.

01:35:31.95
Chris Morrell
So, you know, I'm not, I'm not knocking companies for doing it.

01:35:34.81
Steve McDougall
100%.

01:35:35.73
Chris Morrell
I, I do think that the big companies Twilio could afford to have a sick, just a sole PHP developer working on their SDK.

01:35:37.66
Steve McDougall
Yeah.

01:35:43.08
Steve McDougall
yeah

01:35:43.24
Chris Morrell
Um, and it'd probably be better than the auto-generated BS, right?

01:35:46.16
Steve McDougall
Yeah, 100%. Yeah. I mean, if I had to write a Java SDK or, you know, dot .NET Core SDK, then, you know, I'd probably think about a different line of work. So, yeah, but there's times when auto generation makes sense.

01:36:04.93
Chris Morrell
Right.

01:36:07.33
Chris Morrell
Yeah, for sure. Yeah. I know something, um, uh, that team, uh, do you know, Daniel Colburn at all or, um, I know Daniel and thunk, one of the things that they have been doing is, um, you know, trying to work with, uh, you know, medium sized groups to, to provide just like, we'll, we'll make.

01:36:16.13
Steve McDougall
Yeah.

01:36:33.73
Steve McDougall
yeah

01:36:34.12
Chris Morrell
just an exceptional Laravel SDK for your product. You know what I mean? And I think that's a really interesting space.

01:36:39.39
Steve McDougall
Yeah.

01:36:41.14
Chris Morrell
Like there's so many places where, um, yeah, it's just like, if you don't understand the ecosystem, you're gonna, you're not going to get it right.

01:36:52.35
Steve McDougall
Yeah.

01:36:54.30
Chris Morrell
You know?

01:36:54.64
Steve McDougall
yeah

01:36:54.98
Chris Morrell
So just having someone within that space, write the code, um, makes such a big difference.

01:37:01.01
Steve McDougall
Yeah I mean especially from a developer experience perspective and I had a really good chat with a head of developer experience at Paddle not that long ago and you know the amount of effort they put into you know handwriting their SDKs off of a set of practices and principles is you know it's really at admirable companies will still do that.

01:37:25.70
Chris Morrell
Yeah, for sure. All right. Uh, we've been going for a long time. I have one last question for you, which is, you know, how often do you use the four 18 response code?

01:37:37.72
Steve McDougall
I use it so much, actually. ah ah Yeah.

01:37:40.42
Chris Morrell
Do you?

01:37:43.65
Steve McDougall
i I do it for fun. um You know, if it's like a, I'm not sure what I should respond here, then 4-1-8.

01:37:55.35
Chris Morrell
might might as might as well be a teapot.

01:37:57.81
Steve McDougall
Exactly. if youre If you're not sure, and if all else fails, a teapot will save the day, you're returning something.

01:38:03.16
Chris Morrell
I love that. I love that. um So is there, ah you know, I guess ah let's let's close out with the the the standard, how do folks find you on the internet?

01:38:07.15
Steve McDougall
Definitely.

01:38:15.53
Chris Morrell
Where's the best best place to ah get connected with you?

01:38:19.81
Steve McDougall
I am, you know, Twitter, X, whatever Elon's gonna call it next. I'm, you know, at Just Steve King. Same on GitHub, same on Mastodon, same on Blue Sky, Threads, so all the places I'm at Just Steve King, so.

01:38:39.75
Chris Morrell
Okay. And is there, uh, anything that you've got going on right now that you'd like to plug any particular thing that you're working on for people to check out or Oh, wow.

01:38:45.23
Steve McDougall
So much.

01:38:48.07
Steve McDougall
so much. i I mean I'm doing so much through work at the moment and um next week I'm actually in Croatia for the whole week recording a Laravel API video course.

01:39:02.68
Chris Morrell
Well, there you go.

01:39:02.80
Steve McDougall
um I've been meaning to do it for years and I've been saying I'll do it for years. I finally put a date on it and said I'm going to do it within this window and work our Flyme out to the office in Croatia they're setting up the recording studio and they're literally going to spend the week with me recording this video course and it's going to be free so it's yeah it's it's completely free I think yeah it's going to be behind some sort of sign up thing so you can track your progress but nice free API video course

01:39:26.83
Chris Morrell
That's very cool. That's awesome.

01:39:39.48
Chris Morrell
Okay. Uh, where, where will folks go to find that? Or is there some place to sign up for updates or anything like that yet?

01:39:47.12
Steve McDougall
I haven't gotten that bit built yet. I've been too busy. I like decided I was going to do it two weeks ago. um Yeah.

01:39:56.25
Chris Morrell
Oh, wow.

01:39:58.48
Steve McDougall
I mean, I've been planning it for years, but I only kind of decided to pull the trigger on it like two weeks ago. So I still need to get a website and all that up for it.

01:40:05.09
Chris Morrell
Okay.

01:40:07.40
Steve McDougall
But if you keep an eye on the Treble Twitter, which is Treble API, all one word, ah

01:40:15.84
Chris Morrell
Okay. How do you spell that?

01:40:16.66
Steve McDougall
will that will be t r e b l l e i'll drop it in the chat it's it's a funny spelling um yeah it's um it'll be announced through there yeah obviously i'll talk about it on twitter but if you don't want to follow me then just keep an eye on

01:40:22.71
Chris Morrell
Okay.

01:40:28.11
Chris Morrell
Sure. I, I'll include in the show notes for sure. Yeah. Okay. And I assume you'll talk about it on Twitter as well. So.

01:40:41.69
Steve McDougall
that twitter

01:40:43.28
Chris Morrell
Okay. And you do, you do a lot of YouTube live streaming too, right?

01:40:47.21
Steve McDougall
Yeah, I tried to live stream at least once or twice a week. ah More recently, I've been doing kind of three times a week for two hours at a time.

01:40:51.42
Chris Morrell
Okay.

01:40:56.23
Chris Morrell
Wow. Okay. So that's another, another place to check out and i'll I'll throw that in the show notes as well.

01:40:59.62
Steve McDougall
Yeah.

01:41:01.37
Chris Morrell
Awesome.

01:41:01.36
Steve McDougall
Thank you.

01:41:02.35
Chris Morrell
Well, thanks so much for joining. And, uh, yeah, I'm, I'm, I'm interested.

01:41:05.77
Steve McDougall
Thanks for having me.

01:41:09.44
Chris Morrell
I'm going to keep a eye out for this API course, because it's definitely one of those things, even though I don't have to do it that often. Um, I often wonder about, about some of those best practices. So that sounds really interesting.

01:41:22.48
Steve McDougall
Yeah. If you haven't done it in a while, it's nice to refresh your memory on it. And if you do it often, it's nice just to kind of see how other people approach it in case there's a different way. And, you know, low barrier of entry, all we're going to require is a way to sign up, no cost.

01:41:32.74
Chris Morrell
For sure.

01:41:40.53
Steve McDougall
So no matter where you're from, no matter what your budget is, you'll be able to learn.

01:41:45.78
Chris Morrell
Awesome. All right. Well, thanks again. Until next time.

01:41:50.10
Steve McDougall
Thank you very much.