All Posts

Does your REST API need an SDK?

Introduction

When integrating with a platform that offers a REST API, a developer sometimes has the option of downloading the client library in their language of choice, or writing HTTP code themselves to integrate with the API directly. You as an API provider should decide early on if you wish to offer SDKs to your customers.

REST, SOAP, and WSDLs

REST in its simplicity has generally been considered less of a barrier to entry than more cumbersome SOAP APIs, despite not having the assistance of a WSDL to aid in generating client code easily. One of the things that made REST simple was the flexibility in its design. As a consequence, for a long time there was not a common, standardized way to describe a REST API’s interface. Swagger has recently come to fill this void, even offering a tool to autogenerate client SDKs via swagger-codegen. However, these tools for REST APIs are fairly new. Hand-written SDKs have been offered by quite a few API providers for the past several years, their necessity varying from provider to provider.

Case study: Braintree

Braintree, a platform that makes it easy for your application to accept various forms of payment, does not offer a public REST API. Instead, they choose to deliver their platform through language-specific client libraries that they maintain. They have a wonderful write-up here. Things to note in the case of Braintree:

  • Their API is their business, and they need to do anything they can to make sure that clients can integrate easily.
  • They are in a space (payment processing) where security and application correctness are incredibly important.

For Braintree, SDKs make sense. They allow clients to integrate quickly with a complicated workflow and can abstract away things that the client doesn’t necessarily care about. For your API, it might also make sense to have an SDK if your API has non-trivial functionality such as a complicated authorization scheme, binary data serialization, request signing, etc. This is especially true if your clients do not need to customize any of this functionality.

Case study: uShip

We at uShip started our API platform with SOAP (which, to my surprise, looks like it is still in use here o_O). Eventually, we moved to a more RESTful approach, especially in anticipation of releasing native mobile apps. Things to note about our case:

  • Our mobile and web platforms are our business. A majority of external API integrations simply push customers to our platform.
  • Most integrations by third parties are limited in scope (targeted to a small subset of the markets we support) and therefore consume a very limited amount of easy to consume REST APIs, which makes the need for an SDK not as important.

For uShip, SDKs do not make sense as a necessity yet. Integration against our API via the REST interface is quick and easy. For your API, an SDK does not make sense as a necessity if your SDK does not offer much beyond simple HTTP bindings, especially if you don’t have the developer resources to maintain the SDKs in terms of bug fixes, new features, and availability on many platforms. This isn’t to say that you should not offer an SDK. Some form of example client interaction is always useful to a prospective integrator. Even if this means that I as a developer only end up using your DTOs (which are easy enough to automatically generate).

Automatically generating SDKs

When writing an SDK by hand, most of your code usually ends up looking like the following:

public class NounClient
{
  private final String BASE_PATH = "https://api.example.com";
  private HttpClient _httpClient;
  
  public NounClient() {
    _httpClient = new HttpClient();
  }
  
  public Noun getNouns(string filter) {
    String resourcePath = "/nouns?filter=" + filter;
    HttpRequest request = new HttpRequest(BASE_PATH + path)
    HttpResponse response = _httpClient.Execute(request);
    return response.Content.Deserialize(Noun.class);
  }
}

The resource names will be different, and you might add a couple of helper classes that allow a client to interact with your API easier, but a lot will look like copy-paste. With hand-written SDKs, there is a huge amount of boilerplate code that adds very little value for consumers, which means lots of wasted development efforts on your part. As developers we know things like this can and should be automated.

With the aforementioned tool swagger-codegen, it is possible to take a swagger spec and automatically generate client libraries. The default template can get you pretty far (especially if you lack resources in a particular programming language), but the real power comes in being able to write custom templates to generate the boilerplate. This allows you to spend your time designing an SDK instead of dealing with boring HTTP code. For the longest time we didn’t have any sort of SDK, but having something autogenerated lets us dip our toes in the water. Now we have something that internal (or even external) projects can use to quickly build a prototype application.

Conclusion

Whether you want to offer an SDK depends on the experience you would like your client to have, and that ultimately comes from how your API was designed, but no SDK will make a poorly designed API easy-to-use. A chatty API could lead to chatty code, or at the very least high latency between calls. Covering up a bad API with an SDK will inherently make the client complicated and could lead to possible bugs. Regardless of the existence of an SDK, good documentation with pertinent examples of common integration patterns is a must.

[amp-cta id=’8486′]