August 06, 2017
Launching an SDK is hard. You will have to get everything right before making the SDK public - else you will end up releasing an update the next day of your launch (experience is talking here 😅).
Here is a checklist that I came up with after following certain best practices I found on the internet and after revamping & releasing 8 server-side SDKs at work.
This checklist is broken down into the following 4 sections:
This checklist is designed to ensure smooth SDK releases and I recommend you use this for your existing and new SDK releases.
Here is what you must capture in your spec to avoid last-minute surprises.
User-Agents: If your SDK is going to send web requests, be sure to send a User-Agent from the SDK so you can analyze how your users are using the SDK & what they are trying to do. This helps in prioritizing bugs & issues later. I usually use the following format: library-name/semver-version (Language language-version). For example, plivo-python/4.0.1 (Python 3.4.2)
Proxies: If you expect enterprises or BFSI companies to use your SDKs, support the basic HTTP(S) proxies at the very least as most of the HTTP request packages in every language support these, and thus can be exposed with minimal effort. Also, if your API supports X-HTTP-Method-Override, then an appropriate interface should be defined.
Timeout: If you don’t support async requests, give a default timeout for each request so that the requests don’t take forever. This timeout parameter should be configurable, and you should raise a timeout error after the timeout is reached - your users can write a retry logic if they choose to.
Authentication: As a best practice, server-side SDKs should take the auth credentials from the system environment so that your users don’t need to check-in their authentication details in code repos. It also makes DevOps work much easier. In your spec, define the environment variable names where the authentication credentials must be stored. In the case of client-side SDKs, assume that attackers will go through the source code and attempt to gain unauthorized access. So, consider supporting a token-based auth for your API and define an SDK interface for the same.
Error Handling: There are just two simple rules for error handling - no known error should go unhandled and no unknown error should pass silently. Define all the SDK errors that should be derived from a base error so that your users can catch this base error and write some error-handling logic.
Now that the spec is done and you are ready with an alpha/beta version, use this checklist to catch issues early on. If you are going to release this alpha/beta publicly, follow the Public Launch checklist too.
Eat your own dog food: Start using your SDKs yourself as much as possible. Document every error you face and the steps to resolve them, and also the best practices to handle errors.
Give it out to customers: As with any other product, ship the alpha to customers and gather feedback around usability, issues, and errors they encounter. If you don’t have great instrumentation in place of can’t roll out a public alpha/beta, give it to a select customer base.
Testing: Test everything multiple times. Automate this by getting unit-tests and integration tests written. For most of the well-written SDKs, writing unit-tests is a breeze and achieving an 85%+ code coverage is normal.
Hard documentation: Every user-facing function and class must be documented. This should include all the parameters that are supported. Engineering teams ideally would be using some standard docs generator for the SDK language (Sphinx for Python, RDoc for Ruby, etc.,) to generate readable code-level documentation for the end-users.
Coding style and contribution guidelines: If you are going to make your SDK open-source, the code needs to be well written and well-documented so others can contribute to the codebase.
Soft documentation: All API endpoints, along with the HTTP verbs to be used and the parameters that are allowed must be documented. It is best not to have verbose documentation - it always helps to be precise and direct, but not at the cost of missing crucial information. Also, include code samples where possible. Assume that the users aren’t going to look at something that is right in front of them. For anyone who is wondering how good documentation would look like, look at Stripe’s documentation and their API reference. Simulate building the end-users’ use cases using this soft documentation so you know what is missing.
Example codes: Host all the example codes from documentation or tutorials in a repo so the developers who just want the code samples can directly take the code from there. Re-use these example codes in your soft documentation so users can follow the code. Test these codes multiple times.
Talk to the users: Select the alpha & beta users based on their profiles and be the point of contact for the SDKs. Give access to the soft documentation and let the development happen. Understand the issues they are facing and document all of them. You will then have to address these issues before going public.
This is great! These are the things you need to double-check to make sure your public launches go well.
Release notes & blogs: Have the release notes and blogs ready. Proof-read these multiple times. Mention what is it that changed from the previous version. Include a migration guide if you expect your users to move to the new version.
Brace for impact: Make sure all your team is ready for customer queries and issues. Hold training sessions for your support teams if needed. Record video tutorials and do webinars if required.
CI & Testing: Have mocked unit tests and integration tests written for every functionality, including utility functions. I usually specify an 85% code coverage for every resource before launching a stable release. Make sure to test whether the right URL is being hit with the right HTTP verb. If your SDK manages some serialization & deserialization of parameters, then that has to be tested thoroughly to make sure the data is being passed the right way. The last thing you want your end customer to do is to write try-except blocks for everything.
Congrats on the SDK launch. Here are a few things to close the loop!
Lessons learned: Document the lessons learned and update the relevant internal documents for future reference.
Deprecating older SDKs: Work on deprecating the older SDKs as managing multiple versions will be a huge pain, both for your users and you. Monitor the usage of the new SDK based on the user-agent values.
That’s all I had. All the best for your launch!