Coding Blocks - Write Great APIs

Episode Date: April 26, 2021

We discuss all things APIs: what makes them great, what makes them bad, and what we might like to see in them while Michael plays a lawyer on channel 46, Allen doesn't know his favorite part of the show, and Joe definitely pays attention to the tips of the week.

You're listening to Coding Box, episode 157. Subscribe to us on iTunes, Spotify, wherever you like to find your podcasts. We are maybe there, probably there, kind of, sort of, I don't know. If we're not, let us know, we'll figure it out. Yeah, something.net. And we got a website at codingblocks.net where you can find show notes, examples, discussion, and things like links to podcasting places.

We're trying to make it easy for you, and you can send your feedback, questions, rants, too. Comments at codingblocks.net. Hey, be sure to follow us at Twitter at CodingBlocks or head to www.codingblocks.net and find all our social links there at the top of the page. And with that, I am Alan Underwood. I'm Joe Zach. And I'm done. This episode is sponsored by Datadog, the cloud scale monitoring and analytics platform for

end-to-end visibility into modern applications. All right, and today we're talking about writing great APIs, and we'll get to that. But first, we got a little bit of news. Yep. So we got a review at iTunes from HHSkakeIDMD, something like that. Thank you. Okay. I was curious to see, like, I purposely gave you that one because i'm like alan's usually

pretty good at pronouncing these things i want to see what he comes up with for this one because i looked at that one and i'm like no i would i would i don't think i would do it as good as you did so you know hey good for you sir i appreciate that um and Audible, we had a new review from Colm Ferry. So, and I recognized his name from Twitch when we were doing the game jam. Oh, excellent. Awesome. You know, Colm, I saw a tweet of his recently. He's working on a game in PixieJS.

It looks amazing. I'm so jealous. I want to be working on that. So, yeah. Well, which reminds me, you know, we talked about doing something else. We did the game January back in January.

And we talked about maybe doing something else. So, you know, if we were to go for, say, two a year, that would put us around July. And we haven't really talked about what that might be. So if you have ideas, then leave comments and tweet or whatever. Because we're going to need to start thinking about it pretty soon. I thought we did talk about that last episode and we decided that it was going to be based around the theme was going to be sprints.

And I was just going to like retheme my closing tickets to be closing sprints or story points or something. That sounds like a lot of fun. Okay. No, sure. Yeah. Please define fun for somebody. How about we define APIs? Oh,

Hey, when you ask you a stupid question, you get a stupid antsy. So thank you. Casper's. I like it. Nice. We're off to a good start. So thank you, Kaspers. I like it. We're off to a good start, so let's do this. Alright, so APIs. We had the idea to talk about

APIs and basically writing really good APIs, because if you're a back-end developer, you're probably writing a lot of APIs. If you're a front-end developer, you're probably also writing APIs and you're probably also consuming a lot of APIs. In fact, it's pretty hard to do any sort of coding without consuming a ton of APIs. So I thought it might be fun to take a look at some tips for writing good ones. Because a lot of times, people don't even realize or

don't think about themselves as being API authors. We're going to fix that today. I like it. So a definition on Wikipedia, which we'll have a link to, of course, is application programming interface. It's a formal way for applications to speak to each other. Back when I first heard this term, public was in there. They used to say application public interface. So that was kind of interesting that it's changed. I don't really know why. I don't remember it being public though but

yeah me neither maybe i got that one wrong on my multiple choice question in college mnemonic if you remember if you know why let us know in the comments uh so apis define requests uh or actions that you can make what you need to provide in terms of arguments and what you get back in terms of responses. And if you do any Googling, then you are going to see a ton of articles about web APIs, very specifically rest and i thought that was really interesting to see that the word api has kind of taken such a strong meaning there because it really doesn't mean web apis it doesn't mean rest it's much more general than that and so we've got a list here of different types of apis that you have surely interacted with if you've been programming but you may not have thought of being apis i don't know somebody else wants to go for that so real quick on that though and we interacted with if you've been programming, but you may not have thought of being APIs.

I don't know if somebody else wants to go for that. So real quick on that though, and we moved this around on the show notes, I'll shift it back up in a minute. But to that point, you hear API and a lot of people think, you know, web requests or whatever, but a very popular or very big one, I should say, that's available out there that has nothing to do with HTTP at all is the Linux kernel. And I have a link down here and they've got tons of APIs for all kinds of things in their system interrupts, you know, just tons of garbage. So yeah, APIs are just, if you want to call something programmatically, this is your contract to do it.

Yeah, and really, if someone has published something that you can use to call their code, we're calling an API here. So that's just about all code you're going to be interacting with unless you're doing some spidering or you're hacking around some stuff in, I don't know, the Game Genie or whatever. Then you're probably going through an API. And so one example here might be every single library ever and every single framework ever. Yeah. So the.NET framework, you know, that library, those set of classes, that's a version of an API. So there's the Windows API that you could program against. So if you wanted to create an application and get events from the operating system as things happen, right, like you're using some Windows API to make that happen. Oh, that reminds me. You remember when.NET was making that transition from the.NET framework to core and all that?

There was the.NET framework to core and all that, there was the.NET standard library. All that thing was, was a standard set of APIs for things to be able to interface with so that, you know, you could write it for Linux or Mac or Windows or whatever, and it would work. So as long as you adhered to that standard set of APIs, then your stuff could run cross platform. Yeah.

And speaking, I mean, you already mentioned that Windows API, so things that Windows can do. Remote APIs is basically just remote actions that you can take that's kind of an older way of doing things. SFTP, it's kind of a fun one. If you've ever done anything like that, you go in, you open, you send some stuff, you get some stuff back, that's an example of an api um web of course is in there so we mentioned that so rest but also soap uh if you're doing how do you os or however you say it um very strict uh rest uh and graphql also is another another api that you might interact with or rather it's rather it's a type of APIs, many, many, many GraphQL APIs out

there. Domain-specific languages, so like SQL, that is an API. Literally, it's a way that you communicate with someone else's program in order to effect changes. So the formal definition of APIs and who owns them and what can be copyright copyrighted whatever is really complicated and it's still kind of being defined uh you know google and oracle just had a major core case that's been going on for the last like i don't know 20 years or something about the android api and the different uh java calls that google kind of emulated in order to behave like uh java and be able to say that you worked in Java on their platform. You know, that was a, that caused a big stink.

And so the definition is still kind of a flux, but just want to kind of emphasize that when we're talking about APIs in this episode, we are talking about the ways that people interact with your code, how they make your code do stuff. By the way, that Google lawsuit you're referring to, didn't that just end?

They won? Did it wrap up? It did wrap up. And it's been appealed several times. So I think this is the final one. I don't know about a final appeal. I'm not a lawyer. So I play one on TV, though.

So you can check me out, Channel 46, on your local. I know. It's been like somebody won several years ago so this is definitely not the first time this has been declared over but it may be the last maybe i put i put something in here too because you had like remote api but um i think you know unless you correct me if i'm wrong but uh more commonly you might hear that referred to as rpc so yes um also uh remoting so if you're um sometimes this is less common but um you used to be able to kind of do weird stuff like um kind of almost like p invoking or whatever to kind of calling things remotely either on your

system or otherwise where you're kind of like marshalling commands in and out and like p invoking or whatever um so i meant very just like just communicating you're kind of like marshalling commands in and out and like P invoking or whatever. Um, so I meant very, just like just communicating over socket kind of, but yeah, GRPC is like the way you do that now and it's much better. Yeah. So RPC would be remote procedure call. Yep. Just to be clear. And GRPC somehow brought that back.

I thought, I thought that was just done. But it turns out they're good things. You know what's funny about the gRPC thing is I know it came out of Google, and I always assumed it meant Google, but it doesn't. Like a lot of people say that the G has changed meanings as it's been versioned, but at one point it was like geeky RPC. So the thing, yeah, it's,

it's weird, but apparently the G does not represent Google, which sort of makes a little bit more sense because it's a lowercase G, but yeah, I don't know. It's like every version of they changed the meaning of the G. Yeah. Something like that. Yeah.

I really didn't go. And so they wanted to throw something in there for it. I don't know. Possibly. Yeah. Oh yeah. That's it. I don't know. Possibly. Yeah. Oh, yeah. That's interesting. So I came up with a little list. We put together some things that we thought of.

If you ask me, what are some good APIs? And the first one I put down was Kubernetes because it's very consistent. And it's got a cool plug-in architecture, which is something I think that would have been really hard to do and they managed to do a good job of it in a way that makes sense and that works with a lot of tools and allows for plugability which I thought was really cool and everything is annoyingly

versioned. So if you've ever done anything with like the role-based authentication or whatever they call it, role-based security stuff you've probably seen where you have to specify the scopes and stuff are in. And so sometimes it's like, well, deployments are under apps slash V2 and some other thing is under apps V1 and some other stuff is just under nothing. It's just version with the main version of Kubernetes.

And so it's kind of interesting to see how they did that and how they have so many different versions and how it all kind of makes sense like scaffold is tool we talk about a lot it's got its own version and it's cool to see how they kind of plug that stuff in so that you can use newer versions of say kubernetes with older ways of doing things so it's kind of cool to see that kubernetes is made up of many versions, which is not something that you see often, but I thought it was cool. Kafka, as much as I'm sometimes frustrated in how Kafka makes me feel like a dummy, if you look at their APIs, actually, a lot of them are really simple

and really well done, like Schema Registry, Kafka Connect, stuff like that. They very much stick to the kind of standards. So after you get kind of used to what's available you can pretty much guess what their apis are going to be so if you need to delete stuff or get the status of something it's all just pretty much going to work like that that's always a great feeling when you like you get to the point to where you know you understand their api enough to where you're like i guess i i bet there's something like this. If I just search for these keywords, I'll probably find

it. Yeah, that's a sign of a good API. Real quick question, though. When you're talking about their APIs, I assume that you're not talking about their CLI stuff. You're talking about their Java admin APIs and that kind of stuff, right? Yeah, and the CLIs, it's okay, but

I think Kubernetes consistency is much better. You know it's Kubernetes, kubectl, git, and then some sort of noun or resource type. So even if you go and install the Prometheus plugin, essentially, like the operator or whatever, and it installs those custom resource definitions, you know it's kubectdle, get Prometheus, keep cuddle, get whatever. And you know, that, um, that stuff is just going to kind of plug in where you expect it, which is really nice.

Um, I put pie game and pot and pixie JS, because those are two examples where they introduced new abstractions. So whether, um, those libraries are writing to a web GL or SDL or whatever, uh, they've got some, some nice consistent abstractions where, say, you write to a texture,

and it doesn't matter which library you're using underneath because it just kind of glosses over that. And so that was just kind of an example of something where it's like anytime you're working with graphics, really nice to have an abstraction that kind of saves you from that. So I really appreciate those interfaces. Cool. Yeah, and what I threw in here, because it truly is one of my favorite is S3. So Amazon's S3 API is for their simple storage. Can't remember what the third S is. Service. Is it? Yeah. Service. So the thing that's interesting about this is by

them creating such a good API for their cloud storage, other companies basically said, hey, we want to compete with them, but we want to make it easy for developers to switch over and use us. Right. Or different applications. Right. Like it may not even be a developer. Let's say that you have a backup solution that is backing up to Amazon S3. And then you find out, oh, wait a second, Backblaze has a compatible API that's a quarter of the price for the same storage amount.

I want to switch over there. And it might just be as easy as pointing to a new URL because they've implemented the same APIs, right? And then there's another like Wasabi is another company that has done the same APIs, right? And then there's another, like Wasabi is another company that has done the same thing, right? Like they've provided cloud storage using the same S3 APIs. And so just by doing that, you make it easy for developers and people to adopt your technologies, but you might also make it easy for other people to sort of piggyback on you and, and create shims or replacements, you know, slip ends for that kind of stuff.

Well, isn't Kubernetes like the ultimate of that? Like, Oh, Hey, how do we get into the cloud business? We're a little late to this and Amazon already has all of it. I tell you what,

what if we had just abstract the whole thing, right? You can just run your child anywhere. Yeah, it's true. That is true. I tell you what, what if we had just abstract the whole thing? You could just run your cloud anywhere. Yeah, that is true. I mean, honestly, one of the projects that all three of us had worked on in the past, one of the things was they wanted to be able to make it run in the cloud and on-prem, and that's why we chose it. We can create this thing and it'll abstract away all the hardware and stuff as long as we got some compute.

We can make it happen. Yeah, that's a good point. So, you know, we talk about Kubernetes, how you have to get certified. So if you want to say, hey, I'm Linode and we offer Kubernetes, that means they had to go through a rigorous certification program and be able to use that capital K word. And that meant that they had to go in and they had to meet these interfaces. And so when you create a new service or whatever, it'll go and provision the right load balance or whatever behind it. Yeah, I was curious. So I did a search for like, hey, what are some of the

most popular APIs? And came across this website that I hadn't heard of, Rapid API. Oh, I saw that one too. Yeah. And there's some interesting ones that came in here. Like some of these, I was like, okay, yeah, I could see that. Like Yahoo finance was in there. I'm like, yeah, okay. That makes sense. Uh, there's one, I hadn't heard of it specifically, but open weather map. I'm like, okay, it would make sense that, uh, you know, somebody want, might want something for, uh, you know, that there would be some weather one in there. Um, although I kind of expected it would be something that there would be some weather one in there.

Although I kind of expected it would be something that you would have heard of more like a, you know, weather channel or weather underground or something like that. Right. But, you know, it was in there. But then there were some funny ones in here, though, that I was like, I don't know what that one is. So one of them was the Chuck Norris API. So I was like, okay, well, that just has to be awesome. Like there's, you know, where could that one possibly go wrong? The Urban Dictionary will tell you where it went wrong. So, yeah. Then there was one for jokes.

