API Design Smells with Keith Casey

David Brown

Welcome to Episode 78 of the Coding Over Cocktails podcast, my name is David Brown.

Our guest for today serves on the Product/GTM Team at ngrok, helping teams launch their systems faster and easier than ever before. Previously, he served on the Product Team at Okta working on Identity and Authentication APIs, as an early Developer Evangelist at Twilio, and worked to answer the Ultimate Geek Question at the Library of Congress. 

His underlying goal is to get good technology into the hands of good people to do great things. In his spare time, he writes at CaseySoftware.com and shares his experience of a lifestyle change living amongst the trees. He is also a co-author of “A Practical Approach to API Design.”

Keith Casey

Great, thank you! I sound quite impressive when you read it like that. I love it.

David Brown

The bio is intended to sound impressive, so it has the intended consequence. That's good and it should do as well. You have amazing experience and a great new role at ngrok and I want to talk to you about your book as well. 

So let's first of all start talking about your role at ngrok. It's a fairly recent thing, right?

Keith Casey

Yeah. I guess I've been there for about 11 months now. So yeah, relatively recent.

David Brown

Yeah. And what is your role, you're evangelizing the product and educating the market?

Keith Casey

Yeah. So I'm on the go-to market team as of this moment. I'm the third of the overall marketing team. And really, my entire job there is to be able to show people what to do, how to do it, why it's important – those sorts of things, and then amplify people doing the things. Most people, if they're familiar with ngrok at all, it's because they use us to connect their web hooks from Twilio, from Slack, from Salesforce, whatever down into their local environment. And we do that really well. 

But that's really just the beginning. If you start layering in things like, OAuth 2.0, you can do that. And I think it takes 12 characters to enable Google as your OAuth provider. You can do IP restrictions. You can start doing web hook verification. You can do so much more stuff that frankly, people aren't aware of yet. And so it's my job to go and talk about it.

David Brown

Well, that's a good point because I think myself included was very familiar with ngrok as that solution to get something which is publicly web based, connecting to your local computer. For example, at Toro we have a desktop application which has a server runtime. So, if you want to publish that, make it publicly available, you can use it to do that. 

So tell me about some of these other features you mentioned, for example OAuth, was it 12 lines or 12 characters? Tell me a bit more about that. That sounds interesting.

Keith Casey

Yeah so one of the things we realized is that opening up your local environment can be scary. In fact it's often terrifying, especially the security IT compliance folks? They freak out at that. So one of the first things we want to do is be able to put some restrictions in place. So we added things like IP restrictions to be able to say, “No only this IP range,” or “This particular IP address can access my stuff.” 

So that comes in really useful for IoT devices and use cases. We have a lot of people that are using ngrok to put their Raspberry Pi online. But once you start with that simple thing, instead of thinking about where they're connecting from, you need to think about who's connecting instead and who's connecting ends up being a much more powerful lever to pull. 

And so we implemented a simple OAuth 2.0 consumer. It's a reliant party, if you want to speak in those terms. And so you basically say “-- OAuth = Google.” And then what happens is when you hit the ngrok tunnel like you normally would, just the URL. You hit that URL. It detects you have Google as your OAuth provider, and redirects you to Google. You go through that authentication flow and you come back with that access token that Google has granted you. So it ends up being a really quick and simple way to be able to put an identity provider in place. 

And of course, we support Okta. I was kind of biassed to get that one in place. But as your A. D. For dirac being just about any open I. D. Connect or sample two point compliant identity provider. We support out of the box.

David Brown

Fantastic. You mentioned a couple of other things which people may not be familiar with. You want to run us through those briefly.

Keith Casey

