Why ProgrammableWeb Refers to a Javascript API as an SDK

A few years back, ProgrammableWeb had four directories; the API directory (what ProgrammableWeb is famous for), the Mashup (app) Directory, a directory of mashup source code that was discovered elsewhere on the Web, and a resource directory that was a mish-mash of anything else that could be helpful to API practitioners (developers, providers, etc.). If we came across something relevant that didn't qualify as an API, a Mashup, or source code, we tossed it into the fourth bucket. This included things like software development kits (SDKs), frameworks, and libraries and there was no clear understanding of what these terms meant. What was a library to one person was an SDK to another. If you were looking for an SDK and it was classified in our resource directory as a library, chances were you wouldn't be able to find it. 

As we leaned back to look at how helpful our directories were to our audience, we also saw the rising importance of the SDK. SDKs, if you're not familiar with them, are language specific tools that make it easier for software developers to work with a technology. That technology could be a mobile operating system like Android, an application server platform like Enterprise Java or .NET, a hardware driver like a TWAIN driver for controlling a scanner, or, in our case an API. SDKs make developers more productive by giving them the equivalent of shortcuts that would otherwise take longer to code if they had to work in the target technology's native mode. Those shortcuts bridge the gap between the developer's preferred language and whatever the target technology understands natively. 

So, in the case of Web APIs, SDKs essentially obviate the need for developers to understand the semantics of HTTP verbs, HTTP header construction, the URL path to the resources available through an API's endpoint, or how to serialize or deserialize JSON or other payloads. Depending on the API, there's no telling what language specific SDKs are available for it. For example, the provider of an API that's more likely to be used by server side applications might be more inclined to prioritize SDKs for server-side platforms like PHP, Python, Ruby and Node.js (server-side Javascript). In contrast, the provider of an API that's more likely to be consumed by mobile applications might be more inclined to prioritize SDKs for Android and iOS. And for the not so popular langauges and platforms, it's not uncommon for open source developers to step up and offer their own SDKs. We see this all the time.  

Automated SDK creation is now among the many beneficial outcomes (like automated documentation and automated test harnesses) of using API description specifications like the OpenAPI Specification or RAML. But they have their downsides too. For example, one downside is that an SDK typically requires more system resources at runtime (not good if such precious resources are scarce) when compared to the resources when working directly with an API. And, while SDKs include many shortcuts designed to make a software developer more productive, the shortcut you most need might not be included. 

As we watched the interest in SDKs explode, we knew it was time to set aside a special directory just for them. This way, developers could not only come to ProgrammableWeb to search for SDKs (in addition to APIs), but they could also start their search by looking for the right API, and from there, find a list of SDKs that supported it. On our API profiles, the SDK tab is now just one of many tabs that you can click in order to find resources related to an API as illustrated in this partial screenshot of our profile of the Twitter API:

We did this with the best interests of developers and API providers in mind. One thing that developers look for in an API is a solid list of SDKs that support it and we aspire to help them answer that question. On the flipside, API providers can now populate our SDK directory in a way that might convince developers of their commitment to providing a great developer experience. In the case of unofficial SDKs that come from open source developers and other third parties, we are constantly hunting those assets down and adding to them to the SDK directory ourselves. These services are free of charge and we know of no other destination on the Web that makes it possible to search APIs and any associated SDKs (official or unofficial) in this way, and without restriction. 

As can be seen, just this one modification forced us back to the drawing board for both our user experience as well as our data model (for more on my thoughts about data models, be sure to read Why Forcing LinkedIn to Allow Scrapers Sets a Dangerous Precedent for the API Economy). This was all done with ProgrammableWeb's  end users in mind. 

But as we reconsidered that data model and the data we had, we encountered one interesting wrinkle. There were hundreds of APIs in our API directory that referred to themselves as Javascript APIs. We had no other language specific directory entries called something like Python APIs. Or Ruby APIs. Somehow, the API economy was viewing Javascript APIs as a special type of API. 

In fact, althought Javascript APIs are a language specific means of accessing an API (just like an SDK), they are usually architecturally different from other SDKs. Whereas the codebase for other SDKs is usually incorporated, in-full, into a developer's local integrated development environment (IDE) when developing an application (and the resulting application gets installed somewhere), the majority of the codebase for a Javascript API (for example, all the code behind the aforementioned shortcuts) lives at a specific URL-referenceable location on an API provider's server (and the resulting application doesn't get installed anywhere).

The genesis of this architecture is no doubt related to the way browsers work since, generally speaking, they have to pull all of the instructions need to paint a page -- the HTML, the CSS, and the Javascript -- from a Web server. For the most part, browsers don't keep those instructions locally (although, as browsers' local storage capability improves, you can expect to see more Web apps cached, if not installed locally).  Had the scripting language for browsers been Ruby, then we would have seen Ruby APIs instead of Javascript APIs. But it's Javascript and in the case of some of these so-called Javascript APIs, there wasn't even a RESTful alternative for developers to work with natively.  Ergo, "Javascript APIs."

Once we took the time to understand this edge case, we had to decide what to do about it. Should these so-called Javascript APIs continue to remain in the API directory? Or should we declare them to be SDKs and move them to the SDK directory? The answer, not suprisingly, was derived from our aspiration to always solve for the best user experience. Developers should be able to search for an API and once they find it, they should also be able to discover all of the language specific tooling for it. Even though Javascript APIs are called "Javascript APIs," at the end of the day, they are language specific tools for consuming APIs that, in our opinion, should show up in the same list as the other language specific tools for consuming APIs. In other words, that's where developers would expect to see them listed. 

And so, this is why, when we see something that refers to itself as a Javascript API that's really just a Javascript-specific way for accessing some other resource that's across a network (in other words, it's not a browser API for doing something locally like reading a smartphone's battery status), we call it a Javascript SDK. This rule is subjugated to a more overarching rule that any language specific tooling for consuming a specific API is, in ProgrammableWeb's lexicon, an SDK. "Library," on the other hand, is a term that's predominantly reserved for language specific tooling for standing up an API or some other process to support an API.  

We know this is an opinionated view and that not everyone agrees. But rather get into a religious war about semantics, we just want to enable the best possible user experiences. As long as we're consistent in our U/X and in how we categorize assets like APIs, SDKs, libraries, and frameworks, we are enabling other great soon-to-come ProgrammableWeb experiences such as power search (ie: show me all Social APIs for which there are Javascript SDKs) and our very own API. 

David Berlind is the editor-in-chief of ProgrammableWeb.com. You can reach him at david.berlind@programmableweb.com. Connect to David on Twitter at @dberlind or on LinkedIn, put him in a Google+ circle, or friend him on Facebook.
 

Comments