So just joke API. So I was like, okay, I should probably, uh, use that one. Um, and then there was actually a couple of jokes when there was a joke API one in there too. So yeah. Uh, and then, and then there was like another link that came up for the same site that was like the top, uh, you know, some free API services that were available. So they, you know, Amazon's, uh, there was one for Amazon products. So, you know, Amazon's, uh,

there was one for Amazon products. So you could get like real time, uh, uh, data about products and reviews and whatnot from Amazon. Uh, there was another one for Google search that I thought was interesting. Um,

and then just like, you know, kind of topical related to what's going on in our current world. Right? Like, so there was another API just for COVID. so i'll include these links in there too you can go check out the chuck norris api excellent i also wrote down uh some of my least favorite and i should i want to clarify this doesn't mean that the apis are bad it's just these are ones that like don't love working with

and the first one i mentioned is elastic and the reason why i say elastic is because it's just these are ones that like don't love working with and the first one i mentioned is elastic and the reason why i say elastic is because it's got a really big api that's done in basically essentially a domain specific language for the most part which is just a big json document which means it's hard to get uh tooling that uses like let's say autocomplete or something and so little things that like um well i want to filter by range it's like well okay so i've got my object and in there i need a query and there i need a a bool which has a must which has a filter which oh let me go look how the range works and so it just crafting those things the first time uh and obviously you get better at it but it's just it's not as easy to get started with.

And it's super powerful. And that's why it's kind of so all over the place. But it's, you know, it's not the kind of API that you can really start kind of feeling out on your own. Like you're going to be spending a lot of time in the docs. Pandas. So the reason I mentioned pandas here is the Python library that is really good for dealing with like kind of tabular data. The reason I have pandas here is not because it isn't great, because it's fantastic, but it's because the inputs and outputs are very flexible.

And the output of the function can change based on what you pass into the input because Python can do that sort of stuff. But for me, kind of coming from like a static mindset, that can be really. But for me, kind of coming from like a static mindset, that can be really frustrating to think like, well, I pass in a numpy array and I get a numpy array out, even though that's a third-party library. If I pass a list in and I get a list out, it's just very loosey-goosey

and there's all these optional arguments and stuff. So you look at any one function and it's super powerful, but it's got like 18 arguments. And depending on if you're passing in a csv or an array maybe you have to populate arguments 1 3 7 11 or maybe you just need 2 and 4 which is just kind of tough if you're looking strictly at the api i'm surprised that you didn't include in your least favorite list here, like any API I wrote. I guess I'm a little honored,

but it wasn't in one of your favorites either. So I'm like, eh, I guess I'm somewhere in the middle. You know, an API that I don't love and I don't, I, this is maybe mixing up with a CLI is gets,

and I know this is going to be painful for you outlaw, but the problem is depending on what you are choosing, it's just what you said, Joe, like you have to know that you have to combine these three other parameters out of the list of 200 in order to get it exactly right. And that's, I don't know a good solution to that. Honestly. I's just forget man kit has got so many like if you ever need to do something that seems seems reasonable like hey i want to know who the last person is that touched this file oh my dear god or you know like maybe not the last person the last person who did this the last 10 times or something like the string of

commands you got to put together to do stuff like that is just crazy a lot of times and it's and somebody will put rtfm out there and you're like for real like yeah dude like i went i went to the page and i got lost on you know character, character number 9 million. So I'm not real sure how I'm supposed to figure this out. But it's super powerful because it is. Man, there's just so many combinations. But not an API. It's not consistent. And so, like, you know, the Kubernetes I said was very consistent.

Like, there's things you can do. Like, if you want to delete a service or you want to delete a pod it's the same command you just change the resource type yeah git is not like that if you think about the four common git commands if you were going to go teach someone new commit you're like okay well i mean you need to know about git clone maybe you need to know about git remote origin add if you want to's commit. Oh, we got to teach you get add. And so some things there are verbs. Get log is not really verb. And so it's just, it's this kind of election thing.

So, so imagine if it was resource pivoted, if it was resource oriented and you said, get commit, add, and did you think, or get commit, undo or get commit list,

you know, that's much more consistent about. So when people think like, oh crap, I need to undo my commit. It's not a Google to see what weird kind of type thing you have to, you know, which flags you have to pass to which commands. Yeah. I think that's what it is really is the consistency and the number of flags that can go with each one. Right. Um, so yeah, again, I love get, I use it a ton and I've gotten pretty good at it, but it is not my favorite interface. Yeah, so maybe to say another way, the APIs that are my favorites are the ones I have to use the least or I have to know the least about, at least in order to get what I want done.

Well, because they're consistent, right? Like you said with the Kubernetes one, like Kubernetes is massive in terms of if you're just even looking at the CLI, which in turn probably uses the API behind the scenes, it's hyper consistent. Like you said, you need to delete an app, you need to delete a pod, whatever, a persistent volume claim, whatever, it's all the same commands. Yeah. So so yeah i really don't want to sound like i'm hating on get you know gets uh pretty old things were different then but we think about like the github uh api the cli tool that they just came out with they went resource oriented so you say get issue or gh issue new gh issue list gh issue close and so it's kind of got that thing where it kind of branches out like a tree.

And it's just kind of arranged more hierarchically. And that's a newer style, newer way of doing things, and newer tools have the benefit of seeing other things do it and work out that way. I guess we can't be friends anymore. So, yeah. What if we had a common enemy?

What if we all had something we didn't like? Yeah, I saw this one coming up. This might bring us all together. We've talked about this one before. So if you've listened to the show for a length of time, then you're not going to be surprised to hear this one be mentioned. Someone mentioned? Oh, I was going to leave it.

I was going to let you do it since. Oh, okay. Yeah, so I wrote down the paypal api and you know granted my experience with it is very old at this point but we just had a really rough time if the things were confusing um it was kind of stateful in a weird way where you would have to kind of do things um kind of do something before you could do something else and it wasn't very clear you know oftentimes you'd have to like if you wanted to do a refund or if you wanted to collect and just wasn't very flexible. And so it was a,

it was a real pain to work with and trying to kind of organize what happened to happen in your code to get the effects that you want. It was just really frustrating. You know what though? I think it's worth talking about the reason here. It, I don't think the APIs were terrible. They were documented pretty well. Like you said, they might be a little bit confusing, but I think the problem is they

tried to model it to act like credit cards. The APIs were set up to make you believe that it functioned like a credit card API, but in reality it didn't. And that was where, so they built up an expectation by making it look like something and it didn't actually function that way. And that's where a lot of the pain came in. If I'm remembering correctly. Yeah, I would totally agree with that. And like, you would think, um, if you had a credit card and we worked for e-commerce company and there was a problem with the product or the customer call and said, hey, crap, I ordered the wrong thing. I actually need 10 of this and I need to not get rid of that item and say, OK, fine. With a credit card, we say, OK, that's fine.

We're going to rerun your credit card. And, you know, because now your new order is more expensive, for example. And so it would go and do that. And you use the token from the credit card, which was still valid and would go and it would get the do that and uh you used a token from the credit card which was still valid and would go and it would get the new amount and would be reauthorized we get new authorization code and when those items shipped we would collect that money so we didn't have the liability sitting out there paypal was very much more oriented around the order and it kind of makes sense with paypal because like you really don't know what that person's using behind that

paypal wall maybe it's a credit card maybe it's their bank account maybe it's a gift card who knows uh but paypal abstracts that but then when the customers would call and say hey you changed my order you would say okay well i can't just reauthorize your thing you you have to take an action here we can't do this stuff on your behalf and so it was just really complicated to make edits and so it got to the point where like all right well if a customer uses paypal then we just don't change their order. We have them go back to the website and just redo everything. And it just was a real big divergence for all of our workflows and everything to kind of have this thing that felt to customers like it should be so similar and felt to our employees like it should just work the same way. And because of these implementation details and these restrictions and things that just worked a little bit different,

it was just a hassle at every step of the way. And it, I wanted to bring that out though, because it's important to know that I think in terms of their actual API implementation, documentation, all that, like they did a pretty good job putting all that together.

It's the fact that they led you to believe that it worked like something else that made the API experience painful. So it had nothing to do with their technical implementation. It had to do with the fact that they modeled it after something else. So, so I'm bringing that out. Like APIs don't necessarily have to be great or bad because on their own, they are are it just might be that you know some external influence might have caused pains in that same regard it was a really interesting frustrating time well it's like they you know going to to elaborate on your point there though it's like they they didn't even model it like the real world, right?

They didn't take into consideration it like, oh, okay, yeah, we'll let you put this hold on the account. But because these are bank accounts, that money might not be there, right? There's no guarantee, but they let you put the hold on it. So it didn't model reality and that's where, that's where it got frustrating. Now, you know,

that in fairness, that was a while back. So, you know, maybe they've corrected that. You would hope so. Right. Um,

you know, but I was also thinking here too, like, you know, speaking of some of the older APIs to like older iOS, uh, versions and Xcode, uh, you know, you know, you go back to like older iOS versions and Xcode, you know,

you know, you go back to like an iOS four and you know, the Xcode that you had around that time, like you know, but that, I guess, well, I mean,

that's not fair because I'm talking more about the Xcode, which is not the API, but whatever. I digress. Yeah, totally. Slack just changed our API and removed a feature that we were using for auto signups.

And so we got a problem there. So send us a tweet or something if you want to get into Slack. So can we say Slack is our least favorite? Yeah, it is right now. Of late, yeah. I wanted to mention that different types of APIs have their own set of common problems. So we've got a big list here from REST and then we've got some other ones.

But I really want to kind of emphasize that REST is not the definition of API. That's just one way to do it. But it's so common that it's making it hard to search for anything else. And there's some good and bad we'll talk about coming up here in a little bit, but I just want to hit on the commonalities. If you are a REST designer for making APIs for other people to consume on the front ends or maybe other back ends, you're probably worried about authentication and maybe rate limiting. You probably have interest in async commands, if not everything async, at least for

larger reports. You ever see that? That's a good way to make me hate APIs, have something that's async where I have to come back and keep pulling, see if it's ready yet. Filtering, sorting, and paging, something that's really common. If you're writing APIs for a website, that's something that you're probably familiar with. Caching, error handling, game libraries. I mentioned that abstractions over graphics libraries earlier.

There's a huge emphasis on inheritance and hidden systems a lot of times. If you're working with a game library, it can be hard to work with at first because you'll try to do something like add text or something only to realize that the text system hasn't been initialized and that's not something that you ever get from going to google to look at how to do text because it's something that happens in a

total effort different area of your application um so you know if you're working with uh like big triple a pc games and you're looking at doing things like supporting multiple different resolutions and having graphics that can scale down or pop in later and all this stuff and those are details that you want very far away from you if you're programming something about like the the player interactions and input and output it's just there's a lot of things that are connected and they really try hard to keep that from you so game libraries have things and common pitfalls for that. Libraries for service providers. So I mentioned Elastic earlier. Elastic has libraries for Python, Java, C Sharp, the REST API that you just kind of meant for humans or anyone else.

That's all really great. And every time they add a new feature, they need to go update it for all those libraries, which have their own versions, because sometimes they need to change independent of your stuff changing. Maybe Python releases a new version and deprecates something, and so they are forced to release or have a bug fix. And they need to go out and update the documentation for all that stuff, too. So every time Elastic adds one new feature, they've got a ton of different places just to communicate it that need to be updated which is in addition to actually implementing that feature which is something that's that's really tough and if you're designing a program or an api uh that's apis that are meant to be used by multiple people then multiple different languages and that's something that you got to put a lot of work into you know who we forgot to mention? We were talking about APIs we love.

Microsoft. Azure. Oh, Datadog. They've got a ton of APIs for whatever your language of choice is. They've got you covered. And we've talked about it before in the past, where it's you know, you, you want to use a data dog with Python, pip install data dog. It's like literally that's a thing.

Yep. And a day sex too. Like one of the things we talked about, um, I know the sponsor sponsor is, uh, we look at data dog, sorry,

data stacks. One of the things that we were really impressed with was, uh, just how easy they made it for developer. Cause it depends on what language you were working with or, um, they had like serverless options and just all sorts of other stuff and like that's one of the things it's really great for you as a consumer because if i'm looking at rust maybe there's a

rust library for it but if you're that developer every time every feature you add you've got to think about how to do it in that language and i know we've seen we've seen libraries that like uh our first class java libraries they were designed for Java first and then someone poured them to C sharp and it feels like Java, the terms they use, the way things are capitalized, the abstractions don't make use of language features. And that stinks.

There's all these, why there's all these impulse, right? That brings me back on, on APIs that did. I particularly like Microsoft does such a good job like in their azure environment because they support more languages than just about any other cloud out there and they do a really good job putting that stuff on a page right like their documentation for that

stuff is amazing don't don't don't limit them to just azure okay yeah microsoft has been the gold standard in terms of documentation for decades which is why they became the powerhouse that they are because they catered to the developer yeah like everything they did was for the developer to make the developer easy and so like you know you know, they, for decades, it was like, oh, hey, you know, you get an MSDN subscription and here's all the documentation. You remember like you would get the CDs and you would install all the documentation locally? Yes, you were. You were super excited. You know, like 85 floppy disks later, you've got like all the documentation, like locally searchable.

Yeah. But it was a big deal, right? Like they've always had amazing documentation. And now the thing that they did in recent years, and I don't remember how long ago was they did this, but they moved all their documentation to get. And so now you could be on a page and you're like, oh, I see a problem. And you could just click on a link. They'll take you to get to where you could fix it. Yep. Yeah, no, their API docs are amazing. I'll tell you who's I'm not a huge fan of is Google's. So having done some Python development on some data product stuff at Google, man, it's so frustrating because we've all seen Java docs, right?

Like we've been to those pages. They're ugly, but they're very functional, right? Like you can find the method names, you can find all that kind of stuff, and you know the format. Man, the API documentation for the Python stuff in Dataproc was just, it was so unorganized and it was so hard to actually find relatable things. Like you'd say, hey, this returns a job collection. It's like, well, what is that type? And then you'd have to just go Googling around to try and find a page where it actually told you

