PostHole
Compose
Login
SE Radio 679: Wesley Beary on API Design
Wesley Beary of Anchor speaks with host Sam Taggart about designing APIs with a particular emphasis on user experience. Wesley discusses what it means to be an "API connoisseur"— paying attention to what makes the APIs we consume enjoyable or frustrating and then taking those lessons and using them when we design our own APIs. Wesley and Sam also explore the many challenges developers face when designing APIs, such as coming up with good abstractions, testing, getting user feedback, documentation, security, and versioning. They address both CLI and web APIs.
This episode is sponsored by Fly.io.
Wesley Beary of Anchor speaks with host Sam Taggart about designing APIs with a particular emphasis on user experience. Wesley discusses what it means to be an “API connoisseur”— paying attention to what makes the APIs we consume enjoyable or frustrating and then taking those lessons and using them when we design our own APIs. Wesley and Sam also explore the many challenges developers face when designing APIs such as coming up with good abstractions, testing, getting user feedback, documentation, security, and versioning. They address both CLI and web APIs.
Show Notes
Related Episodes
Other References
Transcript
Transcript brought to you by IEEE Software magazine.
This transcript was automatically generated. To suggest improvements in the text, please contact [email protected] and include the episode number and URL.
Sam Taggart 00:00:51 This is Sam Taggart for SE Radio. I’m here today with Wesley Beary. Wesley Beary is co-founder of Anchor and has worked at a variety of tech companies, including Salesforce, Heroku, and Engine Yard as an engineer and developer advocate. Today we’re going to talk about API design. We’ve talked about various aspects of APIs in previous episodes such as 612 and 542. We’ll include links to those episodes as well as a few others in the show notes. Welcome, Wesley.
Wesley Beary 00:01:16 Thanks. Thanks for having me.
Sam Taggart 00:01:17 Let’s get started by defining what is an API.
Wesley Beary 00:01:21 I think technically Application Protocol Interface, if I remember, right? That sounds right, really it’s the interface that we expose to outside users. So most of my experience in particular is with HTP driven APIs and so usually it’s, somebody’s making a request over the web to me that they want some work done in some way, shape or form, and that’s how they tell me what and how I should do it.
Sam Taggart 00:01:45 So I think APIs actually exist at various levels because I think of an API as I’ve got a software module in the API is the things that I call to make it do things. And those command line interfaces are also a form of an API because you can script them and make them programmatic. And as you mentioned, a lot of people talk about web interfaces as APIs.
Wesley Beary 00:02:05 Sure, yep.
Sam Taggart 00:02:06 I’ve heard you in a talk before mention your own acronym for APIs called Assumptions Probably Incorrect. I found that rather funny. Can you talk about how you came up with that and what it means?
Wesley Beary 00:02:16 Sure. It kind of speaks to I suppose all those different levels of APIs that you were mentioning, whether it’s in a library, on the CLI, on the web that at least in my own experience, when I try to make a new interface for something, it’s this sort of no plan survives contact with the enemy kind of thing. I’ll have a plan, I’ll put together this interface and then I’ll try to use it and realize that I’ve forgotten six or eight things or something that there’s some edge cases that weren’t considered, that basically I’ll end up with something that the experience isn’t nearly what I hoped it would be, that it just doesn’t pan out. So it’s one of the reasons why more and more I push towards trying to do lighter weight things, I guess? Trying to basically have prototypes or other things that I can work against, don’t spend all the time to implement the interface front to back with full tests or something, only to find out that I’ve made a huge error.
Wesley Beary 00:03:02 So doing what I can to get more hands-on experience sooner, because for me at least I find it really hard to just think through all of that in the abstract. So that’s kind of what I’m talking about with assumptions probably incorrect. If I try to just do it abstractly upfront, I tend to miss things. So I feel really getting into the nitty gritty of it and trying it and using it in anger as people say, actually using it the way you think a user would use it quickly reveals the things that you didn’t think about or overlooked.
Sam Taggart 00:03:28 So if I understand correctly, you’re advocating for more of an iterative or agile style of development?
Wesley Beary 00:03:34 Yeah. I definitely think that that makes a lot of sense in this context. You can get a foundation of something together quickly, but the edges always end up for me at least being rough until I’ve had some real experience with it and can get some real feedback on what is working and what isn’t working. So more agile is the way to go.
Sam Taggart 00:03:51 Do you have any specific examples that come to mind of times when your assumptions were not quite correct?
Wesley Beary 00:03:57 I just made a mistake related to that this morning when I was working on some API design, so I guess that’s fresh where I was going in and we were working on something related to specifying domain names and what something can and can’t do basically by which domains is able to operate on. And I sort of quickly looked in the existing API and checked to see what precedents we might have. And there was an example of an array of domain strings and I was, great, I’ll just use that. But it turns out that I had had a conversation with my colleague that I’d totally forgotten about, in which he had pointed out that that’s just one of the things that we want to check against. And so I needed to actually to have an array where there was both a type and a value.
Wesley Beary 00:04:38 So one of the possibilities is A DNS type with a domain name, which is very similar to what was there already, but just putting an array of domain names would’ve been too limiting and it would’ve been very difficult to change later. So just making that small tweak to something where there was a type and a value will give us a lot more flexibility in the future. Where again, I was just sort of assuming, oh, well I’ll just follow the existing example, not thinking about the broader implications in these other use cases that I just, again, didn’t happen to be in mind at the time. It can be hard to get all the context all into your brain all at once, sometimes I think with interfaces. So we end up piecemeal recalling parts that you had previously forgotten.
Sam Taggart 00:05:11 That leads into my next question, which you kind of already answered, but the question was, I’ve heard you talk about one of the major problems with API designs that were too close to the problem. And I think that’s a good example. You’re looking at the narrow thing of, I just want to filter some domain names, but you take a step back and youíre, well, maybe people would also want to filter other things.
[...]