Making a SDK for Your API in Node
Great companies have great API’s, that’s a given. What’s also a given, is that no matter how good, and well documented your API is, there will always be that one developer who is too lazy to follow your beautiful oAuth workflow. Lazy developer, is quickly followed by “I need autocomplete with everything I do” developer.
Neither of these developers are likely to use your API unless you gift them an SDK to use. And you know what, that’s okay, because 80% of all developers probably fall into one of those two categories. Probably both.
To that end, let’s give them an SDK they can use to cut down on the drudgery of using your API.
What makes a good SDK?
A SDK should be:
- Easy to use with a predictable pattern
- Handle authentication for the developer
- Easy to get. This means putting it on NPM.
- Well documented
- Well tested with CI integration.
The key factor here is trust and ease of use. When you look at a SDK, it should say “Use me, i’m reliable!” If your SDK is lacking in the reliability department, your company’s reputation may take a hit.
To help gain trust, I recommend signing up for Travis-Ci and Coveralls.io and displaying their “Build Status” and “Code Coverage” badges. These badges, displayed on your repository’s readme file are a good initial indicator of reliability.
To save you, and me, some work I created a boilerplate SDK that can be easily modified to accommodate your new SDK. It saves the you the grunt work of settings up unit tests, handling authentication, and a few other mundane tasks you would probably rather not do.
It’s well documented in the code and easy to follow.
- Repeatable, easy to follow pattern with extendable classes. Easy to get up and going.
- Built in Authorization support.
- Built in unit testing and code coverage with Mocha and Istanbul.
- Built in JSDoc support.
- Comes with a starter module (Ping)that can be discard or written over.
The boilerplate SDK makes heavy use of ES6 classes. However, it makes use of what could be considered an anti-pattern, static methods, for the bulk of the class methods. This runs counter to what you usually see, but is a pattern heavily used in .NET Web API.
This creates a very neat and repeatable pattern.
At the top, you have foo-api.module.js which contains the super class that all other child module classes are based off of. We can call this module FooAPI. The FooAPI contains static methods to effectively call your API in a repeatable mannner. The methods are:
These methods can be called in the child classes by using the super keyword. Let’s look at an example:
This way, if we create a new module, say a User module, it can inherit from FooAPI and use the same get method that has all of the logic needed to make a request. The FooAPI class already comes with logic to make the get request, including getting a token from the server.