API Evangelist Conversation with Ben Hutton of The Guild Software

Ken, great to see you again. Uh, I’m Ben Hutton, uh, and I’m a senior software engineer at the Guild and I’m part of the JSON Schema TSC.

Yeah, thanks Ken. Um, I was, you know, chatting with a few different people, um, about the API usage and, um, looking at the API news and I saw a lot of, uh, talk about, uh, SDKs. And it got me thinking, you know, What value do people place on SDKs? So I asked the question, or I kind of made a statement and asked what people thought, uh, developers don’t want to use APIs. They want to use SDKs. And I asked people what they thought about that. Um, you know, deliberately provocative. Uh, I wasn’t coming down particularly one way or the other. I really wanted to see what people thought. And, um, I was really pleased to see people turn up, a lot of the usual suspects, and [00:02:00] a few really great bits of insight as well.

Yeah, thanks Ken. Like, um, I think I was, I was really torn. I wasn’t a hundred percent sure. Um, and I still think, you know, you have to play that it depends card. I mean, it really does depend on what you’re working with. Um, you know, I’ve, I’ve consumed, you know, many, many APIs. Uh from different providers, but I found I’ve rarely used an sdk um And and rarely use those in [00:05:00] production. I think that’s partly due to the the languages i’ve worked in Mostly not being strongly typed Uh, I think you know when you work in in strongly typed languages like dotnet then you you want to avoid having to write A lot of boilerplate code or you want to have to avoid writing all the stuff that you just really don’t want to um, I think ultimately me SDKs are not necessarily, you know, about providing easy interfaces as much as it’s about saving time. I think it’s whatever’s gonna. enable the, uh, you know, the developer to reach whatever they need from the API as fast as possible. Now, when it’s like fairly simple APIs, uh, or if it’s just a few APIs, or if you only need to access like a very small section of the API that’s available, then using, Uh, direct HTTP calls might be the right [00:06:00] approach using some sort of wrapper and you know, you might write some sort of auth wrapper around that as well, just to mitigate having to manage that or having a proper separation of concern with that. Um, but when I started playing about with the GitHub API. And I started needing to make more and more calls to different places and needing to do more and more nice pagination stuff. Um, I started looking at the SDK a lot more and found it a really nice experience. Um, and, you know, for those sorts of APIs, it’s certainly a win, uh, for developer productivity and it’s, it’s going to make me use it more.

Yeah, I think it, you know, um, certainly as you say, like it can make onboarding easier. Um, people don’t have to learn like a new type of authentication. They don’t have to write their own wrapper. Um, they can just use what’s provided and it’s simpler for onboarding. In terms of like the, the other reasons, um, I think often, you know, as a, as a publisher of APIs, you want to have, as you say, like good observability on your API. Um, and you know, if you’re receiving individual HTTP calls, yeah, you can make assumptions about the process or the flow that people are doing. Um, [00:08:00] but if it’s all coming from the same machine, you might not have good visibility on, um, like a thread or a workflow of, of a particular action. Maybe it’s not quite the best explanation, but like when you’re thinking about, um, you know, when, when a user interacts with, with a service and that creates, you know, five API calls as a result to get certain sets of information as, as the API producer, you can’t tell that those five API calls are associated with a user of the system that’s making that call. But if you have an SDK and you provide the SDK, then you can do that sort of analytics. You can actually have have session or workflow attributes in your, uh, your API calls, or you could modify how your API calls work, uh, without interrupting, um, you know, the, the APIs. Uh, [00:09:00] I mean, that was one of the really interesting threads. Um, and the LinkedIn discussion was actually enables you to give your API consumers a level of abstraction. That means you can make changes that would otherwise be breaking changes. And, you know, you wouldn’t want that. Um, I mean, that’s probably like a, uh, a really nice feature for many companies that, you know, can’t do the same level of API production as a Stripe, for example, where they support. You know, n number of, of versions of the API concurrently and then translate between them, which is still pretty impressive. Uh, but most companies don’t do that. So they need to have another way to, uh, you know, push out the updated versions or updated routes of the API without impacting their consumers.

Yeah. Wow. Um, I think when you start thinking about like [00:11:00] the, the low code adaptations, like I haven’t used Locode extensively, but I certainly got into nitty gritty and had to, you know, add some, some code on top of that, um, on a number of different interactions and a number of different services. And I found it doesn’t often break. Um, and I know from, from doing a case study with Zapier, for example, some of the approaches they take and they shift a lot of the responsibility of in terms of what it does and how the update process works between published versions of the connectors, uh, onto the, the producer, um, of that API. Um, so they, they make it easier for themselves in a lot of ways. Um, and they have to define their, their interfaces and code. Um, but I think, um, Yeah, I guess it’s like, like an SDK is a similar level of abstraction to a low code client for, uh, for developers more because you still got to [00:12:00] write SDK, right? Um, but I guess it’s kind of that, that level of, um, you need to get more work done faster and Calling the APIs directly probably isn’t going to cut it, or, you know, you, you know, how to use a particular approach. Um, I think when you start thinking about the hypermedia HTTP APIs, um, there aren’t many I’ve seen that really work. Uh, the, the standards out there for doing them are not finished. Um, you can, you can kind of put them in production and there’s, there’s a few, um, You know client libraries you can use and it does work Uh, and and even the server, um libraries to assist in that do work Um, but there are caveats and there are things that you can’t easily work around, you know Having put some of those those things into production [00:13:00] and You know ultimately when you’re faced with it with a choice of do I want this thing that I don’t have Complete control of or do I want to have control over it? Yeah, like if i’m a company i’m publishing an api And I can exert a level of, of control or a level of, um, you know, story or benefit or perception on to your API consumers through the use of an SDK, um, that certainly sounds like something that’ll be beneficial.