Yeah. So we do a ton of things. So since most common use case that people using Rock for is connecting those web hooks, we started digging in deep into web hooks. So we started looking at like how can we lock these things down? How can we make sure that when your application and you launch your application, you're expecting that web hook from Twilio request that sms message coming in. How can you make sure it's from Twilio. We realize that I. P. Restrictions is useful but really verifying that web hook provider is way more important. So we ended up building a web hook verifiers in place. We've got probably 50 of them or so right now in place in in rock out of the box. In fact, we had accumulated data on about 100 and 50 different web hook providers out there. And so we, let's see back in august, we launched web hooks dot F. Y. I. Which is just a clearinghouse of here's all this information on different web providers. It's a totally neutral community oriented site. It's runoff, get hub pages. So if you have if you find anything wrong or missing your favorite web hook provider, just check it out. Um do a pull request added to the list? Were totally unbiased. There were, I really want to make sure that this is a definitive source for figuring out how to use web hooks, how to integrate web hooks if you're a provider and you're considering building web hooks. Here's a bunch, here's what the entire ecosystem is doing. So you can decide which capabilities you want to blend in with. Like, do you want to look more like Twilio and their approach or do you want to look more like slack in their approach?

David Brown

That sounds like a really good resource. What was what was the name of that again?

Keith Casey

Web hooks dot F. Y. I.

David Brown

1. Y. I. Okay.

Keith Casey

Yeah, it's a great resource. We've got some great attraction out of it. People love it so far. We're happy about that.

David Brown

I'm looking at it right now. Um so you mentioned that you added for example, with web books, you want to authenticate that the request is coming from the provider itself. And so you've done that with a bunch of providers, for example, Twilio. So how are you authenticating that the the the request came from Twilio?

Keith Casey

Yeah. So most weapon providers provide some sort of hash in the header itself on the request. And so um you can go ahead and you can pull out the hash and then we do that on our side. So the way it works is when you have the local agent running on your machine, you use that to open a tunnel to our cloud and then on the cloud, that's where we put those, those enforcements in place. So we go ahead and we dissect the header, we hash it properly according to H Mac, whichever hashing algorithm they use. We validated if it validates great. We pass the traffic onto your app. If not we drop it in the cloud and it never sees your your network.

David Brown

Great. Well, that's all interesting stuff on and I'd like to move beyond and go to which I'm going to pause for a second. I opened your website now, I've lost my questions. So let me just here we go. So cut that bit out um Keith on your first job, you worked for a consulting firm for the Library of Congress. And your goal is to answer the question: “How much data is in the Library of Congress?“ So how much data is there? Did you get the answer?

Keith Casey

So we had some projections of what the answer is and I love the fact that you started from like my most recent job to my very first job.

David Brown

You’re going to work your way in between.

Keith Casey

Excellent. So I joined the Library of Congress to specifically digitise everything they had. And at that point we figured out that if we digitised about 50 terabytes a day, that would let us at least keep pace with everything they had. Now some context here. This was 2001. And if you remember, the internet and creation of content in 2001 is a little bit different than today. There was no social media. YouTube didn't exist, blogging was still exceptionally rare. Itunes was not a thing yet. So when we say 50 terabytes a day, you have to remember, it's a completely different ecosystem than what we have now. 

But the wild thing about that is that it did not address the 225 years of American history up to that point. Because in the States, according to copyright law, when you copyright something you're supposed to send two physical copies of it to the Library of Congress. So in theory, anything that's ever been copyrighted in the States is on file at the Library of Congress. Now, realistically it's not available. A lot of it's sitting in boxes and warehouses, but they were working to change that. 

It was funny when we were first specking out these systems, we're looking at doing these arrays of 120 terabytes each, which in 200,  was mind blowing. We didn't have an idea of how much data that would be. And then we figured out that once the building was fully staffed, we'd filled two of those every working week. And we're like, “We need to plan bigger.” Like we need to do more stuff with that. 

But there were like two really cool aspects that came out of that one. When you're working with a library, you're not just thinking about, “How do I make this data available today?” We're thinking, “How do we make this file format that we're storing things in readable to people in 10, 20, 50, 100 years when the tooling that we have today is long gone?” So, if you think about lossless codecs, if you think about JPEG and GIF and all these things, 100 years from now, people still will be arguing over how to pronounce “GIF,”  but at the same time we may not have readers for it. So how do we store these bytes in a way that 100 years from now, people can make sense of it? 