what a job collection was. So yeah, it's not easy, but that's, that's a situation where the API itself was decent, but the documentation made it so hard to work with that. It was like, man, I don't want to deal with this. Okay. This is going to be an unpopular opinion, but if we were to go to the APIs that I don't like and turn,

like, because their documentation, then, and this is not shots fired because you picked on get like, I promise you, I promise you, who's this one aimed at? Well,

we need to have a talk with Colin. Cause documentation is awful. It's not great. No, it's not even close. Really? I've never used it because it's just so obvious. Oh, is that what it is?

Yeah, that's complete garbage. I don't believe that either. They do have a really good tutorial page or set of pages, but yeah, their documentation, if you're... You get out of that need, though. You're like, wait a minute, how do I do this? And you're like, well, we got this Hello World example over here. No, I need to do something more sophisticated than hello world. No, but we got this hello world. Use the hello world and it will work.

Yeah, but I want to do something a little bit more complicated than hello world. I don't think you understand, sir. We got this great hello world. Like that doesn't do anything for me. Yeah, I can agree with you. Kotlin as a language is amazing, but their documentation suffers a bit. All right. Whatever.

So the next one I actually threw in here because we were talking about REST. And REST specifically, like one of the things about it that either makes people extremely happy or extremely frustrated depending on, on the application that you're doing is it's very noun based, right? So if you have a customer, then you're going to have a customer rest interface and it's going to have the get the ad, the update, all that kind of stuff. Then you're going to have an order interface. Then you're going to have an order item interface or whatever, right? The problem is if you adhere to the REST standard kind of

the way that they want it out there, you keep those things separated, right? Like you're not going to have user order interface typically is not how it works. You um, but everything is operated on in, in individual states, right? Like I said, get update, whatever. So it made some things kind of difficult. And this is where sort of, Oh, data or Oh, data sits on top of it. And this was for people that needed sort of more complex things to happen with their, with their web requests, their APIs. So like one thing that they have in there is the ability to pass in complex filters.

So if you think about querying a database or something, right? Like you give me all the orders from customers where their order value was greater than a hundred and it was in the last 30 days, right? Like you have two filters right there that you can't really represent in a typical rest world, because what if you want to add a different filter that says in their last name starts with you, right? Like you don't just keep adding on to a rest thing like that. Well, OData gives you the ability to add these filters to those queries. So that's a big one. Another one is this whole notion of relating objects, right? Like I've got customers with orders. Well, I don't want to have to call two separate rest endpoints to get the customer first and then go get the orders after I got the

customer information, right? You can stack those things. OData has a way of doing that. And then another thing too is this again goes to why it's sort of hard because typically what you'd see, and I mean, the three of us have seen this over time is people will abandon O data as soon as they need to start passing in multiple arguments, right? Multiple search filters and everything. And they're like, well, I'm just going to create a method and we'll call this get customers by, you know, filter criteria or something. Right. And so now you have this method out there that you can pass some sort of filter object into. Well, OData allows you to do that on top of rest and invoke a function RPC style. So if you needed to do that and get away

from the verb approach, which rest sort of ties you to, then they have a standard way of doing that. So I have a couple of links here. If you've never heard of OData, I know Microsoft uses it pretty heavily in a lot of their products. And it's kind of nice to see how they've done it in case you ever need to do things like paging, advanced filtering, that kind of stuff.

But you want to stay within the rest paradigm because this is actually being created on top of rest. You know, if we're going to talk about rest for a moment though, there is like the elephant in the room that hasn't been mentioned with it. What's that? Right. And I know what you're thinking. You're probably thinking like, uh-oh, wait for it. Outlaw's going to set us up for a joke. Here it comes. No, because with rest, like, you know, you mentioned the verbs, right. Which, you know, for anybody who hasn't done any rest, you know, development, then, you know, the verbs that he's talking about like,

or you'd post a verb back to the server that might be like post or get like, I want to get something. I want to post something to like write it. I want to delete something. I want to tell something like there's a whole bunch of different verbs, right? But not all of those verbs are even allowed, you know, through, through some companies. So like, depending on what you, your audience is for some of that, you know, like if you're writing a business application, that's're writing a business application that you're going to sell to your customers and that they will have inside of their business intranet, they might not allow a delete verb, for example. So then that can become an issue. Because then if you're like, well,

I wanted to try to adhere to the REST standard, but it's like, but you can't, he speaks from experience. And then you also have to be careful too, with like, uh, with, you know,

people might try to abuse the gets and not realize like, oh, but those can get cashed. And, uh, you know, you have to be prepared for that. So ironically,

I've seen the inverse where everybody's like, I don't want to deal with the gets. Post everything. Yeah, I'm going to post everything because I can do, you know, huge request bodies and then it's fine. But then you don't get the caching benefit. So when you're dealing with REST, it's not just the verbs for the verb sake on the server side. It's also, you kind of need to know what you're getting when you're running each one of those verbs. Cause your gets can be cached by a browser or something and your posts can't.

And I don't know, there's all kinds of things. So I mean, this is super complicated. Yeah, it actually is. So, so yeah,

I realized that the way I set that up, like it, you know, you saw, it sounded like I was going to go into a joke, but I really that the way i set that up like it you know you saw it sounded like i was going to go into a joke but i really wasn't it was really just like you know a complaint about about rest though although i mean i do have a joke for you about yoga but it's not really working out i think we'll get some comments back on that one. Hey, one other thing before we head into the break here. So there's APIs out there and I want to caution and I'm curious what you guys say about this, but I want to caution anybody from calling APIs directly from your front end. Maybe if you're just trying to do a POC or something, fine,

whatever. But anything that you call directly from a front end, if you're doing a web client, especially, that's all stuff that people can hack into and do whatever they want, right? So my take is anytime you're trying to call some API, public, private, whatever it is, it should happen from your middleware, right? Whether it's your.NET, public, private, whatever it is, it should happen from your middleware, right? Whether it's your.NET, your Kotlin, whatever, you should not be making those requests directly to Elasticsearch, for instance, from your UI. You should not be making requests to that weather API from your UI. Your UI should be talking to your own server, in my opinion, and then that server should be making the requests out to the thing because then you can safely scrub and make sure things are the

way that they're supposed to be coming and going. So I would say it would definitely vary by use case, like, you know, because maybe your use case is you don't want to have a, uh, server, a server running. Right. Um, so there's that, but then, you know, keeping in line with the things that we've learned from like clean

architecture and clean code and pragmatic programmer and things like that, then, you know, they would advocate for you, um, having a front, you know, by,

by allowing your, your front end to talk directly to those multiple services, then you're creating that dependency at that layer. Whereas if you put it back on the server side, you could, you know, put a wrap of facade around it or, you know,

wrap some kind of layer, you know, some kind of boundary layer around it so that you limit its exposure. Yeah. And that's really what I'm getting at. Especially if there's, if there's any, if you have to authenticate,

do not ever call from your front end, you know, that should be going through your, your middle tier somewhere. But, but yeah, I mean, I agree.

Like if it's a POC or if it's some like little utility you're creating just for fun and maybe it's your own use case, fine. But if you're going to expose it to the world, then you need to put some more thought into it, I think. So you need your backend or sorry, your front end for your backend, your gateway, all your other stuff. You do, you do. This episode is sponsored by Datadog, a software as a service based monitoring and analytics platform for cloud-scale infrastructure, applications, logs, and more. Datadog uses machine learning-based algorithms to detect errors and anomalies across your entire stack, which reduces the time it takes to detect and address outages and helps promote collaboration between data

engineering operations and the whole rest of the company now you've made me curious though because you said slack and they have like so many integrations that i'm like huh i wonder do do they have a slack integration because that would be kind of nifty if they do i mean they have integrations for everything else so i wouldn't be surprised if they do. And I'm looking and maybe I'm spelling it wrong. But, you know, the real thing, though, is we're talking about APIs here. And, you know, as I just mentioned, they have APIs for all your platforms, too. So not only do they have, favorite, you know, tech stack is that you want an integration for, they've also got for whatever your language of choice is, an API that you can use for that. So just such a well thought out product that,

you know, I can't gush over enough because they just have so many awesome things that they offer. And if you don't find it, what you're looking for, I guarantee they probably have a blog article about it. And it'll point you in the direction of what you were looking for. So they've got you covered in like a thousand different ways. There's no shortage there. You know, I'm glad you mentioned both the blog and the apis because i was actually just looking at their docs because uh i don't however i want to look up something for data dog that's where i go is docs.datadoghq.com if you just search slack there 183 results

and if you go look at any one of these pages you will see that there's many many ways to integrate with slack uh but that's not even the thing that's most interesting. How well organized it is, the images that they have to show you exactly what you're getting and what it means and how to set this stuff up with examples in multiple different languages. I mean, it's just fantastic.

It's really a pleasure to read. It's kind of makes me want to go write some better docs. Even just on the top right, you can select multiple different languages, different sites. I mean, it's just really laid out really well and they made it really easy to do a whole lot of things with Slack and a lot of other integrations that Al mentioned. Yeah. So as you can tell, we like Datadog quite a bit and we're pretty sure you will too. So head over to datadoghq.com slash codingblocks and start your free 14-day trial.

If you start a trial and you install a Datadog agent, Datadog will send you a free t-shirt. So again, head over to datadoghq.com slash codingblocks. How about that? Just out of the blue, we picked a technology and they had an integration for it. Yeah. That's insane.

I got it for everything. You just slash invite at Datadog. Yeah. Isn't that cool? That's so awesome. Yeah. And seriously, like for various, like if you go to like page 183 or 18 or whatever it is for the last ones, like some of them are very specific or integrating with your distributed tracing

and so you can get a very specific information about how something got there. It's just really cool. They're amazing. All right. Well, it's that time of the episode where we ask, hey, what do you call a pig with a black belt in karate?

Bacon? Bacon. Bacon. There's gotta be bacon somewhere in there. Well, the answer is pork chop. And so thank you, Mike, Mike RG for both of those.

But no, seriously, this is the time where we would typically ask like, Hey, if you haven't already left us a review, if you enjoy those jokes and all the other ones that people have submitted to us that we've shared, then, uh, you know, Hey, we would greatly appreciate it. If you left us a review, um, you can find some helpful links that are plural now, uh, since Alan thankfully, uh, updated that for us and, uh,

you know, just a two year, uh, support ticket. Uh, but he got on it within the first two weeks of it being asked for. And so service with a smile. Yeah. Yeah. We're good. Uh, but yeah, we would appreciate the review. So you can find some helpful links at coding blocks.net slash review, uh, to your favorite, uh favorite podcast destinations. And with that, we head into my favorite portion of the show. Survey says. All right. It's the tip of the week.

No, that's later. That's your favorite portion. How do you not know this yet? How long have we been doing this? Yeah. Oh, we're off to a fantastic start. Okay. So back in episode 152, we asked, what's your favorite Python feature? And your choices were all the machine learning libraries or the Jupyter notebook support or pip install everything I need.

Or, and this might be my favorite, the virtual environments are the best. Or I require a lot of matrix multiplication. Or it's so easy to visualize data. And lastly, it's so easy to visualize data. And lastly, it's not Java, which is not a lie. It really isn't Java. So,

uh, according to, uh, to Tucko trademarks, um, you know, rules of engagement for the episode here. Uh,

this is an even number. So it would be Joe's turn. No, wait, this is an odd number. Sorry. The other episode was a – I was looking at the episode 152, which was an even number, but you're right. This is 157. So this would be odd, so this would be Alan's turn. Time to go first.

All right. So I think we can totally eliminate the virtual environments. Those might've been used in 1990. Come on. I think, I think we've gone away. Come on, man.

That's not even, you know, that's, you know, you're wrong. You know, you're wrong. So I,

you know what I'm going to say here that i think it's man i think it's so easy to visualize the data i'm going to go with that and i'll say 22 of the vote 22 easy to visualize there's a lot of options here okay ah. Ah, geez. Well, it's not Java, but I'm going to go with Jupiter Notebooks at 40%. Oh, bold. All right. I like it. I like where we're at here. So, Alan

says, it's so easy to visualize data at 22%, I believe you said. Yep. And Joe picked Jupiter Notebook support support with 40 of the vote right yep at least oh we both lose yeah you're both wrong how really it was staring you in the face. It's not Java. I knew it. I knew it.

Of course that's the one. Of course. I knew it my whole. Even people that write Java are like, yeah, I'd rather work in like, you know, anything else, Scala,

Kotlin, something. They don't mind the JVM. Nobody minds bytecode, but Java. Right. It's not Java. That's why there's groovy, Scala, Kotlin.

What else compiles down to the JVM bytecode? Closure. You know what's bad? People are choosing closure over anything else. It was 55% of the vote, by the way. Oh, wow. Nice. What was number two?

What was number two? Number two was pip install. Everything I need. That's a good one. 20%. It is easy. Yeah. I can't believe you guys let me down. They voted by with the virtual environments.

Yeah. Well, what place did that come in? Fourth. So disappointed. Um, yeah. So,

uh, okay. so okay, I can give you this episode's survey or I can give you a joke. Which one would you prefer? Joke. Alright, guy walks into a bar and asks for 1.89 root beers. Bartender says, I'll have to charge you extra for

a float. Guy says, alright, well make it a double then. I like it. afloat. Guy says, all right, we'll make it a double then. All right. So, uh, this episode survey is how do you prefer to be interviewed? And your choices are behavioral interview. Tell me all about your mother. Or take home project. How many hours do you really spend? Or whiteboarding like surfing, but worse. Or multi-person interrogation room like firing squad, but better. Or an informal dinner because that's not creepy. Watch me chew.

