We have taken a deep look on javascript npm package ecosystem and one may ask a natural next question: what is a relation 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 details of how APIs work. What I want is to try APIs, see the results, and start using 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 Reference .
Say hello to experimenting with APIs from the command line The most basic approach for API testing is to use a command line tool like ‘curl’. Typically, API documentations provide examples of [command line usage] (http://www.ibm.com/smarterplanet/us/en/ibmwatson/developercloud/language-translation/api/v2/?curl#translate), which developers can just copy & paste. Consider this example: curl -u "{username}":"{password}" "https://gateway.watsonplatform.net/language-translation/api/v2/translate?source=en&target=es&text=hello"At this point it is easy to test an API by using test credentials:
$ curl -u 5e2bd14a-d577-4b4d-b4ca-2d0e30041cce:YxdS26iGii0W "https://gateway.watsonplatform.net/language-translation/api/v2/translate?source=en&target=es&text=hello" HolaThat command returns text. To get more information, developers can request data being provided in JSON format by setting the Accept HTTP header correspondingly (see API docs for details):
$ curl -H "Accept: application/json" -u 5e2bd14a-d577-4b4d-b4ca-2d0e30041cce:YxdS26iGii0W "https://gateway.watsonplatform.net/language-translation/api/v2/translate?source=en&target=es&text=hello" { "translations":[ { "translation":"Hola" } ], "word_count":1, "character_count":5 } Say hello to experimenting with APIs from the browserAPI specifications, if available for an API, make it also relatively easy to provide an interactive web browser page to invoke an API without any coding. However, unless a service is publicly available, developers need first to get test credentials like an API key, or, in our case, create an instance of the translation service in Bluemix to get credentials. . The translation service has an API explorer . After clicking the link to the API explorer in the browser and filling in credentials (typically the username and password; in the top right side of page) it is easy to test an API by specifying required input (e.g., {"source": "en", "target": "es", "text": "hello"} ) and just pressing Try it out! button.
Hello API using SDK for my PROGRAMMING LANGUAGEThen as a next step let look on how to call that API from my code. Let assume that I already have a Node.js application. A lot of API documentations have example code for popular programing languages such as Node.js: for example, the translation service documentation gives me:
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 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 Using REST API directly from PROGRAMMING LANGUAGEWhat if there is no SDK for an API? As the translation service has a REST API, it can be accessed using HTTP. Let go back to Node and see what can be done when Node SDK is not available. Let’s write code in JavaScript that uses the popular request package :
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); });After modifying the code, again, to use your credentials and saving it to translate-request.js we can again run it:
$ node translate-request.js HolaThat code is using the request library to make an HTTP requests and handle the response. Here, we have to perform additional work and lower level abstraction than accessing the service’s translate() method from the SDK (see above).
Why to use SDK over accessing REST API directly?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 task can be non-trivial if the REST API uses more complex authentication schemes such as OAuth, or even has its own protocol.
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. For scripting languages SDKs can provide value by providing 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.
What if there is no SDK for your LANGUAGE?If an API has a formal definition, such as Open API Initiative (OAI) aka Swagger 2.0 , it is possible to generate SDKs from the API definition. If there is an official API definition available then it should be used. If not there may be an API definition available elsewhere (for example, the APIs Gurus project provides quite a few definitions).
And, of course, if there is no SDK for your programming language and no formal definition of API you can write code to access an API using any HTTP library (available in every programming language) and maybe make it into SDK eventually?
More is better? Can there be too many SDKs?The Watson SDK was a great scenario: there is an official SDK available for several programming languages. But what happens if there is no official SDK for your programming language? Or if there is more than one available? Or if there are unofficial SDK libraries that are popular and may be a better fit for your project or programming style?
As an example, consider the IBM Cloudant database-as-a-service . It provides a REST API and there is the nodejs-cloudant library, which is the official Cloudant SDK for Node.js. However, Cloudant is based on open-source project Apache CouchDB and provides the same API (with some extensions.) There are, thus, open source SDKs that work with CouchDB and will also work with Cloudant, including the official CouchDB SDK . And there are many more SDKs and libraries available for CouchDB and Cloudant - for example see this list of libraries for Node.js .
Depending on whether I am only going to use either Cloudant or CouchDB or both (for example, use CouchDB for local testing and Cloudant for production deployments) the choice of SDK may be different: can it work across CouchDB and Cloudant? Can it use Cloudant extensions? And, of course, there is also the Cloudant REST API that is easy to use directly with HTTP library from any programming language.
Different choices for using REST APIsA big advantage of REST APIs is that they are based on open standards. That means that, as a developer, I do not need to use an SDK to access API form my code. I can always use HTTP library directly and code may not be too much bigger (see example of code using request library above in Node.js and compare it to the code that is using the SDK).
The other good news is that SDK libraries are typically open sourced and that makes it easy to modify them to fit your needs and to contribute your changes so that the whole community of developers can benefit. And if, for some reason, an SDK is not meeting your needs you can fork the code to make your modifications. Or write your own SDK!
However, official SDK libraries for given programming languages are typically better supported than non-official open source alternatives.
HOWTO: Best SDK for API in few easy stepsAll those considerations lead to a situation where choice of SDK is a multi-step process. Here is algorithm that I use:
- if there is an official SDK for your language that meets your requirement use it (great!)
- if the official SDK does not meet your needs and it is open sourced and you can make necessary modifications then make your modifications and consider contributing it to the open source project
- if there are multiple SDKs then you need to evaluate them - do research and try to find SDK that is well supported (this may be difficult as SDKs may get outdated but still appear in the top results of search engines)
- if there is no SDK for your programming language, you are back to using an HTTP library and maybe writing your own utility methods - which could evolve into an SDK eventually. If that happens, consider turning it into an open source project to share with developers and benefit from a collaborative development process.
Conclusion: less is more?Deciding how to access an API involves a lot of steps and choices - but lucky for developer, most of time there is one choice that works (first step) - and that is to use an official SDK.
Trying to avoid making choices means more work needs to be done, i.e. writing an application that uses bare HTTP to access an API instead of researching SDKs.
For us, a question that arises is: if there is more than one choice, can we help developers make informed decisions faster? We may have more on that question posted here in future…