So, that was one really cool, exciting aspect. The other one, and this actually kind of shaped the rest of my career was, in the library, there's no feasible way they could digitise everything themselves. They just did not have the staff, they didn't have the equipment. So what they started doing is they started building this interchange format, this XML payload to be able to say, “Okay if we digitise some of our collection, we talked to this university and this library and this group over here and we get them to digitise their own. Then we can trade and no one has to digitise everything.” 

And so we created in 2001 which we believed to be the first federal government web service, because exchanging XML documents is fundamentally a web service. So, we're working with WSDL at that time, XML and XSLT and we were bleeding edge. And sometimes we had the bruises to demonstrate it. But it was a fascinating, fun topic to dig into.

David Brown

And so this led to your passion towards APIs and shaped the rest of your career really. And led to obviously the writing of the book, “A Practical Approach to API Design,” which you're a co-author of with James Higginbotham and seems to be an electronic publication. Is that right?

Keith Casey

Yes. It's through

David Brown

 through an evil. Um, so tell us what led to that to the creation of that book. What drove you to create a guide to the arch?

Keith Casey

Yeah. So fast forward a few years after library congress had gone through a couple startups, many of them had crashed and burned. But I joined this little company called Twilio. And I say little because when I interviewed, there were about 12 or 15 people total the entire company. When I joined up, I was number 18 or 20. Somewhere right in there. Um, which is a wild place to be. But one of the things Tulio did better than anybody else and a lot earlier than most other people was their api design. Making sure that it was consistent. That is understandable, that it was logical that it was predictable. So that a lesson learned in this portion of the A. P. I could apply to that portion of the A. P. I just as easily. And I spent a lot of time helping people sort of figure out their A. P. I. S. 

When I left Twilio, I realized that most of the world was behind. Most of the people that are doing API Design? It was crap. It's terrible. It's miserable. It was inconsistent, unpredictable. It wasn't versioned. Well, there are all these issues. So I realized pretty quickly that I was in a special place. I had a special understanding that most people didn't. So I partnered up with James through a mutual connection, we decided to just document what we're seeing and what we were detecting is the best practices and sort of surveying what was out there and at the same time trying to provide some direction on where people could go with it.

David Brown

Yeah. So you've also written about design smells. So which is, as the name implies, something's not quite right. So what are the design smells that you've discovered those things where you said most people suck at it. So what were the indicators for a bad API design?

Keith Casey

Yeah, I'd say probably some of the first and most impactful ones were just poor naming, you know, and what's the saying in computer science. There's two big problems naming things cache and validation and off by one errors like these are the kind of things that just completely screw up in API. They make it really hard to understand, really hard to to make sense of, to normalise things. 

And really that next step is, the consistency aspect. One of the most powerful things about rest api specifically is how we interact with them having a stock set of http verbs having a stock set of response codes means that the understanding that I get in this A. P. I was the understanding I get in the Twilio Api I can bring over to the slack KPI and apply it. We need to think about that within our API itself so that if we have a resource set of endpoints in our API and we interact with it this way over here we go to a different part of the A. P. I. We didn't make sure those exact same designs those exact same principles throughout. 

So if we query a particular way, if we search a particular way, if we sort a particular way it should be exactly the same when you see those little variations were over here. It's one thing and over here it's a different thing. you can tell very clearly that different groups designed the A. P. I. And they didn't talk to one

David Brown

another. Any other smells that people should be aware of. Yeah

Keith Casey