Or weird esoteric. How many angels can dance on how many ping pong balls on a plane with three potential destinations? Dude, these are amazing. You just want to know your thought process. Don't worry about getting the right answer. Well, it's interesting because like, you know, so it's a little bit of behind the scenes for the audience there. Like I was telling the guys that like because there's been a lot of conversation lately in the Slack related to, you know, a couple of people that have been interviewing

around at some of the big companies and having really good success with it. So if you're in the coding block slack, you'll, uh, you know, you might know some of those conversations that I'm referring to. And if you're not, Hey, you should definitely become a part of that. And, um, you know, made me think that like, Hey, you know, we probably should just do an episode on trick interview questions. I thought it would be kind of neat. Of course, we would fail miserably at it. So I would have to go ahead and come to terms with, like, I'm going to sound like a fool.

Unlike this one. But I would sound like a fool different on that episode. That sounds great. It'd be interesting, though. I'll just do the interviewing. That'll be good. Yeah. Okay, here's one for you.

You have three cups of coffee and 20 sugar cubes. How do you put an odd number of sugar cubes into each cup of coffee using all 20 cubes? What was the number of cubes? 20, 20, an odd number of cubes. Yeah.

So how can you basically divide by 20, uh, within with three odd numbers? Let me read it again. You have three cups of coffee and 20 sugar cubes how do you put an odd number of sugar cubes into each cup of coffee using all 20 sugar cubes i don't oh that's tough it's like any it's like any two odd numbers that you add together is going to give you an even.

So I feel like this is the joke. No, I think you eat one of them and you put the rest of the coffee cups. Do you want to know the answer? Yeah, of course. Wait, give me one more minute. So if you add any two odd numbers, if I add five and three together, you get an even number eight, which means that you've got an even number 12 that's left. So there's no number that you can, there's no even number you can subtract from 20 and get an odd number.

So 20 minus 10 is 10, 20 minus eight is 12, 20 minus 18 is two. I feel like this is a riddle. I don't think it's something that you really solve. Is it something you really solve? Something you really solve. So you put 11 in one, 9 in another, and 0 in the third. You can't. That's not an odd number.

It's not an even number. But the question was that you put an odd number in each. Do you want me to tell you an answer? You ready? Well, a 0 has never really made much sense to me. It's not a number. You can't divide by it. Yeah, I'm ready. Okay. Here's the answer.

You put one cube in the first cup. You put one cube in the second cup. And 18 in the third, because 18 is an odd number of sugar cubes to put in coffee. Oh, yeah, that's great. That's great. That's just great. I knew. I knew.

When I saw that joke on Reddit, I was like, oh my God, that's so good. I totally could have tripped him up because I already wanted to do like real interview questions anyway so i was like this one is going to be perfect i can't wait oh my gosh i was about to like prove by induction that there's no two odd numbers you can i loved where you're going with it too you're so serious like all these examples of like okay 10 20 minus 10 is still 10 man when you read you read it, I had already bailed.

I was like, man, he's going to say something here in a second that's ridiculous. You know, we've got an interview tomorrow. We're going to be interviewing somebody. So I think we got our first question. I think we do. Do you want another one? I don't know. Okay.

I'll give you that. Well, okay. How about this then? Did you know that 10 plus 10 and 11 plus 11 are the same thing? I believe it. No. But they are. I can prove it.

10 plus 10 and 11 plus 11 are the same thing. So 10 plus 10 equals 20. But 11 plus 11 equals 22. That's what I was afraid of. Let's give something like that. Well, you can blame David for that one. Nicely done. Nicely done.

Dave Fullett? No, no, no, no. I don't know the username. I just know the name that he has on there that you can see. Oh, thank you, David. I have my Slack configured to where I don't see your screen name, like your login name. I have it, like whatever name you have that gets presented, which would normally be like first name, last name.

But some people don't put in their last names or whatever. Fair enough. All right. So, well, let's get back to the episode talking about writing great APIs. And now we're actually getting to talk about what makes the APIs great. We've been using some bands so far, but we've got some things that are gathered up here.

The first one we've got is easy to work with. That, for me, is kind of number one. The APIs that I enjoy writing for are easy to work with. They install easy. They're documented well. I don't even need documentation. Difficult to misuse is something I thought was interesting.

How do you make something difficult to misuse? I mean, you, you, you just skipped over the documentation that was saying like you didn't need it if it was easy to, to work with. But like, to me,

the documentation is what makes it easy to work with. And so it's, it can be easy to misuse if you don't have the documentation to tell you how to use it. Right. Yeah, I agree with that. I think the difficult to misuse though,

I think going back to the consistent, like, um, resource verb type thing definitely helps with that. Right. Like just having a consistent approach to it, it makes it easy to, or makes it hard to misuse. I know APIs that have been easy to misuse where, um, like sometimes we'll work with the API and you change the verb,

maybe if you use a postman or something or curl, and, um, maybe, um, the thing that gets a resource is the same URL that you would use to delete the resource. And so if you actually type the wrong thing or forget to when you're moving stuff around, I've actually deleted stuff that I didn't really mean to. So one example of a way to make something easy to or hard to misuse is to just change that a little bit.

And so maybe that's not a great idea. Maybe you don't want to do that. But I think if React has that dangerously set in our HTML, they could have made every other property and just idea. Maybe you don't want to do that, but I think if React has that dangerously set innerHTML, now they could have made every other property just innerHTML, but they don't want you to because it interferes with Shadow DOM and whatnot. So they actually went out of their way to make the name

something awkward. We've seen in other languages sometimes they'll have things that are kind of private by convention with underscores. So it's kind of a signal to you that you shouldn't be messing with that. So that's the kind of things I think of where it's, they've kind of gone out of their way to make it difficult for you to do the things you shouldn't. I like that. But what you said though, and it makes a lot of sense, you were talking about the whole rest thing, you know, a get like a great

example is get person by ID or something, right? It's going to be person slash and then ID. And if you happen to post it with it or ID. And if you happen to post it with it or not posted, if you happen to submit that with a get, you'll get that ID. If you did it with a delete, it's the same URL. So yeah, you totally, it's what they're supposed to do, but I can totally see where that could bite you. I like that. Like maybe just trying to change that a little for the dangerous operations. Yeah. Mad like a second printer. So it's consistent and it's easily discoverable,

but if it's something that's a dangerous action, like something you do not want to do lightly, maybe make it a little harder, add a second command to say like, yes, I mean it or a second parameter, right? Like you have to add a token to it or something.

I don't know. Anything. Anything to change it up a little. Good call. Sometimes we've seen something will have resources that you can lock, like a domain name. You can lock your domain name. And so you can't accidentally do something that domain name until you go and unlock it first. Yep.

That's the example where you might have to do some other action first before you can delete or do something dangerous. I like it. Consist dangerous. I like it. Consistency. Really like that. Especially when it comes to things like input and output types. You ever work with an API where it's like it'll take a credit card, but if you call it this way, you pass the token.

You call it the other way, you pass the number. You call it the other way, you pass the order for the credit card number. It's just kind of confusing. So if you can be really consistent with those, with those objects, then that helps a lot error messaging too. I like to have, you know,

sometimes languages will just throw you, you know, kind of like unexpected question mark or, you know, whatever it is, something really not easy to work with. And sometimes other ones will have like really specific like error codes or links to documentation that you can find.

I like that. I hadn't even thought about the error messages, but man, that's so key. You ever gotten a good error out of Helm or some of the Kubernetes things? Man. Yep. You got to go describe the thing just to see what's

really going on. Jeez, man. They never tell you. Or any kind of like parallel errors can be really rough. I've been having a lot of fun with Scaffold lately because you could Scaffold up. We've talked about Scaffold in the past as like a tool to where you could, you know, it goes along with Kubernetes to where you could build environments locally. You can also deploy them using the same tool, but, um,

there's, there's this capability to where it could do all of the builds in parallel. But if one of those fails, it can be super difficult to figure out like, Hey, where'd that error come from? Like I had, I had 60 things being built in parallel,

which one of them died. I mean, it's a great call out. If you're going to have an API, make meaningful errors, help, help the people out who are trying to use it. I love it.

You ever work on something and you see an error in the logs and you tell someone about like, I saw this error and they say, Oh yeah, but that error is okay. We expect that error. That's not an error yeah exactly and i do that all the time but those are supposed to be warnings yeah uh so simplicity and uh when

i see simplicity i mean there's like one way to do things and there's nice abstractions for common actions and so i've seen some apis that are really low level and so if you want to do the most common action then uh you have to kind of do this like builder pattern where you're like okay well let me go build this resource and build that resource and build that resource you're like i'm just trying to cancel an account and here i am building the customer object and uh you know building their whatever their order and like all I want to do is just say cancel order and give you an ID. That's that's kind of stuff I'm talking about here. But also, if you've got really purpose built APIs, by which I mean you have things that aren't resource oriented. So you'll have like maybe web service calls or commands that called like create cart from order or something like that,

that are very, like very specific actions. Then a lot of times there's overlap with things like just create order, for example, where you've got two different ways of doing something, uh, creating an order, but you know, one is much more specific than the other. So for example, you know, the thing I said, create cart from order, if you want to do, you want to replay an order. Another way to do that would just say, we're not going to offer that fancy, fancy,

whatever. You just go out, get the order, look up the products from that order. You create a cart and you add it together. So you can argue that one either way. If like, if it's a common enough action,

like don't make me do those 11 things to do something that's really common. On the other hand, don't give me multiple ways of doing things that you have to support and each have little kind of tricks. You know, I have to know about each one in order to make them work. Service evolution. This is super important. So having good versioning habits and also the ability to have good versioning habits. I've seen a lot of things, a lot of libraries that are built by people who haven't really thought much

about changes that might want to make them the future. And so they get to a point where they can't get to the next level of that product because it would mean breaking so many other people. And so, you know, libraries have this sometimes where they go from version one to two and it's totally different you know angular js and angular totally different and um that can be remedied in some different things and some different apis depending on what you're doing like uh rest apis

a lot of times they'll have a version number just right in there so you continue to use the old version even if there's a newer version that's out. Eventually, you can kind of deprecate that. So that's a good path. But if you release your API without that slash V1 in the front, then you are kind of committing yourself to either supporting those original calls that you thought were what your customers wanted or you're committed to breaking your customers in the future. Yeah, take one. end. Don't, if you're populating an index called customers, right? Don't expose that to anybody. You create an alias for that thing called, um, customers underscore V one. And then if you ever want to change it, right? Like then, then you can, you can do these things later on, right? Like, because just what you said, you don't want to break that contract and you don't want to be tied into the same code that you wrote five years ago and you can never move away from it.

Windows API is famous for supporting things for a long time. So they, you know, for especially back in the 90 days, 98, 95, whatever, they were kind of famous for supporting older commands and even just for single applications. And that's rough. And even some of the tooling that they would release for new versions of stuff would come with tools that would automatically go out and update your code or update your binaries to the new APIs, which is a lot of work for them to do because they didn't have a good answer to that evolution problem at the time.

That's just how it was. So documentation, we touched on that already. I do want to mention that there's different levels that you need to write for based on your audience so for example like if you're looking at like a node module uh the text that you get on there you know the couple hundred words that maybe you get on that page should be oriented towards people that have never used the service before and they're trying to decide which library to use and so you want to make it look as simple as possible and show them how to do the simplest tasks that they're probably there to do.

Now, the documentation that you have maybe on your website can be much more in depth and have to do with like each individual argument. What, you know, maybe this subtle nuances in what those arguments mean and why you might want to use one over another. That's a whole nother layer.

And that's not the stuff that you want to throw at someone who's never used your library before. So you need to be able to kind of have places that people can find for the level of their involvement, whether they're casual, just getting started, or they're ready to get into the weeds. And that's hard. So we're really talking about three different layers, right?

Like there's the about, what is this thing? There's the quick start, which is kind of like what I like to call it. Like if you get onto a good GitHub readme page for an API, and then there's the reference. And those are kind of the three pieces of documentation that I'm always expecting if I'm actually going to sync anytime into using an API. Yep. And depending on the maturity of the API, I'm sure you've seen ones where it's got, you know,

one or the other, like more frequently, it's probably more likely to have one that's got a real simple example of what you do. And then as soon as you go off the path, you're like, okay, well, this doesn't do what I need to.

It's like, well, maybe it's embedded in one of these 1100 arguments that you can kind of pass. And then you change one source code. Yeah. Yeah. And it conflicts with another. And then you change one source code. Yeah. Yeah. And it conflicts with another.

And then, yeah. What'd you say outlaw? I said, looking at you, Kotlin. Oh, man.

I mean, it was like, like you were talking about the documentation and it did make me think though, like going from like one extreme to the next, like, you know, the Kotlin documentation is,

is light, but then you get into the Kotlin documentation is, is light, but then you get into like some of the Python documentation for some libraries. Like I'm, I'm, I don't remember off the top of my head, maybe like a, um, a Pandas library, maybe that, or, or a NumPy library or something that was like super, like the extreme opposite where you're like, Whoa, there's too much. There's like so much on this page. Like, you know, you're scrolling, scrolling, scrolling, scrolling, scrolling. And all of a sudden you're like, wait a minute, suddenly I'm reading about another function. I didn't even realize I like went to another function yet.

You know, like it's almost too much in some places. Yeah. Yeah, there have been times where I'm like, I just need to know how to cancel an order. Like, well, canceling an order can be very difficult because there's different states and maybe some items have shipped. I'm like, no, no, I just need to cancel an order. It's like, nothing's shipped yet. Let me just see the most. It's like, well.

And so you end up like reading, reading, reading all over the place. And yeah. And so at the end of the day, you find the one argument that you needed to pass that does the thing you wanted. But it's just frustrating. Yeah, just change the verb to delete. Right? Yeah, done. So here's one I found.