Yeah, and I think this was a lot of the discussion like it’s it’s not an either or situation Um, and and it really And [00:14:00] the preference should be for both and we’ll come back to that. I think for a bit more later But um the threads I picked up on the more sort of like regulated industries Like particularly finance, health, um, we’re getting changes into production are costly. Like a lot of companies and a lot of people boast about their, their rapid deployment process. Oh, we deploy like 30 times a day or whatever. Like, yeah, if you’re an unregulated industry and you’re a startup and you have a small team, or even if you have a large team and you have your CICD set up well, and you have lovely tests, like you can deploy 50 times a day. Great. Um, but for a regulated industry that requires a manual review and different levels of review, like finance, um, yeah, you’re not gonna be able to do that. Um, you wanna make a change. You wanna pull in, um, an SDK, that’s suddenly a huge risk and that review period is, is gonna be much larger. Whereas if you’re just [00:15:00] making API calls and you’ve written your own thin, thin wrapper around that. Um, that’s a lot easier to, to get through that change process. And that’s before you even start talking about like the additional dependencies you bring along with an SDK. I mean, I’m sure there are SDK, uh, SDKs out there which don’t have any dependencies, but I’m pretty confident that many of them have a lot of dependencies, particularly in the Node. js ecosystem.

I mean, yeah, there’s a couple of approaches, um, to this and like, as I mentioned earlier, I don’t think it’s an either or. I think most people would agree that it’s not an either or, it has to be, um, you know, API first and it has to be a good API. I mean, what do we mean by good API is like a whole other discussion. Um, but if you get your, your foundations, right. Uh, you define your API. Well, you make sure it matches up to your, uh, API and production based on your API definitions. Um, generating your, your client codes, uh, suddenly becomes a lot easier. And I think, you know, there’s, there’s a sweet spot between fully generated. API SDKs and customized handwritten SDKs. I think there’s a sweet spot between that where you, where you generate a lot of it and you have the ability to like add and extend and customize [00:17:00] that approach. Um, you know, ultimately the, a lot of the stuff in the SDK is, is going to be. Um, like boilerplate stuff, you know, not particularly exciting. Um, you know, you might have some auth stuff in there. Okay. Right. You should be using existing libraries to do that well. Um, unless you have some like really weird auth thing, in which case people aren’t going to really like you doing that. Um, but I think there’s, you know, there’s a sweet spot there to be had. And everybody publishing an API who wants to have an SDK. If they have those good foundations, they’ll be able to try and move that dial and see where that sweeps what is for them. Like there’s certainly a cost involved. It’s whether that cost material comes to, um, you know, provide the business value of the game. Like I’m seeing a few reports from different places that having an SDK dramatically increases the onboarding of their [00:18:00] API usage. And where your API is your your product or you know a big portion of your product for certain tech companies If you could move that metric by generating an sdk Uh, suddenly that becomes a lot more interesting and worthwhile spending time investigating

Wow. Um, I think maybe I’m somewhat shielded from seeing the SDKs. working in a non typed language, um, and I think people have wanted them. Um, but I think we are, we are going to see over the next few years, a definitely a positive shift towards more SDK usage.[00:19:00] Um, things are complicated, but also tooling wants to be able to use them in a way that’s not gonna, uh, affect them when there are changes. Um, you want to insulate consumers from the producers, uh, and allow the producers to do what they need, allow the consumers to do what they need. And that, that insulation layer, I think is going to become really valuable in a space which is fast evolving and dynamic. Um, and, you know, thinking more broadly, I just want to bring up like one of the, the quotes, um, or one of the comments I had. Um, from, uh, you know, our friend, Lorna Mitchell, um, said we find it easier to, to build technical solutions, um, than to think about how to solve a hard problem. And I think it’s really poignant. Like we, we can, we can build amazing SDKs from, from API descriptions, but unless our APIs themselves are good, uh, for, for a measure of good. Those SDKs [00:20:00] are going to be garbage. Um, and I think, you know, although we’re going to move in a pro SDK direction, um, the, the result of that is going to be, we need more tooling and we need more support and we need more enablement and education of those underlying foundational things, which enable that good SDK generation and have a metric by which we can analyze those. And, and that’s, that’s going to be, you know, really telling when we come to evaluate with, uh, A company has released a good SDK or not. Like, okay, let’s, let’s, let’s go back and measure the foundations that you used to build that SDK and see if our measures are correctly predicted with the quality and utility of your SDK.