APIful Blog We're obsessed with Web APIs


Why APIs need SDKs?

Jun 10, 2016 •

We have taken a deep look on JavaScript npm package ecosystem and one may ask a natural next question: what is the relationship between APIs and SDKs (such as npm packages)?

Why do we need SDKs for APIs anyway?

As a developer I do not want to spend much time learning the details of how APIs work. Instead, what I want is to try running APIs, see the results, and start using these APIs in my applications. Typically, that leads to searching for APIs using a search engine with keywords like “translation API”. I could also use an API discovery services such as our API Harmony, providing a web page that describes the REST API exposing a translation service. As an example, consider the IBM Watson Language Translation Service API.

Using REST API directly from my PROGRAMMING LANGUAGE

Let’s look at how to call that API from an application without any SDK. Let’s assume that I already have a Node.js application. Web APIs provide REST API and HTTP is supposed to be easy so why not to use it directly? As the translation service has a REST API, it can be accessed using HTTP. Let’s write the code in JavaScript for Node.js that uses the popular request package to make an HTTP request and show the response:

var request = require("request");
var options = { method: 'GET',
  url: 'https://gateway.watsonplatform.net/language-translation/api/v2/translate',
  'auth': { 'user': '5e2bd14a-d577-4b4d-b4ca-2d0e30041cce', 
            'pass': 'YxdS26iGii0W', 
            'sendImmediately': true },
  qs: { source: 'en', 
        target: 'es', 
        text: 'hello'} };
request(options, function (error, response, body) {
  if (error) throw new Error(error);
  console.log(body);
});

As the translation service is not publicly available, developers first need to get test credentials like an API key, or, in our case, create an instance of the translation service in Bluemix to get credentials.. After modifying the code to use your credentials and saving it to translate-request.js just run it:

$ node translate-request.js
Hola

Hello API using SDK for my PROGRAMMING LANGUAGE

A lot of APIs have in their documentations ready-to-run code for popular programming languages such as Node.js: for example, the translation service documentation provides that source code:

var watson = require('watson-developer-cloud');
var language_translation = watson.language_translation({
  username: '{username}',
  password: '{password}',
  version: 'v2'
});
language_translation.translate({
    text: 'hello',
    source: 'en',
    target: 'es'
  }, function(err, translation) {
    if (err)
      console.log(err)
    else
      console.log(translation);
});

The sample code is using watson-developer-cloud SDK npm packgage. To run that code we need to modify the example code to set the credentials:

var watson = require('watson-developer-cloud');

var language_translation = watson.language_translation({
  "username": "5e2bd14a-d577-4b4d-b4ca-2d0e30041cce",
  "password": "YxdS26iGii0W",
  version: 'v2'
});

language_translation.translate({
  text: 'hello', source : 'en', target: 'es' },
  function (err, translation) {
    if (err)
      console.log('error:', err);
    else
      console.log(JSON.stringify(translation, null, 2));
});

After modifying the code to use your test credentials, save it to translate-sdk.js and run:

$ node translate-sdk.js
Hola

Why to use SDK over accessing REST API directly?

The sample code snippets above look similar both for SDK and using HTTP library directly. However, there are several differences. Probably the most important is the amount of work involved from a developer’s point of view. When using REST API with HTTP library directly, developers need to write their own code (unless code snippets are available such as generated from API specification for programming language library.) When using an SDK typically in the SDK documentation there is already sample code and developers just need to copy the sample code and modify it to fit their needs (as shown above.) If there is a service, like API Harmony, that can take API specification and generate sample code for a programming language HTTP library then amount of work is similar to using SDK. Another possibility may be that SDK can be generated based on API specification. And as we know: the less code is being written that is already in (SDK) libraries, the lower the probability of bugs and developers wasting time on debugging.

An additional concern is what happens when API is updated? When using an HTTP library directly a developer will need to change HTTP calls. In case of using SDK that may be avoided as SDK library provides level of abstraction and it may allow using functionality (such as translate method) without any change as long as SDK library is updated.

Additional considerations: when using REST API directly we have to perform additional work and lower level abstraction in order to access the service’s translate() method from the SDK. That leads to the typical situation where developers write utility functions, such as translate(), to make HTTP request to REST API and return results. As shown above, accessing a REST API directly is easy - but it can be error prone if the code making the HTTP requests is written by hand. In particular, the utility code may be non-trivial if the REST API uses more complex authentication schemes such as OAuth, or even has its own security protocol. SDKs can simply save all that work and avoid bugs as SDK code is well tested and easy to use by copying code samples from documentation. That does not mean that every SDK library is high quality or well tested but the quality of SDK should be better as it is used by more developers than an app utility code - as the saying goes “given enough eyeballs, all bugs are shallow.”

And there are concerns that are independent from REST APIs: if an SDK is used with statically typed languages, the compiler can check if the REST API methods from SDKs are used correctly before they are invoked (parameter types, URL string, etc.) As SDKs are libraries they can provide additional value by creating programming language API that is more idiomatic and feels “native” to developers than making HTTP requests or writing ad-hoc utility methods that hide HTTP details.

Making the life of developers easier is one of our main goals: we want to make writing high quality code that uses REST APIs faster and we hope API Harmony will become an important tool in achieving this.

Share via a Tweet or follow us for everything APIs!