So to prep for this episode, we went and found a couple of links for different places, like advising kind of how to write good APIs. And what I thought was interesting that came from uh microsoft actually was platform independence and what they meant by that was trying to stay away from uh the specifics of the platforms that you expect to deal with so for example you know we mentioned if you're like elastic and you've got the python api and they are you got a python module that you know people can go out and install and interact um They don't, Microsoft is advising you not to build the specifics of that implementation detail into the greater platform.

It says basically, you should keep your service as pure as possible and push any sort of details and try to keep as much as you can in those clients that are things that are specific to those platforms only. I like that. So like you shouldn't like, you know,

Elastic doesn't want to maintain a Python 2.7 version of their API, their server API and a Python 3 version of the API. They just want to have like, for example, a REST API and then, you know, have the Python libraries be responsible for doing that. Or let's say I know Python, not Python, Elasti has different ways of communicating. So the most common one you think about is the REST API, but they do stuff with like gRPC, I believe, internally as well.

And I think that, again, kind of the nodes can communicate with each other and do things via gRPC. But the actual APIs, the calls that those GR, GRPC commands are making, don't want to know anything about GRPC because if something better comes along next year, then they don't want to have all this stuff kind of tied in. Yeah, that makes sense.

So that was interesting. Uh, so now we're onto the fun stuff. So I Googled, you know, API design. I Googled how to write APIs. I wrote, uh, Googled a bunch of different things and OMG, everyone, every article on

like the first 10 pages of Google is assuming you're talking about rest APIs. Most of them don't even talk as if there's anything else until you get down to the third paragraph and you realize like, Hey, we're talking about verbs again dang it dang it y'all i thought you were talking about other kinds of apis but you weren't you got me and so i want to talk a little bit about why rest in particular is kind of taking over that term and becoming synonymous and i came up with a couple things that i think why kind of why that term is kind of combining a little bit. And I thought there might be a couple of things that we could even take away from rest and use in other areas because rest is so popular and people talking about rest is so popular. And part of that is just because it's really popular. So the reason why people are talking about REST API design

is because there are bazillions of developers who are working with REST APIs and running REST APIs. There are far less people working with SMTP, for example. Or I would say, you know, OData works, you know, it's got some carryover with REST, but it's much more niche. Or really the reason why you would say that REST is so popular though

is because it is so wide. Communication over the internet is so widespread. It doesn't have to just be about your website. It could be your iOS, your mobile app, and your mobile app might want to make a call back to some server to like log a statistic or, you know, get a user's, you know, high score or something like that. So that's why it's so popular because it's not, it's become so ubiquitous and so like the glue that's holding so much stuff together, you know? It's a low friction standard, right?

Like as opposed to soap back in the day with all its wrappers and XML and all that garbage, these things are pretty lightweight. Lightweight in terms of use, maybe not implementing, but the use of them is way easier than a lot of the alternatives that we dealt with for years and years, I think is really what it boils down to. And now you have like a native. What's it? What is it?

It's like, it's native to the internet. You know, it deals with these URIs, these uniform resource, you know, whatever locations, URLs, that are just meant to be used over the internet. So it's great for communicating with things over the internet. It works pretty well for local too.

Real quick. Sorry, just to finish that thought. You also have it as a first class citizen in some libraries. If you're in Groovy and you're like, Hey, I need a rest client, new rest client, like literally new space rest client. Boom.

I got a rest client. Yeah. So pop quiz, either one of you know what rest stands for without looking it up, sirs with computers. I think so. Is it a representation, representational state list transfer?

State transfer? State transfer. Very good. That's what I was going to say. Yeah, me too. And we could easily do three episodes just on what REST is and what REST isn't. Give it a rest.

Yeah. The thing is, it's funny. It's like my first kind of thought was like, well, rest is really popular because it's so easy to use. And then you start looking at people's best practices. And it would be like we found one list here, API checklist. And every single item on this checklist was like, yeah, you should do that kind of thing that I looked at.

It's 43 items. It deals with what kind of status status, what you call it, return codes you use for various problems. Like if the thing is unauthorized or if the resource wasn't found or if it's a legit error on your part or if it's an error on the arguments passed. There's a whole world of best practices that should be kind of taken into account. You don't get away with it. But then, you know, the definition of what is restful is kind of it's its own conditions, kind of controversial thing because of how it started and how people kind of use it day to day.

And so I don't want to go too deep on there just because we're really trying to focus more on APIs in general, but you just can't talk about APIs without talking about the elephant in the room. I mean, how many of these 43 do you do? Oh, not enough of them. Right. Some of them are just kind of normal. It's like, Hey, you use verbs like get head, put delete and make them in idempotent. I'm just so used to doing that. That's how I kind of think about it when I'm not doing stupid stuff. Authentication. Most APIs should be authenticated.

Some of them are just kind of obvious like that. The things like unauthenticated stuff, I get that from my framework. So if I'm writing Flask or something like that, then it's going to take care of a lot of that stuff for me. Like I'm relying on the frameworks to handle it. We mentioned versioning. If I'm going to be communicating with other people that I care about, I'm going to be doing a version. If I can't guarantee that's not going to be rolled out to the clients. So the real answer is that you don't think about these. Like a lot of these, the answer was, well, I'm assuming that my framework is going to handle clients. So the real answer is that you don't think about these.

Like a lot of these, the answer was, well, I'm assuming that my framework is going to handle it or the framework. I don't even think about that one. I just, it's something I, I, I just do,

you know, I'm going to make it item potent. So really the answer is like there's 43 on here. We don't think about them. We do. We have, we do have this link. So the thing is, I think the key is you should probably read the list to at least be aware of them, right? Like

we're not going to go through all 43 of them, but you should be aware of them because even if you're not thinking about them, a lot of times you're not thinking about it because you don't know about it. If you're not thinking about it because you do know about it and you know your framework handles it, fine. That's good. But you don't want to be blatantly missing something. The versioning is a perfect example. If this is something you want to be long-lived, you should probably consider that.

Yep. Have you ever hit the URL length limit? Yes. Absolutely. Yeah. Which is why you change everything to a post and you abandon rest like on day three yeah that's ridiculous uh yeah so you know the canonical urls there's definitely something here that there's stuff i have like i've thought about at certain times but not

the course is another example of something um i uh i think about it too much and I still suck at it. I still, I just don't get it. The cross origin stuff. Yeah. Yeah. All that stuff and different kinds of attacks and stuff. And so, you know, there is a lot to know.

And like, even though I'm sure we've all gotten API results that were 200 and then had an error message, you know, which is not considered a best practice. So there's a bunch of stuff like that that you should know if you're writing APIs. But then so many APIs do things differently

that you got to be careful about your assumptions, you know? So, yeah. And so I just wanted to kind of say, like, REST isn't really that simple, you know? No, it's not. So I want to mention... Oh, go ahead. I was going to say, it's just too easy to gloss over things yeah even that status thing like i i've seen that happen so so so many times

like oh i i sent you back an empty array but it was really you you sent me some bad parameters like that's not legit you're supposed to sit back and error say you gave me bad input so yeah it's too easy to overlook a lot of things yeah absolutely uh so some things that i mentioned here are great by design of rest so uh one protocol to support basically you're talking about going over http you know https of course same same basic principle you know it's that's it that's what REST is. So that's pretty cool that you don't even have to worry about it. You just use your whatever library in whatever language, and it's responsible for taking care of shooting that thing over through space,

over to the other side of the planet, and you don't even care. It just happens for you. Verb orientation, which, I mean, you have things like get post put patch delete we didn't really talk much about how uh rest is really designed but those are basically the different kind of methods that you pass in order to deal with stuff so um it's resource oriented by convention so you might say i have a customer api but the verbs that we pass from our clients are get, like get my customer or put, add a customer. Patch is like update. And so it's pretty cool that it's got these kind of CRUD operations baked in.

And there's a bunch of other ones that are less common. And like Outlaw mentioned, not always possible. So that's kind of awkward. And you can actually do custom verbs too, although no one does. And I would beg you not to do that. Like, honestly, when have you ever used a patch to do an update? If I'm working with like something that requires it, which is very rarely. What's the, I'm talking about, I'm talking about, I mean, like you're not using somebody else's.

I'm talking about you I'm talking about, I mean like you're not using somebody else's. I'm talking about rolling. You are writing the API and it's an, you want to do an action to like update a customer profile or something like that. I'm not doing it. Everything I do is post. That's what I'm saying. Like that,

that, that's what it ends up being defaulting to. It's like, you know, if it's a simple get thing normally, it's like if I want the URL to be shareable, right? Or, you know, you might be able to like, you know, open it up a new tab or something like that. Then get are very convenient for that because that's going to be the default of your address bar, right? Is a get. fault of your address bar right is is a git but post you know for anything that you want to like

update or write or whatever back to the server like it feels like that's just the defaults like everybody defaults to the like you know it's it's basically like everybody has this like silent agreement like okay i know that there's listen i know that there's patch and delete and put let's just agree to that she's getting post. Okay, that's enough, right? That's right. And that's kind of the way it works out. You're like, okay, whatever.

Totally. I've gotten my hand slapped for using some of these other verbs before. Yeah, it's smack hard. Open standards. So, I mean, there was a big big council that met some point in time and kind of decided what the standards were going to be and they laid it all out and everyone agreed on it and so um the c++ library does it the same way that chrome does in the browser does it the same way the postman does and this stuff just works across clients and uh what that means is

these companies and these organizations were free to build up these really big advanced tools like things like Swagger, which is a great user interface that will work for any REST API. And it's going to do a really bang up job. And it doesn't matter what kind of weird stuff you did as long as you kind of set that thing up, right, and make your stuff discoverable with the underlying language. It's going to work out really great. So that's really great. And it's kind of baked in to the protocol essentially. And I want to mention some things are great by convention, which means there's nothing forcing you to do this. Like you have to pass a method

when you're calling or resting. You have to, even if it's always get or always post, you have to pass it. You have to send it over HTTP. You don't have to orient around resources. That's best practice. So we said, you know, customers. We talked about orders. Those are places where you would want to have an API where the URL is slash orders or slash customers or something like that. And it makes it really easy to discover.

It works really well when you start talking about, like, you os which we didn't get into which is like really strict way of doing um this kind of like discoverable cool kind of rest where you can kind of link and browse and navigate between resources in a really cool way that's really strict and nobody does it i'm sorry i don't think i've ever seen it done yeah yeah i don't think so either you know i've heard rumors of it i think i think once uh i on the show i actually said no one does how do you ask and then i got like five emails of like five examples where it was done uh so hey you know say send me a comment i'll read them again and this time i'll remember i swear so So human readable is really nice. So JSON is part of the standard.

You don't have to do it that way. You can do other stuff. You know, actually, let me double check this. This is one of the things, sorry, I had it under the convention soon. So JSON is what everyone's using. It doesn't have to be. And I'm sure you've probably seen APIs where you would just pass a string in the body or something like that or you do stuff in the query parameters so there are other ways to pass arguments but for the most part people do json and that json works out really well as a human

because i can look at logs and see what went in or i can replay things or i can work with tools like postman and really easily and kind of see uh what that's like when we talk about avro which is binary format not so human friendly right uh protocol buffers that's uh used commonly with the gr pc maybe maybe always but uh you can't read it as a human you need a tool and schema to tell you how to parse that that's a that's a pain in the butt and somebody's going to say like yeah but you how to parse that. That's a pain in the butt. And somebody's going to say like, yeah, but you could like return back or send or return XML back. And then in that case, you're using soap. Yeah.

I mean, it's pretty, pretty much there. Yeah. There's some other stuff along with soap that gets, it does feel gross. Like you should like that. It goes back to like, okay, I guess it's, it's like, technically I can read the letters, but it's, it's like technically I can read the letters, but it's,

it's not as easy to read. It's, it's so verbose and gross that it like gets in your face and you can't read it. Yep. Totally. Totally. Yeah. Yeah.

Soap is a whole nother can of worms here. And luckily, uh, we don't have to think about them too much, uh, statelessness. So this is another one of those things where like, uh, representational state transfer.

So the original design and intent for REST was for things to be stateless, meaning that you. What's a good way of saying this? The call could happen on any number of servers. It's going to do its thing. The operation is going to be atomic. There's no sort of carryover. In practice, this is the kind of thing that does not happen all the time so you'll see a lot of times where an api will have like a login method and you can do stuff and when you're done you either say log out or if you get timed out your token times out you might

say re-authenticate and so this is an example where that's stateful means there's some server out there that knows who you are knows what you're doing knows where you are in the process and that's really important sometimes because sometimes things you need to do are are stateful means there's some server out there that knows who you are, knows what you're doing, knows where you are in the process. And that's really important sometimes because sometimes things you need to do are stateful. If you're working with the bank, you know, you need to make sure the money's there before you do it. You may need to put a lock on the account before you withdraw the money and then unlock the account. So other transactions can take place, you know, things like that. Those are all stateful type things and sometimes you need to do stuff like that so if you're buying uh tickets for a concert and you're picking out your remember we have those you're picking out your seats it's important that some of those operations be stateful and it's okay to want to do those over rest that we're talking pre-2020 right yeah pre-2020

back in the day yeah and yeah we mentioned how we mentioned Hadeos, which is really nice. And one thing that's nice about that is it really pushed sending resource links back. So you would say, hey, slash orders, get me my orders. And Hadeos would say, okay, here are links to your orders. And you can kind of click in or you know use these links to retrieve more information about this and you can drill in maybe there's a customer link and maybe there's an order link or an address link or a product link or a shopping cart link then the shopping cart link has links to the products and the products have links to the pictures and it's links links links

links so it makes it uh very easy to kind of and navigate, and it makes it really discoverable. And what's really cool about that is you can build these clients that are kind of dumb about the stuff that they're interacting with, but they can kind of just crawl out and find the things they need. And it means if things move, if resources move servers, it doesn't matter because they're always just getting these links back, and then it goes and fetches the next piece of data from those links. So there's some really cool advantages there, but unfortunately, it's just really complicated and hard to do, right? Don't at me. We just can't have nice things. That's really the takeaway from all of this.

