This post is a transcript from Burton Rheutan’s lightning talk at
The Austin Homegrown API Meetup in June 2019.
All right. So, I’m going to talk real quick about creating SDKs for your API. So this is the Austin API meetup, but SDKs are an important part of an API to increase developer efficiency and API adoption.
So what is an SDK? Simply put, it’s a software development kit to enable developing software.
It makes it easier to run your code, and it abstracts all of the specifics of your API and lets the developers using your API follow some common patterns that are more familiar to them. It’s also considered a library or a package that can be imported, included in another project that has all your predefined API calls. So if you have some really crazy long URLs that you need to call, this hides that away from the developers using your APIs.
So why would you do that? To make it easy to use your API. Without any in-depth knowledge of how your API is working. So you can abstract the versioning—I’m sure you’ve seen it:
You can also include the specific headers that you know you need for your API to function properly. You can hide away the authentication, turn it into a single call, just login or something. And, that’s all built in. You can enforce some best practices, default parameters, things that most people may not know about, then you can just hide that away. Paging, for example. And timeouts as well.
Air handling. So you create the SDK, you can lean on the language features to handle errors instead of returning a 418. Does anybody know what that is?
That’s right. I’m a teapot. I’m not, but yeah.
Nobody likes to implement an ACP client every single time you have to make a call to some API. So all that boilerplate code can be hidden away behind your SDK. So traditionally, this API may look familiar — or at least similar to something you’ve done before. Very data centric: calling customers, customers with an ID and having a GET, a PUT, and a DELETE. When you use this API, if you need to check an order, you first have to get all the customers, find the user, get the ID, call a customer’s ID with the orders, get the order ID, and then do the work on that order. That’s a whole lot of work. Nobody wants to do that.
So hopefully you can see all that well enough. Here’s an example of some code that would normally be used to sort of access an API the traditional way, without any SDKs involved. You can see that’s quite a bit of work and adding headers that you know you need, everybody needs that application JSON had, right? But with an SDK, you get one line:
And, you’re off. So it doesn’t matter what’s behind it. You know, you need to get a customer from the store, you pass as a customer ID, you get your customer.
So part of the benefit is you can use some same defaults. Like I said, the header for application, JSON you’re going to expect to return JSON results. For example, in the node.js SDK, You can handle expected errors. I don’t know if you can see that. There’s status code 404: Return Empty; not found, right? A status code 503, you know that means it’s not available. So you throw an error rather than having each client try and figure out what status codes to expect. You can also prevent mistakes by validating some inputs.
Like at the top here, you throw an error if the customer ID is not a number because your API depends on it being a number, but you wouldn’t know that if you didn’t have the SDK.
It also lets you set known methods. So perhaps, you can’t delete a customer, so only have a GET customer method and your SDK, as an example. So nobody’s trying to call DELETE method on your API and then getting some strange error back, not knowing what to do.
It also allows you to make your API intuitive.
Accepting known parameters, like customer ID. Do you have any idea what the customer ID is? Probably not, but I bet you got their name. So make a “GET customer by name” function. And look, query string parameters, that’s not easy to know if you’re just using an API by itself. The SDK makes that easily known and usable.
Naming conventions as well. So, “ADD order,” you know, that’s going to put an order or maybe post an order. Um, and then update customer, things like that. Make it common, easy to understand so you don’t have these really long query strings that make it difficult to use. And then like I said, again, leaning on a language features. So throwing exceptions, throwing errors, having default parameters and strongly type parameters to like if you go to C#, you have a date time for the birth date and if the date time is minimum value, you can throw an exception. So things like that, not really possible with the bare, API usage, which is why you want to use the SDK.
And further, as people start using your SDK, you start adjusting to your use cases. So you can combine multiple calls to your API with a single SDK call. So say a common request is to GET orders by customer, you can combine that into one call. So behind the scenes you’re making two API calls, but the user of the SDK doesn’t need to know that they can just get order by customer not knowing what’s happening behind the scenes. And then, again, you can intelligently handle the errors. So you can combine the update order with the “create order.” So if you tried to update an order, it’s not found; then you create it and it’s a smooth transition for the user of this SDK.
Some of the benefits of SDKs: Fast and easy adoption.
So, one-line access to your API. You don’t have to worry, not that it’s not a good idea, you should always document your API. But with the SDK it could be self-documenting, if you will. So “GET customer,” and you know what that’s going to do and you don’t have to worry about what the, what the URL is, what the query string parameters, things like that. It’s safe. It’s optimized. So, you can use a default parameters, specify default limits, things like that to just help protect the user of your APIs. And then you can expand API functionality. So chaining calls, making it more intuitive, getting customer feedback—users of your SDK–figure out what they’re trying to do, combine things without having to adjust your core API because probably your behind the scenes services depend on the API working the way it is, but you don’t want to share that with everybody. So you update your SDK, sort of combine things and work it around.
So some, some tips for creating an SDK to begin with. It is generally easier to start with the same coding language that the API is written in. If your API is written in node.js, create an SDK for node.js, ship it, see what people think. And then start adding it when people start asking you where’s the Java implementation of this?
And then another tip is to avoid unnecessary dependencies. So most — if not all languages — have some sort of http client built into the language. So use that don’t depend on some third party that may go down, may have some sort of strange bugs in it. Use the language to avoid unnecessary dependencies. You could end up in dependency hell; it’s a mess. So SDK, super small and light, avoid any dependencies that you don’t need.
Then, add other languages as people start using it and asking for it. If some of the old guys in the back are still using Java and they want to use your API, listen to them and build up a SDK for Java. And then you know, as it grows, people will start using it more and you’ll start building more SDKs with more languages.
And then the other thing is to make sure it’s backwards compatible because you’re never sure what the client is using and you can’t force an upgrade. So with your SDK methods, make sure that it can handle itself and is always backwards compatible to avoid any sort of troubles and complaints.
That’s about it!