SDK Patterns for Accelerating API Integration

I recently attended APIStrat 2016 in Boston, where there was plenty of discussion around the practices of providing and consuming APIs. One thing that was notable was the reemergence of SDKs for APIs. Rather than in previous years, the discussion wasn’t on SDK vs. no-SDK. Instead, the discussion was on the various ways we could empower API consumers to quickly integrate API providers into their solutions. Out of these discussions came four patterns on how API providers can offer SDKs to help their API consumers integrate quickly. Let’s revisit what an SDK is, and then examine these 4 patterns to see what may be the best fit for your API.

What Is an SDK?

A Software Developer Kit, or SDK, is a packaged solution that includes code for developers who wish to interact with a web-based API. SDKs target a specific programming language or runtime platform such as Java or the JVM, Ruby, JavaScript, PHP, Python, Perl, or Golang.

SDKs speed the integration process between a server-side, client-side, or mobile application and the web API. They often include one or more of the following:

• A client library for the specific programming language, removing the need to deal with the lower-level details of HTTP request and response.
• SDK documentation that describes how to use the client library.
• Example scripts and/or full applications that demonstrate SDK usage.
• Administration or CLI scripts for interacting with the API from the command-line to prevent the need for writing code for common administrative functions.

Are SDKs the Same as Helper Libraries?

Traditionally, SDKs include more than client libraries, as noted above. Some API providers offer helper libraries, which simply offer a language-specific distribution of a client library. All other resources often found in an SDK are hosted on their website for reference.

While there is a distinct difference between an SDK and helper library, many (like myself) tend to use the term interchangeably. The important thing is to be clear about what is provided in the distribution to set proper expectations with the developer. Providing a clear README file inside the distribution with links to additional documentation and resources is also a good practice, as it will help developers get started quickly.

SDK Patterns for API Providers

Now that we understand what SDKs are, we need to determine who will build and maintain them. There are four distinct patterns for providing SDKs:

1. Provider-Supported

Vendor-supported SDKs are built and maintained by the API provider. They own them, manage them, and keep them in sync as API endpoints are added or enhanced.

2. Community-Contributed

Instead of the vendor offering the SDK, the community contributes the SDK, often through GitHub or something similar. This may be the case for all SDKs, or just for less popular programming languages that the vendor has not offered. Vendors may choose to allow the community-contributed SDKs to thrive on their own, work with the author(s) to make them better, or eventually offer to take over maintenance of the SDKs. Be aware that community-contributed SDKs have a tendency to lose interest or available maintainers over time and may become abandoned. Communication with community supporters is critical, as many developers may assume they are vendor-backed and complain if they are no longer maintained.

3. Consumer-Driven

With the growth of API definition formats such as Swagger, RAML, Blueprint, and others, it is becoming easier for API consumers to generate their own client library from any of these formats. This gives the consumer the most flexibility, as they may opt to create a lightweight wrapper around the HTTP layer, or perhaps generate a robust library with objects/structures that mimic API resources.

4. HTTP Is the SDK

Those familiar with HTTP generally prefer working with it directly rather than through an SDK. SDKs often hide the lower-level details of HTTP and may prevent tuning API consumption to fit the exact needs of the use case. Offering examples using cURL and in popular programming languages can help get them started, without the overhead of needing to learn a brand new SDK library.

Which Approach Is Right for Your API?

Some have made the case that SDKs create more challenges for both API providers and consumers, preferring in most cases to simply offer well-documented APIs for developers to make HTTP requests. However, there are times when it makes sense. This is especially the case in the mobile space, where developers are accustomed to installing an SDK and coding against it rather than composing raw HTTP requests and handling the responses themselves.

Understanding your API consumer audience is the best way to make a decision. When in doubt, start with great documentation and using an API definition language such as Swagger, RAML, or Blueprint. Consumer-driven SDKs enable developers to work directly with HTTP, then generate their own SDK as desired. You can then begin to offer SDKs for specific programming languages when your team is ready to fully support them.