My favorite is I was working with a bank, jesus was 789 10 years ago now working at the bank major bank in the States. Um and they were they're going through that normalization process. They're trying to figure out how do we how do we make sure that somebody has understanding over here in this API and they can apply it over there and I'll never forget interest rate. So one department called it integrate I. M. T. R. A. T. Very simple. Another one called the interest rate and they used was it snake case where it's underscore in between the words all lower case. Another one we use camel case and somebody else used prefixes so they were Irate and it was just great because I was like they were getting so frustrated each other.

I mean I guess they were very irate with each other. Um and that was that the naming thing. But then also the data representation and end up being a big problem also. So when you and I think about interest rates, we probably think of the actual percentage, you know, you are your mortgage and you say it's 5.5%. So we think 5.5 and we just naturally rounded off to, you know, not a whole number but a number, some departments thought of it as a percentage or I'm sorry, a decimal. So they represented 5.5 is 0.55 and still other others thought of as basis points and basis points. Our 1/100 of a percent. So 5.5% or 0.55 was represented as 550 when it's in basis points. So now when you're trying to apply for a car loan and you're pulling interest rate from here versus here, you need to understand well wait a minute. Should I divide by 100 or multiply 100 those turn into wildly different interest rates if you hadn't guessed by now.

David Brown: 

Yeah,

Keith Casey

So I would, I would always say, understanding naming conventions, understanding how the data is stored, how it's represented, how it's transported throughout the system is a really easy place that it's, it's easy to screw up. And it's hard to realize it until it starts biting you.

David Brown

You were talking about writing part two of the design smells article. What sort of things would you incorporate in part two?

Keith Casey

Yeah. So one of the things I saw in Okta, I launched their api security product is fundamentally off as a service. And so one of the big problems I've seen with this and that I'm probably going to include the next one is about authentication of making sure how how are people thinking about authentication? Is it is it header bases? It tokens is a U. R. L. Extension like the parameters on the U. R. L. Um and then once you get past authentication, how do they think about authorization? So is it just simply you have access to? You don't do you have fine grain access? How is that represented in terms of the A. P. I. I was recently playing with the zoom A. P. I. The zoom A. P. I is exceptionally well done. I was very pleasantly surprised. It's 2.0 which is a particular surprise but then they're fine grain authorization through. Um The scopes is fantastic. Um I was able to get started and be able to grant really find great access to my applications in no time. So I think those are two big things and then I'll probably attack web hooks. Web hooks are my current fascination with, you know, web hooks at F. Y. I and how people are representing it. And it's kind of, it's frustrating right now how many organizations don't put any sort of authentication or even verification on the web hook? So you get this request that claims to be from the provider and you don't know,

David Brown

it's more common than, than it is not. I would, I would think that that you don't get that hash in the header to authenticate the request. It's it's surprising. Um Speaking of which, you did mention that back when you started in with Twilio, I think it's around 2011 that they were doing design particularly well and you realize that most people suck at it were 10 years since then. So, how, how, what evolution have you seen? Not clearly the adoption of a piece has been astronomic, but in terms of the design and implementation and trends, what have you seen since then? What have you observed?

Keith Casey

So one, I think the tooling is magnitudes better. It's, it's some, it's frankly wonderful. Some of it still needs some work. some of the specifications like open api spec is great. You can do a lot of things and express a lot of things with it and then you start getting into the tooling that can actually consume open aPI to generate SDK s or generate portals. I think that's, that's come a long way and I love those aspects of it. And I love the fact that as we're normalising around a couple of different standards, the creativity that goes with that, I'd say probably the the gap is we have a lot, we have more and more tooling that is um frameworks for quickly generating a P. I. S.

So I was working with a group probably about a year or so ago and they said, well you know our framework, we just tagged the methods we want open and then our framework will go ahead and generate all the end points for this. I said, okay, well that's great that that will get you a rough draft of things, but you really need to apply some design on top of it. If we think back to being like a web designer, there was that era of time that every website was bootstrap right? You remember that time and every website looked exactly the same, It had the same navigation, the same, everything. It drove designers up a wall. Now it got rid of it, got rid of the worst stuff like the bottom level of like this is a terrible website design a lot of that stuff disappeared because the now the the minimum viable design was a lot better, but the same time, it wasn't really a design, it was just the default scaffolding and so I think right now the problem that we have in the api spaces, we have a lot of people using that default scaffolding and then shipping it and it's really not a design. It's probably not terrible, which is a good sign, but it's not well thought through. 