So here is my sales pitch. I always like to have something, some crazy thing. I'm kind of trying to push some agenda, some crazy thing. I'm kind of trying to push some agenda, some secret agenda. What is the new get? We all agree. Totally. Little D doctor is the new get. So maybe there's some really good ideas from rest, some things,

some patterns that have fallen out over the last couple of years that have fallen out and become standard because they're just really good. And we've seen some things like the resource orientation that has leaked out of rest into command line tools. Like we talked about the Kubernetes API being resource and verb heavy. PowerShell was the first time I saw something that really had this kind of noun verb thing that was really strongly enforced. Maybe it's not the first thing,

but it was up there. We talked about theithub cli tool if it came out today yeah powershell has examples when you said that i'm like every commandlet is verb dash noun oh okay get dash content now get dash item yeah see i was considering that one thing but okay fine well yeah and i always use the aliases, so I kind of forget about it. But every single commandlet is always set up like that. Okay. You kind of pipe things together, and it just has to deal with it, kind of how it navigates. And so it's just really interesting to see that those ideas have kind of

filtered out, and verbs are just built into REST. So it has to be that way you have to have the verbs but in practice it seems like it works out pretty well so there's other things you want to do in kubernetes is a prime example where um you can scale deployments but you can't scale pods for example uh you can uh describe resources uh you know we use kafka connect a lot we talk about kafka stuff all you can pause connectors or you can start connectors and do these things and the api is set up to let you plug in your own nouns and verbs but you have to do with nouns and verbs you can't give it sentences of stuff to do so i'm thinking what if we could just steal some of the best ideas from rest

and use them in our other api so if we're building command line tools maybe if we could just steal some of the best ideas from REST and use them in our other APIs? So if we're building command line tools, maybe if we kind of borrow this resource verb kind of setup, it makes for really good experiences that people are used to. Maybe if we're building software libraries or this way it makes it just easier for people to use because it seems like this pattern is popular because it works so got a couple notes on that so if you organize your api around the resources and your behaviors or your actions are the verbs so instead of having a class with a method like create order, maybe you have an order with a class called, or sorry,

you have a method, a method called create. And that just kind of seems like good. Oh, design to me, doesn't it? I like it. Yeah.

So now, you know, if you start looking at, you know, at you know oh is it one of those kind of like loaded terms where maybe or really you should go through your object factory and you know whatever and kind of have that call to create and whatever so it you know it gets complicated and uh down in the weeds but as a user i i've never been happy about seeing a factory i've never been happy about seeing a builder if there've never been happy about seeing a builder. If there's a mediator, you know, get out of here.

Right. You know, even events is kind of clunky. But if you tell me there's an order object and it's got a create method on it. I know what to do with that. So maybe that's a cool way of setting things up if you can. And, um, so you're advocating for like in your object oriented world that you would have all of that functionality in the class itself. Yeah.

So class order method create. So now, so now that class becomes rather complex because it has all of that functionality along for the ride. Whereas if you take the string builder thing, then the output is the string, which is a simple data type. Yeah, so this is not a hard and fast rule. But what you're saying is you're totally right and uh obviously if you have like an order object that knows how to create itself in a database or how to save itself in a database or delete itself from a database like oh that's very much getting

away from a single purpose of representing the data but what i'm saying is if you're making a public api or you're making an api other developers, why don't you hide all that complexity? Hide the services, hide the dowels, hide the data classes, and try to create them the most simple API that's oriented around the resources with that ubiquitous language, those bounded contexts, all the things we talked about with triple D design or with design driven development to, to make it so that they can interact with your code and the way they think about things. Cause they think about canceling orders. They think about creating orders. They don't think about order services.

I mean, I think another way that I would like to think about this, at least in my head though, is that this, this pattern of command verb noun, you know, like it's leaked into a lot of popular tools and, you know, we've all become fans of, right? So, you know, we're mentioning Kubernetes, you know, kubectl is one of them. But there's really more like even NPM, for example, does the same kind of thing, right? Like NPM run test or run build or whatever,

like depending on like how you have your thing configured, right? That quote noun is going to be something that you configured. So, I mean, I kind of like that approach because then you can think about this quote, like API doesn't necessarily have to be a web. Something that you're going to do with the web, right?

Right. And so we talked about some command line tools. Oh, crap, I just forgot what I was thinking about. Oh, I was thinking Docker. So there's Docker, you can do Docker images LS. There's other ways to do it. If Docker came out 20 years ago, maybe they would only have those little aliases they have now.

You can do Docker RMI to remove an image, for example. Maybe they only would have had Docker RMI. And who's Googling for Docker RMI when they want to remove an image, for example. Maybe they only would have had Docker RMI. And who's Googling for Docker RMI when they want to remove an image, right? But they set it up as a shortcut. But that's how things were designed like 20 years ago. You kind of had to learn their language in order to learn their tool. And people were expected to spend more time up front learning. But nowadays, you're kind of expected to be able to Google your way through something as quickly as possible.

And so that's why Docker, I think think has a more standard way of doing things. We've got the shortcuts there for the power users, but you can also do Docker image remove. I think Docker image RM or images list. I don't think I'd ever thought about it from the searchable standpoint, but that makes a ton of sense. Like, yeah, never even occurred a ton of sense. Like,

yeah, uh, never even occurred to me. Yeah. Helms, the tool I've been thinking a little bit, a lot, um, a little bit lately.

So, uh, I do not like Helms, uh, Helms, like language, the way their, their command line tool.

And maybe I just haven't spent enough time with it. I'm not trying to diss it. I'm just saying it's been frustrating because I'll do stuff like i just want to see like the rendered templates that are installed somewhere i still it's like helm show something i forget i forget how to do that like but it's there helm knows about it it knows how to get it i just don't know how to whatever or help upgrade dash dash dry run yeah yeah there's just been stuff on what was the uh trying to search for something i was like okay i know the chart so you know here's the url for the charts you go there in a browser it looks different it's a web page because that's like

index.html it's meant for humans and uh your your helm your your computer interacts with index.yaml which is this kind of hidden page that it knows about like your command line tool but it's kind of hidden from you normally and so you know i figured out it's like fine okay so there's index yaml what what's the name of the chart like because for some reason i was trying to do something i couldn't figure out the name of the chart and i just had a really hard time and the way you're supposed to do it is you're supposed to first helm add the repo and then you do home search and then type your repo name and then it searches all your repos for that one and that seems goofy to me it's like no i know it's in that repo second i don't even want to add it i want to pass the whole path i don't really like the idea of adding this thing

and then i have to remember to go remove it later because i'm trying to just get the url for some other system why do i have to install this repo location to my local computer because I'm trying to just get the URL for some other system. Why do I have to install this repo location to my local computer? Because I'm trying to look up something for somewhere else. But the prescribed way to do it is like, no, no, no, just add it to your list and then search for it and make sure you get the one that's in the one you need it and then remove it after you're done. That's a really bad user experience, you know, in my opinion. And maybe just because I don't know a better way to do it, but that's an example of a tool where I would love if it was more resource oriented where I could just say helm repo, give it a name list would have been fantastic there. The helm, the helm search repo bit me like, uh, and we, we talked about that back in episode, um,

what was it? Episode one 45 where, uh, I'd specifically referenced that because that, that command is weird. Like it doesn't, it wasn't what you thought it was, but then when, or it wasn't what I thought it was. And then when I realized what it was like, Oh, of course it's that way. Like, and now I don't even remember the case, the use case that I was running into at the time. But, um, yeah, I mean like there there's, there's a other, like even, um, you know, scaffold follows the same kind of, you know, uh, command, uh, verb kind of format. Um, you know, of course there's the granddaddy get, uh, does it to, you know, which of course granddaddy, um, but even like other Linux commands, you know, a lot of other, um, APT or, uh, apt get, you know, was

the same thing. Um, but you know, you were talking about like some of those that make it like difficult to do certain things. Like the one that came to mind for me, I don't know if you guys have ever tried this, is like when you Docker login into a particular repository and then you're like, okay, I just want to see like a list of all the repositories that I'm authenticated to. What's the Docker command to just list those things? No, you cat the config file. And there isn't one. There isn't one. And catting the config file is going to be the answer that you're going to see. And that's not always going to give you the, what you want to see,

because depending on what your credential store is, you might not have anything listed in that file. Oh, interesting. Super frustrating. Yeah. No. Speaking of, um, kind of frustrating experiences, you ever tried to, uh, like app get install something before you do like an app get update. Oh man. All the time. It's like, well, it doesn't seem like you should have to do that but it's a it's an example of like a stateful operation we have to do something first before you do something else although you might not get the results you expect even though that something else that you have to do seems unrelated that's why like all the commands are always app update and an app get app blah, blah, blah, blah, blah. Absolutely. Yeah, so a couple other things I mentioned here.

So we talked about nouns. Nouns can be complex. You know, we mentioned orders. Orders can have products, addresses, history, all sorts of stuff in there. They don't have to be the tiniest little atomic units. You know, you can build up these abstractions and you build up this language. We're getting back into um the ddd um which we had some episodes on that somewhere at some point driven design

doing driven design yeah i've got the book back there uh so collections if you want to get more than one order you can have a collection object which basically would have you know a bunch of rows you know you want to, of course, from like if it's a database or something, maybe you want to kind of hide those details and have it not look like rows from a database. You want to have it be those objects. And this is the thing I've been guilty of for a long time. We'll get there a little bit more in detail, but I have had and probably still have a bad habit of like returning what I need for my view if I'm working on a website and not necessarily the objects.

There are various reasons for that, but it's inconsistent and it's bad from a user experience. Luckily, in my case, I'm usually just harming myself, and so it's not a big deal. So you're saying like, instead of, instead of like whatever your view layer is, uh, instead of returning just the data for that view, you should just return back like maybe a generic object and then the view can decide how, what bits of that object it wants. Is that what you're describing? Yeah. And like a perfect cat EOS, you know, by the book world uh you would return uh basically kind of these uh these roots of objects and you have links they can go to fetch more information about those individual

objects so what i'm saying is like in kind of bad practice that i would normally do is i might have a arrest quote unquote method named get orders for user and i I give it one user ID, one customer ID, and then I go get all the orders from it with the information I would need to display on it. So in one call, I'll pass in a customer, I'll get back an order.

And that order will contain maybe dates and the address of the person who was sent to and the count of products. And that's convenient for me because that's exactly what I need to display on my web page. But what I'm saying is that's bad from an API standpoint because it's very purpose built. And if you need to have any deviance from that, like maybe you need the product images or maybe you don't care about the addresses, in which case I'm returning too much information. Then you have to make a choice of basically whether to try and build your own apis or find some other apis that are more appropriate or you need to go modify what's there or you just have to deal with getting back more information

or you have to make more calls what so i'm saying is in good api design that would be more granular so you would be more specific about what you're fetching but it it's more work. Well, that's why I was asking, like, if you were talking about like, uh, more returning back, like a generic object, like, um, you know, like maybe you want to display a list of usernames, you know, first name, last name, and their account name. And were you describing like, Oh, in that case, instead of just returning back, uh, under a list of those three columns, instead you would return back the full user object. And in my mind, I was thinking like, that sounds awful because now you have these giant payloads

which would go against everything that GraphQL is trying to solve. Where it's trying to go the extreme and just get you exactly the bits of data that you want and nothing more. I actually had a couple of questions here I was going to ask you all at the end here. And we kind of hit on them. So one was like, why wouldn't you just return the whole objects? And it's because it's really inefficient. A lot of times you don't care about most of the information you have about the entities.

You only care about the very light information, like maybe the status and the name or something like that. Or maybe a location to do a picture. And how do you go? Well, you know, strictly speaking by the book, you would say, get me the users. Maybe have some sort of, you know, search. That would be fine. Where you pass the. No, that's not true.

I guess I would say, give me the customer and maybe it would have links to my orders because there's a relationship there and then I would go to that link for the orders and that order would have links to each individual order and each individual order have links to the products which I could use to. And so, I mean, you're making tons of calls at that point, which would be terribly inefficient. But the big difference is, right, like in Hattie OS, the smarts are on the server that's returning you the data as to where you go get it, right?

Like in your typical client, you say, all right, go get me the customer information. All right, now I have the customer ID. Now go get me the order information. Now I have the order IDs. Now go give me the order details from the order IDs, right? The big difference is instead of the client having the smarts on knowing where to go ask for the next bit of data, the server just gives you and says, yo, if you want the order details, take this link, right? And that's really, it's flipping the responsibility of how to get to the data.

And it is, it's way more difficult from that other perspective, I think. Yeah. And that's why Adios is not popular. Yeah. Because now you've got to keep, I mean,

we've talked about this in the past, but without going too deep down it, if you maintain a product database and one of your products is no longer a product you carry, what do you do? Do you kill that link? You kill that link anyway that bookmarked it, it's going to fail. So now you've got to keep links that will work for your new links. It just becomes a bit of a mess. Whereas if the client just knows how to navigate your APIs, then it makes things easier. So, yeah.

Yup. Absolutely. So, um, and then we kind of touched on like, why would you want to use purposeful APIs, which is kind of like what I've been kind of arguing is like bad design. Uh,

you, cause it's not resource oriented. It's not verb oriented. It's basically like a sentence. It's a verb-oriented. It's basically like a sentence. It's a very specific action. It's super convenient. And by the Hadeos approach where you kind of like go get resource and you go spider out and get more resources,

databases are really good at that already. So it's like we're re-implementing a database via HTTP. No thanks. It sounds like a terrible idea. And so that's where something like purpose-built stuff comes in. So maybe you want to toss it to a store procedure, which is also debatable. There's all sorts of stuff you can do in name of performance.

