DX, API Design & Documentation

SDKs for APIs: Generated or Bespoke?

310views

Your new application, along with its API, is going to change the world. You’ve spent months developing a decentralized social network for pets leveraging middle-out compression and blockchain. Now it is time to release your creation to the world! Providing a Software Development Kit (SDK) will simplify interactions with your API, smoothing the path for integration with existing apps and increasing the chance of a successful product launch. Weary from previous work, the thought of writing an SDK is not appealing, but it cannot be avoided. You have two options in front of you: use your OpenAPI specification to automatically generate an SDK, or write the SDK by hand. Both have pros and cons. What to do?

Set Your Goals

First, you will need to make a decision about the type of experience you want for your developers. Is it enough for your SDK to merely act as a “wrapper” for your API, or should you add additional logic or post-processing? Answering this will require you to think beyond individual API calls. Consider the typical workflows that will be performed through your API. If these workflows require multiple API calls with a great deal of data returned, it makes sense that your SDK should handle the logic required to facilitate the needed calls instead of leaving this up to the user. The data returned should be formatted or filtered in a way that is easy for the end user to consume.

 

Next, consider your release cadence. In all likelihood, you will release SDK updates as new features are released. A product with infrequent releases or a relatively static API will require less effort for development and support. Frequent releases with new features, on the other hand, can lead to development times that quickly spiral out of control. Automated testing is virtually required in this fast paced scenario, so you may wish to generate SDK releases as part of your CI/CD pipeline.

Know Your Users

Now that you’ve set some goals, it is time to put yourself in the shoes of your developers. Your social network app will likely attract seasoned developers that know their way around an API. But what about a different type of app, say Kubernetes for Fortran? This would probably attract infrastructure engineers with a moderate amount of development experience, at best. API use cases and consumers can span a wide swath, which is important to keep this in mind when developing your SDK strategy. Your goal should be to meet your users where they are in terms of technical capabilities. A novice user base will benefit from an SDK that is user friendly. Experienced developers will likely prefer a straight-forward SDK that maps closely to your API. 

Consider an example from an SDK I’ve spent a great deal of time working on, the Rubrik SDK for PowerShell. PowerShell may not be the first language that comes to mind when you’re deciding which languages to support via SDK, but in our case it makes perfect sense. Rubrik is typically deployed in data centers staffed with infrastructure engineers, and PowerShell has been a popular language for infrastructure automation for many years. Our PowerShell SDK was written by hand and designed in such a way that it is easy to extend, allowing us to add a good deal of functionality beyond basic API calls. We made this decision to provide a product that is easy for new users to learn. We have intentionally built in additional logic to make our SDK simple to use, hiding some of the “heavy lifting” that would be required with an auto-generated SDK. For example, most API operations in our product require the use of a Globally Unique Identifier (GUID), but our PowerShell SDK will allow users to perform operations by object name or GUID. If a name is provided, logic within the SDK will resolve the GUID from the provided name, then perform the API call once the GUID has been determined. While this is a trivial task for an experienced developer, this small convenience is an example of why our users love our SDK. Many of our users leverage our SDK for day-to-day management and automation of typical data protection tasks without requiring in-depth knowledge of our API, and it has become a differentiator for us.

Understand Your Capabilities

Now it is time to look inward to determine how much time and effort you will be able to dedicate towards SDK support and development. Staffing is a key consideration. If you are developing and supporting SDKs for Python, Go, and Ruby, you will need at least one engineer that is well versed in each language. Every additional language is going to add headcount to the Engineering team supporting your SDKs. Rapid release cycles will exacerbate this.

Tooling is another consideration. You may be in a position that necessitates auto-generating your SDKs, and there are several tools available to do this. If you choose an open source tool, will you have the resources to contribute code for new features you may need, or to help tackle bugs? Using a commercial tool may be a good fit, as long as it fits within your budget. What would happen if you had to switch to a different SDK generation tool at a later date? These questions require careful consideration before making a decision.

Now Get Going

As you have probably guessed by now, the answer to whether you should meticulously hand craft or simply auto-generate your SDK is: it depends. If you are supporting several languages with frequent product updates, auto-generating SDKs is likely the only feasible option. If you only need to support a handful of languages, or you want to include some “value add” in your SDK, bespoke is a reasonable choice. To further muddy the waters, there are some vendors that do both!

Once you’ve chosen your strategy, gather feedback from the developers using your SDKs. They will tell you what is working, and what is not. Be prepared to tweak your approach based on this feedback. There are strong and varied opinions on the best way to approach this conundrum, but in the end it will be up to you to find the best approach for your product.

Matt Elliott
Matt Elliott is a Developer Advocate at Rubrik with IT experience in several sectors, including healthcare, manufacturing, big law and VAR/MSP. He is passionate about all things networking, virtualization, automation, cloud, and monitoring. Matt is CCIE #56011.

APIdays | Events | News | Intelligence

Attend APIdays conferences

The Worlds leading API Conferences
with 9 Conferences in 2019:

Singapore, Zurich, Helsinki, Amsterdam, San Francisco, Sydney, Barcelona, London, Paris.

Get the API Landscape

The essential 450 companies

Get the API Landscape
Industry Reports

Download our free reports

The State Of Api Documentation: 2017 Edition
  • State of API Documentation
  • The State of Banking APIs
  • GraphQL: all your queries answered
  • APIE Serverless Architecture