David Brown

and so when we're talking about that can give me a specific you're talking about, like for example, you mentioned with zoom that you could have authorization on the scope of the aPI. So what what sort of things are you looking for taking from a machine generated scaffold to actually implementing some design considerations? What would be the, what would be the leap between the two?

Keith Casey

So I really think of it as a ingredients versus a recipe. So if you are tagging individual methods within your controllers and opening those up to the world, you've got some really good ingredients. But the recipe is when you start putting them together in a particular order and you start accomplishing something with it. So I was like thinking of it really well designed api supports some workflows. It says do a doobie. Do see now you've got the result you want and so it's really that beginning to end and to do that. Well you need to understand the use cases, you need to understand what is your, what's your api good at what are people using it for? How are people using it? What's the context or the situation that they're using it in now that you know that then you can sort of optimize for that or build a happy path that takes advantage of all those capabilities, like very sequentially, very simply and you can make a wonderful recipe out of it.

David Brown

You know, obviously you need to talk to the consumers of your api to to understand those things as well. What are you finding you mentioned, for example, open aPI one of the frustrations I have is whilst that specification has been around for a number of years now, very few companies actually publish an open API specification. You might be lucky to get a postman collection for example, but if you want to consume and scaffold their API and machine generation services, getting one is difficult often. Um, what sort of frustrations do you experience with? And I'm talking about the largest companies publishing some of the largest in the world, still failed to do the basics as I see it in terms of making their api discoverable. What sort of frustrations do you experience?

Keith Casey

Well, I personally suffer that frustration because at ngrok, we have not released our open aPI specs yet. We've got some rough drafts that we float past some people, but we haven't formally released anything yet. I'd say that's probably the single biggest problem is that, most organizations believe if they have a developer portal or a relatively simple documentation site, that that's sufficient. And for a lot of people that is. But, if you don't have the capabilities, if you don't have the tooling or he best way to phrase it [is], if you don't have things in a way that people want to consume, they're just not going to adopt it, they're not going to consume it. And so in some cases that's going to need, it's a simple documentation in other ways, it's going to need documentation and SDK s in a particular language, some cases that might need SDK s in a framework. 

I actually wrote about, I don't know about a year or so ago, I wrote about developer experience as a way of growing total addressable market and I said there are people who, all they need are docs like if you give them a dock, that's roughly correct. They'll figure out the rest if you give them a dock that's detailed, it gives you, here's the request format, here's the payload, here's everything. You'll have a bigger audience that will be successful with it. If you didn't give SDK s will have a bigger audience. You give framework sDK s instead of just language to sDK s Now, you have a bigger audience. If you start thinking about like a Wordpress plug in or you start thinking about no code, low code integrations like zap here or um, tray or somebody like that, you have even more adoption. So I think we really need to understand what's the audience we're targeting, if we're targeting the pinnacle of developers that, you know, you give them imacs and a power source and they'll figure out the rest that that may work. But there's like five of those guys,

We need to think about what's the audience size, who who wants to use our A. P I who do we want to use our api how do they do it? What do they need and then solve the problem for them instead of who we suspect might want it at some point,

David Brown

I want to finish up on one of your underlying goals, which is to get good technology into the hands of good people to do great things. Yes. What first of all, where did this goal come from? Yeah,

Keith Casey