So I think that the biggest reason why you would want purpose-built APIs that are very specific to your needs is just for performance reasons. Or lazy. Yeah, lazy. Let's be honest yeah it's it's lazy uh so uh another one i mentioned is consistent naming because of the resources and now things you kind of get that for free if you're doing things the normal way uh and so you know it's kind of nice that all your gets are gets typically all your posts are kind of closely associated with posts. If you're using a good API,

I mean, that's something we can take away for when we're building other things. Like maybe, um, maybe we should have methods for get ID, get name, get whatever, rather than having properties,

because it's very easy from a customer standpoint to say, get and see everything that they can get back i hate that but something to consider if you're trying to make things easy you know it's very clear as to what's happening coop cuddle get pods yeah it feels great it's annoying when you type it you know what it's always bothering me some you get pods you get services you don't get logs, right? I know that drives me crazy. I've typed that a million times.

And even then it's like, say, okay, fine. I'll get logs to give it the pod name. And that works 90% of the time, unless you got two containers or more containers. And it's like,

then you got to specify it. So yeah, that's those, like those little rough edges that are really frustrating, but it makes you realize just how unfrustrating the rest of it is. Yeah, agreed. So Microsoft, we've got a bunch of resources, by the way, for this. They recommend plural nouns in most cases. But again, they're skewing heavily towards REST, and Microsoft was actually the page

I found that was the most unfocused on REST. But this is the case where other examples were basically saying slash orders or slash customers with a number rather than slash order or slash customer. So that was kind of interesting. That just reads weird.

Yeah. Especially, so you think about PowerShell, get-host, get-content. It's not dash host get dash content it's not get hosts it's not good contents but that's also cases where there's only one of the things so i don't know i mean in their particular case though i could i could make the case for why they would do that why they would do it that way because if you like they had slash orders and slash orders one two three and slash orders one two three status or something like that but where it was like okay you could make

the argument that slash orders would just take you to all you know would take you to a list and so that that would need to be plural and so now it would be weird if you wanted to drill to a specific order if you had another route that was singular slash order slash, you know, one, two, three. So if that's where they're going, but also, I don't know. I mean, like routes are cheap, so who cares? Well, routes complicate your client, right? That's the problem.

If you're dealing with an order. Yeah. If you're dealing with an orders entity, we'll call it, you don't want to have to know whether you're dealing with one or more or whether I need to call order or orders or, you know, it just gets complicated. More complicated than what's necessary really is what it is. I guess what I'm saying though, is that like more often than not, you know, uh, I'm probably thinking like maybe something too specific, but I'm thinking like, Hey, if I have an e-commerce site and you know, cause we're talking orders here. So if I have, then I'm probably going to

have more often than not a lot of things that are going to be done against a specific order. So slash order slash ID, right? And to me that makes a lot of sense because I don't have a bunch of things on it, but slash orders, I'm probably not going to do, I'm not probably not going to let the customer do a whole lot, you know, view them, but they're not going to, I'm probably not going to let the customer do a whole lot, view them. But I'm not going to let them bulk cancel orders. They're going to go into a specific order. So I don't know. I mean, if you got to pick one, I get part of their reason for it, but I don't know that I'm too much of a fan for it. And if you didn't, I guess my point

is, is like if you had a slash orders in a slash order one, two, three, I'm not going to be mad about it. I will. So I like the plural, at least some. So working with Kafka, like say the schema registry,

which as much as I like it, they've got some custom terms that are kind of frustrating. So you go slash subjects and it lists all your subjects for all your schemas. And then from there, you might pick one. So copy it out of the array string, paste it up in the URLs. And now you're saying, okay, get me the subjects and you pass the thing. And then you get a list of all your sub or sorry,

you get a list of that subject and all those versions and then you take the version number and you copy it and you do another slash. And so what, um, what it feels like is I'm drilling in, like I started the subjects, I got the one I want, I found the version,

I got the one I want and I went and past paste it. And so I, at every time, every point I added a slash and added more information and I got further and further. And then I can go in there and say slash cancel or delete or whatever. You don't do slash delete, but you can do some extra stuff

there. But it just feels like you're drilling in which just feels good as a human and as a programmer because it's very obvious is what you're doing after you get used to the weird terminology. Yeah, I like that. You're following the path. I get that. And that's why I was saying very obvious is what you're doing after you get used to the weird terminology. Yeah. I like that. You're following the path.

I get that. And that's why I was saying like, you know, with this one specific example that was, you know, kind of commerce driven. Then it, you know,

yeah, that's why I was like, ah, I don't, in that case, I don't know that I care, but you know, other cases,

yeah, fine, whatever. I'm not going to take the, the hard line stance either way i guess my point like you know on a case-by-case basis i would you know depending on what your applications purposes and whatnot then you know do what makes sense for your need yeah and i'm fine with either way it's just kind of nice to have a preference you know for microsoft so you can say like, if you're designing a new API today and you're like, Ooh, should it be a person or people, you know, then it is a vote for people, you know,

that's a terrible example, but now, you know, would also, I mean like what, where this also reminds me of is like table names. And I think we've talked about this in the past. Like, should your table names be singular or plural? Is it a table of users or is it a table

of user? Of user objects. Right, yeah. I get both arguments. I've always liked the plural better. Definitely for tables. I do, yeah. Just don't mix. Yeah, right, yeah. I get both arguments. I've always liked the plural better. Definitely for tables, I do, yeah. Just don't mix. Yeah, don't mix. Oh, for the love of God, do not mix.

All right. So general guidance is return whole resources rather than, or rather resource identifiers rather than whole objects. I don't know how I feel about that, applying that to other APIs. The only thing that works really well on the web because it's like you already know what the next call is and how they're going to do it. So I think that is kind of unique. So I think that's a kind of example where we probably don't want to take a note there from REST. So a couple of

pieces of guidance here that we might want to steal from rest. It looks like I kind of got my notes mixed up here a little bit, but basically avoid introducing dependencies between the API and underlying storage. So that's an example there where you might be tempted to return a data table where REST API and C-sharp data table is like an object that's closely related to like the output you would get from a database for example and so

that's something that you wouldn't want to do because I mean you're going to get back rows and columns and so it's convenient to do that for the server side program and the 30 minutes that they save converting it to something more generic but it's it's just got stuff that doesn't server-side program and the 30 minutes that they save converting it to something more generic. But it's just got stuff that

doesn't make sense to the client, so it would be better to keep that more pure and hide that abstraction. Verb orientation is okay in some. In this case, Microsoft talked about a very specific kind of API. I thought this was interesting because depending on what your library or whatever you're doing is, this might be something to consider where we talked about things being resource oriented and saying that's generally pretty good.

And it seems to work really well in most cases. There is a case where you want verb orientation. And the example they gave was a calculator. So if you have a calculator object, I want to see methods like add a take number one, number two, I want to see divide. I want to see, you know, whatever, uh, absolute value. Those are cases where there is no resource. I don't want to create a number object, say calculator dot number given number four dot add give it another number that's ugly it feels bad so this is kind of a new case where if you've got something that uh is very action-based you might just want to skip the nouns now i want to create a whole new api for you

yeah go to slash four yeah you like that you see a big number four now go to slash four. Yeah, you like that? You see a big number four? Now go to slash four slash add slash two. Have you ever seen those post-fix calculators or whatever? They have stuff like that. It's miserable. I haven't seen that. No? Oh, man. Yeah, you can get...

What are the different kinds? You've heard of computer sciences like post-fix, infix, prefix, or whatever. So you would do four, three, computer science is like post-fix, infix, prefix, whatever. So you would do 4, 3+, if it's post-fix. And the computer would know, like, it's basically like a stack. So it would push 4 on the stack, pushes 3 on the stack. It pushes plus. Ooh, that's an operator that tells us to pop the 2 off the stack and add them together.

And now it pushes the result of that 7 onto the stack and then keep on going. So it's a really efficient way of like doing say math, for example, where it kind of builds up as high as total aggression. But anyway, it gives it,

it gives it a way of kind of like accumulating stuff and kind of building along through complex expressions that are coming in, um, which works out really well for the computer. But as a human, you don't want to see like four, three plus open, close minus sign to brutal.

You're like, what? Yeah, it's just tough to read. So yeah, that's about it. So, you know,

we kind of talked about the other questions I had here. There's one other question, which is kind of unrelated to everything else, but I just wanted to kind of ask it because I feel like it needs to be asked. Uh-oh. What happened to GraphQL? I miss it. I know. It seems like such a great idea.

A couple years ago, it came out. We thought it was awesome. Then a couple more years later, it was like, holy cow, this is really going to take off. People are using it. Companies are doing really great stuff with it. It feels great as a consumer. A couple years later, it's like, wait where's this graphql future i was promised yeah wait wait has it gone away though i don't know that it has i mean i think what's changed is in the past year and a half there's been no conferences or anything because i can tell you every single um you know

conference or whatever that we go to there were there were tons of people talking about graphql and how to make it better and how to make it work in your environment and do all that and i just i don't know i just don't think we're exposed to the outside world of dev is what we were you know a year and a half ago before the pandemic hit. Yeah, we talked about Hasura. We talked about Gatsby and the last two things. And I saw a bundling GraphQL making that a first graph. Citizen Dgraph was a graph database.

We looked at it a little bit. That was built around GraphQL. That's several years old now. And there have been APIs that I see coming out now that I'm interacting with. And we mentioned RapidAPI. old now and there have been apis that i see coming out now that i'm interacting with and you know we've mentioned like rapid api rapid api doesn't have a big graphql banner on their web pages they're not pushing it so it makes me wonder it's like uh do we miss the boat on that is was it just too hard to do on the server am i just not you know working on the front end as much now so i'm not seeing it but it really seems like I'm not seeing companies pushing GraphQL anymore. Yeah. I mean, I don't really know the answer, but I can tell you this,

at least from my perspective, in terms of everything we talked about on this, like with the rest thing, like the, the orders, the customers, the, you know, the order details, all those separate rest services, those still make sense to build in that way. But as somebody that's building a client to go get that information and display, man, it really still, to me, makes a lot of sense to have a GraphQL wrapper around those existing REST services if you want to do it over the top of those. And hey, me, Mr. Client, I want customer first name, last name, and I want the total of the last five orders, right? That's just so beautiful. Give me what I need and nothing more. I don't want anything else coming back. I want to tell

you the graph of information I want. It still, to me me was such a beautiful way of handling getting data. And even their actions, right? Like GraphQL did support verbs. So yeah, I don't know, man. I hope we didn't miss the boat because to me, it was one of the more enlightening ways of thinking about APIs that I'd seen in years. So I was curious, we got some data.

And so I looked at, so here in the Atlanta area, one of the big conferences is connect tech. And I was curious to see like, Hey, we, you know, what were the recent GraphQL talks? For the 2020 Connect Tech,

which they did have, there was a talk on GraphQL. Really? When? The year before there were like 10 of them. I'm like, well, that's just Atlanta, right? So maybe Connect Tech isn't the best way to measure that, right? Maybe I should look at, you know, something else. So then I'm like, okay, let's just go to straight JSConf, right? Which, you know, have one for 2020, but in 2019 there was

a talk on GraphQL. Really? For the USJSConf. That seems crazy. Maybe it has passed? Maybe it has passed.

Maybe it was proved to be too... Maybe it was ahead of its time and was too difficult to implement. And so in 15 years, we'll be like, oh man, there was this technology that we didn't even know how to use. And now here it is. Because things like that happen. Yeah, possibly. So in 2019, the state of JS had a

survey about it and basically whether people were using it. Maybe they changed their URLs, but it's not on 2020 or 2021. So I'm trying to search those to see if like, well, 2021 is obviously not going to be out yet, but yeah, I'm having

a hard time finding the same question on 2020. But if I look at the 2019 stats, it's, I mean, it's growing. So the biggest one was 50% said they have heard of it and they would like to learn 5% and 2%. So we'll call it 60% have heard of it and they would like to learn 5% and 2%. So we'll call it 60% have never used it. 2% said they've used it and would never do it again. And 38% they've used it and they would use it again. And it's, I mean, the chart, the graph going up from 2016 is moving up,

but it's not exactly exponential. So that was my kind of thing. I was like, I was googling around it seemed like GraphQL really has all the good stuff that we liked about kind of REST and it's also really consistent it's a great user experience

and it's something that can be tacked on with a REST endpoint fairly easily so why why aren't we seeing this when people are talking about design? Maybe it's just because it's so easy to do. I don't know. Man, I don't know.

That kind of makes me sad. Yeah. Did they really not ask about it in 2020? Well, I mean, if I'm reading the 2020 state of JS, right? Like I,

it is there, but it's in the quadrant of have not used, but positive opinions. Okay. And, and like all, all, you know,

previous years it was too. Yeah. So it's, it's gaining velocity and it was too. Yeah. So it's gaining velocity, and it's close to crossing that line to get into the have used. But I don't know. Maybe it's just a myth. Maybe GraphQL is a myth, and really only Facebook is using it to any great degree, and other people might create some libraries for it, but it's not really a thing. I don't know.

I found the same graph that I saw in 2019. And so in 2019, they had, what did I say, 38.7% would use again. In 2020, it went up to 44% would use again. In 2020, it went up to 44% would use again. Interested went down from 50% to 43%, but some of those, it's just because they went up. It's just because people started using it. How many of those

are Facebook employees? Yeah, that's a good question. So it's going up, though. The trajectory, if you look at the graph, it's going up though. It just, the trajectory, if you look at the graph, uh, it's not as steep. So it kind of was going up really fast and then the growth rate slowed way

down. So it's still going up, just not, not steep. Yeah. All right. Well, let us know.

So, uh, I guess graph QL is going to make it is the answer going back to the question. That should have been the survey. And on that bombshell, we leave you with a bunch of resources, links to resources we like. And we head into Alan's favorite portion of the show. It's the tip of the week. And I hope

we didn't do this one yet. But I recently in the last couple weeks, we started running Kubernetes in WSL2. Have we done this as a tip yet? I'm going to wait to see where you go with it and then I'll tell you the episode number.