That sounds very aspirational and stuff, doesn't it? So years ago, Probably jeez, 15, 18 years ago or so, I realised that the world is only becoming more distributed and computing specifically, is what I'm talking about, power generation and storage is becoming more distributed storage and processing and wifi, all these things are becoming more powerful, more distributed, more flexible. And really we have more edge computing concepts and so really what I wanted to do is say, if we take that premise to the logical end, what does it look like? So I joined Twilio initially, because I said, okay, these edges are going to have to be able to communicate ap eyes is how they're going to do that. So that made sense. And I really pushed to try and get a P. I. S. As a thing and obviously thousands of other people are doing the same thing. And then I got deep into that and I said well you know the next thing we need to do is we need to be able to add security on top of that. 

So that's why I joined Octa and I really said okay we need to be able to secure those connections as they're communicating. And then I I left october last year I realized that the next layer is actually the deepest layer and that's just fundamentally connectivity. These things can't communicate, they can't communicate securely if they can't connect. So that's why I joined in rock. So when I think about great technology and great concepts I think about how do we take all those edges? How do we take that, processing that storage, that compute that that power generation all those edges and make it work together in a way that's productive. So I really think in terms of those things and when I think of great things I think of um basically anything I really don't have like a concrete specific thing there um I have solar on my house. So I do all kinds of energy monitoring, I've got you know people building all kinds of crazy systems to be able to monitor things and understand here's how these things interact. So I really want to be able to make sure that the stuff we have can connect, you can connect securely it can communicate, it can interact and this and hopefully as an overarching goal, everything works better as a result we'll see if it gets there. But I'm hopeful

David Brown

You gotta have the goal the, you created a Youtube series on your experience of your tree change. What instigated the tree change.

Keith Casey

Yeah. So let's see. I was a city boy. I lived in Washington D. C. For 10 years. I worked in politics and different industries over there. I spent 10 years in austin texas, which was wonderful. But it was still a city early last year. Well late 2020 early 2021 I decided you know what, let's move to the woods. So convinced my family, let's move to the trees. So I started a website which is very little on it, geek among the trees and I figured philosophically we've all hit that moment where we're debugging that thing. We're pounding our head on the wall. We're so frustrated and angry about it and we want to take our computer and throw it out the window and go live in the trees.

So I decided to kind of do that. But what's really taught me is that when I got out here, I realized I had no skills whatsoever that actually translated to keeping somebody alive. I had awesome API design skills but I didn't know how to grow vegetables,

David Brown

How remote are we talking about? Like when you talk about, you know, growing vegetables and survival, like how remote are you talking about?

Keith Casey

Yeah. Yeah. We have water. I call this 21st century homesteading. I mean I've got solar power, I've got Starlink, I've got a Roomba but it's it's um 10 12 miles to the nearest gas station. So it's, you know, it's a 15 minute drive to the gas station or to the grocery store or it's a half hour to a hospital if I need one. So it's it's not the total wilderness. You know, we can go and get stuff, but at the same time I let's see, I think from my house I can see three neighbors.

I can see their houses, I can't see them. I can see their houses. So we've got 20 acres in the wood and it's it's wonderful of small pond, we've got a big dog that roams around patrols, the place. Yeah, we have fun with it.

David Brown

And you can still do what you do and educate the public and work for all these fabulous companies living that lifestyle. It's that it's the new economy, isn't it?

Keith Casey

Yeah. And frankly it's fantastic. Starlink just opened up new worlds to us.

David Brown

Yeah. Right. Thanks so much for your time today for the listeners of our program. How can they follow you on your channels? What's the best channel, you mentioned a couple, maybe you can reiterate those.

Keith Casey

Yeah, absolutely. So I'm Casey software just about everywhere. That's C A S E Y software, that's on twitter, that's on linkedin. That's on um let's see, Lincoln is probably one of the better places because I also have videos through linkedin learning that you can definitely check out. Um and I'm pretty available if you want to find me on a day to day basis really are in rock slack channel is the place to be. so find me there. I'm happy to chat anytime and help people scheme and debug what they're building.

David Brown

Brilliant Keith Casey. Thank you so much for your time today.

Keith Casey

Thank you.