Okay. So it's been going really great. I've been using Minikube with it. You don't have to. You can just run it with Docker and Scrum built in, but I've been happy with that. And the trick there, I feel like this part of the tip has been probably done,

but if you check out from GitHub, or whatever you're doing your Git clone from, you check out from GitHub or, or, you know, whatever you're doing, your get clone from, you check out into the file system for WSL, then everything is so much faster and so much better. Just going to WSL two and using that for, you know, Kubernetes is a pretty big jump in improvement.

It just runs better in WSL, specifically WSL two than it does under WSL one. It's runs better in WSL, specifically WSL 2, than it does under WSL 1. It runs better than it does on Windows. And if you do your clone... That was episode 156. Okay, cool. So we got that one good. WSL 2.

So then if you clone it with Git into the virtual file system for WSL2, meaning like you go to CD tilde, you know, your home directory in Linux, you get away from the C drive, you're cloned there, and then use your file system from there for Kubernetes. Then things are even so much faster still.

Wait, that's what I'm talking about. That was also in the last episode, yeah. That was the previous episode. Okay, fine. Then Minikube is episode. That was the previous episode. Okay, fine. Minikube is awesome. Surely that's not a good one. It was in all seriousness

though, I did mention it and I shared the link. There was a Docker article of Docker best practices. Specifically the title is Docker Desktop, WSL two best practices. And I talked about how, if you do, if you do everything inside of your WSL file system, then it would be faster. And the cool thing is, is that WSL two exposes a special network share that you can access it from windows. So if you did have a need to use an editor

like a visual ide um and you wanted to access that file system you can i think i got this from you yeah probably okay fine then definitely you definitely don't know this one so once you do your clone you do code dot you know types, types, it opens Visual Studio Code. It will automatically detect that it's a remote file system. Dang it. It's installed a plugin for it. Yeah. I actually used that as the lead in because I said that you could do that.

Jeez. Which works fine for Visual Studio Code if that's your visual editor. But if you wanted to use anything else, that's where that special path comes into play. Okay, well, did you know when you use Minikube to start up your new cluster, you can have multiple, so probably you can name them. You can easily just pass dash dash

CPUs and dash dash memory to easily specify the memory. And when you shut down that cluster and start it back up, you can even choose different numbers. There you go. That's a good one. I like that. Much easier than Docker.

All right. So, yeah, I mean, do that, whatever I just said. Just write it in the notes so that we don't forget it. And then, yeah, that's your tip of the week. The other stuff was just a reminder of previous tips of the week. In case you're new to the show that was a great tip of the week you just got like four you're welcome i didn't mean to snort so loud we do this so late at night y'all i think one of those at least was during the day

the hilarious bit about that though is that like when you said, when you said that, like, I don't know if we're talking about this and I was like, don't worry. You say it. And I'll tell you, uh, the episode number episode.

I was like in my mind, I was already like, I'd already picked an episode number as a joke. Oh, not expecting that. It would literally be the last. We promised he was there for it. Okay.

Well, um, yeah. So with that, uh, I will give him my tip of the week that has not been said yet. Uh, or, or maybe it has,

it could be, I'm not going to, we'll see. I'm ready. You tell me, you tell me he's got his episode search. Yeah, here we go. Here we go. Uh, so, uh, my, uh, my wife has, has turned me onto this new, this podcast new to me podcast that I have just fallen in love with. Uh. It is just so well told. So it's by Wondery,

which if you've ever heard of any of their other podcasts, then you might know from a production quality what I'm talking about. But the specific podcast that I'm talking about is American Scandal. And it is just so entertaining. Every quote season is just like a handful of episodes. So, you know, a whole story might be, you know, five episodes or something. And they'll talk about it. And then the last episode of that series will be like with an expert just kind of describing like what was going on during the time

or whatever you know like why this thing mattered but just the production the audio quality the use of space and sound as they tell stories there'll be dramatic parts

of the story where they'll like retell things or conversations. And, you know, there have been times where like I'm sitting there alone in my office and, you know, typing away and then listening to something and I'll hear something, you know,

in that sounds like it's off in the distance on the right hand side. I mean, what was that? Only to realize like, Oh, that was from the podcast. Like it was, but it's just, it's mixed so good. So I highly recommend that. Stories are really interesting. You know, they'll give you like an insight into a particular story,

you know. So one example might be, there was a story on big tobacco and the, the lawsuit that happened in the nineties and some of the things that were going on around that, for example you know, the, the, the lawsuit that the state of Mississippi had against the big tobacco companies and you know what led up to it and like the, the ramifications of it,

it's stories like that. It'll be some big story that happened in the U.S. at that time and why it was a big deal. I'll have a link to that. Then we got an email that we talked about JetBrains tools in a previous tip of the week. Um, I don't remember the specific episode that we did, but, um, Rasmus wrote in and he was like, Hey, specific to data grip, there are some awesome things that we did not mention. And so, uh, he, he called these out

and I thought, you know, Hey, we should, we should definitely mention this because these are pretty awesome. I didn't even know about some of these. One of them is if you have other JetBrains IDEs, like say a WebStorm or an IntelliJ or something, and you have a DataGrip license and you add a data source to that IDE, then that IDE magically recognizes your strings inside of your code,

be it Java or JavaScript or whatever. It recognizes those as SQL and will give you syntax highlighting and auto-completing. So that's awesome. If you were in your Java file writing in a select statement, it would give you the proper syntax highlighting and and autocomplete i love that although i would recommend that you not write sql inside of your java i was gonna say there should have been a warning that's fine there really should be uh but here's another one though that was super awesome because i think i talked about in the past that in like say a data grip,

you can highlight the, like a specific server or even a database within a server and you can give it a specific color. And then any tab, any query tabs that you have or consoles that you have attached to that specific database or server will inherit that color. And so my trick was I would like to use like red for databases that I don't want to, I don't, you know, I want to be careful about not updating or changing things to, you know, and green for local databases that I

don't care about, right. That I, that I'm free to I'm free to insert or change or delete or whatever. And he mentioned that you can set under the options for it, you can mark the database as read-only in your data source configuration. And then that way, you'll get a warning that you have to confirm if you try to do any write operations, even if your credentials have the right permissions to do it.

So it's like a extra layer of protection, um, you know, before you do something bad. That's a really, really good tip, right? Cause you don't want to be that guy that accidentally drops the production

database. Yeah. Yeah. You just remind me of, me of a really good podcast I've been listening to called American Scandal. It had an episode where... Yeah? That was also in episode 157.

Wow! Every time there's a really good one about the cigarette ads in the 90s. Oh, jeez. I give up. That's excellent all right so i i have several here so i'm going to try and blow through them you would more were coming to me as the episode went on and i was like i gotta get it out here because i'm gonna forget it next time so the first one seeing as how this episode was all about APIs, the first one is called API Blueprint.

The link is apiblueprint.org. It'll be in the show notes. Definitely go check those out. But this allows you to design and document APIs. So using almost like a markdown type thing, it allows you to set this up. So definitely go check that out. Might be worth looking at if you plan on making an API. The next couple are from Slack. The first one is from

somebody named the letter I on Slack. There's no name associated with them at all, but he dropped this over in the tip of the week or the tips and tools channel. And this one is actually really exciting. And I can't believe I've never heard of it. We were talking about visualizing data earlier with the Python thing, like the favorite things, dude, Apache super set allows you to hook up to data storage and visualize it in ways I can think of so many times this would visualize it in ways.

I can think of so many times this would have come in handy in things that we were doing. How many customers do I have? How many people are in this? How many orders? Whatever. Like you can hook it up and it'll give you charts of your data. That's awesome. With a UI to be able to explore it.

So again, Apache projects are amazing. The next one from one of our favorites, Mike RG, he posted a link in called use console log like a pro. So if you use Chrome dev tools, you know, when I first saw this, I was like, what am I going to learn in here? Okay. So you've got your logs, your infos, your debugs, warns, all that. All right. That's all cool. What was really interesting though, is there is a console dot assert, which I never knew existed.

There's a console dot count. Never knew existed. Um, a dir, there's a group. You can actually group console logs together. So there's a lot of little tips in here that are really cool. Didn't know existed. Definitely check it out if you do any kind of debugging for front ends or anything in Chrome. All right.

The next one, again, because we're talking about APIs and we were talking about REST a lot in this one. I know that we've talked about Postman in the past. I don't know if we've ever used Fiddler tool as a tip of the week or anything, but if we have, whatever, it's a fantastic tool. If you need to basically see the kind of things that are happening, like let's say that you have a website up and you need to see the traffic that's hitting your web server, especially from you trying to see what was posted to it, what the results are and all that. This tool is amazing because you can capture that and then you can replay it. You can even modify the parameters and stuff in there.

So postman we love because you can set up your gets your posts and all that kind of stuff, but it doesn't allow you to capture traffic that's happening at the time. Fiddler tool is kind of like both tools in one, except not quite as easy to generate requests from scratch. So if you're trying to investigate things, definitely check that one out. We'll have a link there. It's a tool from Telerik. They bought them a few years ago. And then this last one I found out today, as a matter of fact. So I saw something where there were Docker builds running where we were passing arguments into it. So if you,

if you look at Docker files, you can specify an org in a Docker file, meaning that you can pass variables in to the Docker build when you run it. And one of the things that I've seen pass around are like user secrets or tokens or keys, things that really should be private. Well, one of the things that I found out about that accidentally as I was looking through this

is if you call a Docker build and you pass in an arg, that is actually stored with the image or container. So if you ever go to inspect it in the future, you can actually see credentials that were passed to it when it was created. Kind of stinks, right? You don't want that. So there is a thing called Docker build kit that they still have set in experimental. If you're running Docker 19 or higher, then you have these features available to you. But there's a way to pass a secret to where you can actually do dash dash secret when you do your Docker build. And basically what you're doing is you're blind mounting a file and then you can use that secret

within it. And then nothing's logged. No sensitive information is logged or can be inspected off those containers or images in the future. So if that we've talked about that, um, that console one before. I, we've talked about console stuff. Cause I know at one point I'd done a console dot table. Like that's one that I'd never knew it had existed. That is awesome. If you're trying to look at like,

uh, object arrays of objects and that kind of stuff. But this one, like I said, there were like little tips in here that I didn't even know existed. So yeah, you can never have too many debug tools. Yeah. By the way, Fiddler was one of mine like episode two. Was it really?

Are you a liar? Did we always have tips? Did we go to episode one slash episode one? I think so. I'm pretty sure that we did. did yeah i think that was always one of our things now you got me curious on that yeah we did uh you can right click control period as required using directives wow it's like very c-sharp oriented yeah what everybody doesn't know behind the scenes is probably the greatest amount of stress per episode is, oh, man, what is our survey? And, oh, man, what is my tip of the week? I mean, we take these surveys serious, yo. That's right. All of it. All of it's serious.

So they have Hipster Tricks control period and uh web web api route debugger look at that i will say that um seeing this uh superset apache project like we gotta get on a live stream and play with this play with some data man because this looks awesome that's sick isn't it like the gallery for some of these examples that they're giving. It's amazing. Like if this is anything as simple as like what Apache Drill was to go start playing with data, like I want this in my life. Dude, this thing is beautiful. There's so many cool visualizations for it too.

So hold up. I'm going to read these real quick because they're not that long, but these are the supported databases. Amazon Redshift, Druid, I don't know what the next one is. Squirrel or something? I don't know what that is. Okay. Google BigQuery, ClickHouse, Dremio,

XSL, Firebird, Greenplum, IBM DB2. They support DB2, probably because it's JDBC. MySQL, SQL Server, MonetDB, Oracle, Postgres, Presto, which is awesome. Snowflake, SQLite, Trano, Rockset, Vertica, and I don't know what that last one is. And they say there's many more. So, yeah, man, being able to visualize things like this quickly and easily is just fantastic elastics one of them too if you uh go into the more

oh man see yeah this this needs to be played with it was literally uh you know one of the things that we talked about in uh episode 152 about things that are awesome about Python was being able to visualize data really easy. But now, like, hey, you just like point this thing to it. I really want to do a like a live stream play with this thing. That looks really cool. Cool. Cool. Yeah.

I don't know. I would say that Joe and I would get on Twitch and do it, but I don't know that he twitches anymore. So, uh, I guess with that, uh, we would say like, Hey,

you know, subscribe to us on iTunes, Spotify, Stitcher, wherever you like to get your podcast apps. We're probably there. Uh, if somehow you're hearing this and we aren't on your favorite podcast

destination and you haven't already subscribed to us, probably means you have some awesome friends. And, uh, so, you know, buy them a cup of coffee or a beer, you know,

whatever's appropriate. And, uh, you know, tell us your thanks, uh, for them pointing you to us by, uh,

heading to www.codingblocks.net slash review. And you can find some helpful links to, uh, leave us a review, which we, we would greatly appreciate. That would be your way of getting us a coffee or a beer. How's that?

Totally. Totally. Actually, um, on that page too, uh, we always forget to mention this, but there's instructions for getting around,

uh, the fingerprint, uh, the fingerprint access on Android phone. So if you want to like go subscribe some of your coworkers to the podcast, cause they need some of these tips and tricks. Then we've got some instructions up there for, for Android versions,

something in up. Very nice. Very nice. I'm glad you remembered that. Um, so as mentioned, and you probably heard throughout this show, we've got a lot of links in this show.

So while you're up there, check out the show notes or even on your phone or whatever you're listening on. Outlaws mentioned in the past, chances are you can see the show notes in your pod player there. So you can send your questions, feedbacks and rant to our Slack channel. And follow us on Twitterverse atverse at codingblocks or head over to codingblocks.net and you'll find all sorts of social links at the top of the page also we've got some tips there for how to

get in people's phones slash reviews so make sure you hit that up right before the feds take it down cease and desist