Do You Publish API Docs Online for Availability to Third Party Developers?

This is second part of ProgrammableWeb’s series on Understanding the Realities of API Security. It is based on the testimony offered by ProgrammableWeb’s editor-in-chief David Berlind to the ONC’s API Security and Privacy Task Force.  In the previous part -- Part 1 -- Berlind addressed the following question: How Does The External Availability of APIs Impact Their Security?

While ProgrammableWeb does not have an API to document, we have catalogued over 14,500 APIs and we are therefore in a position to comment on the generally accepted practices of the industry when it comes to API documentation (both official, and unofficial).

Before continuing, it is worth noting that there is a fair amount of confusion regarding API classifications such as “public vs. private” and “internal vs. external.”

In classifying an API’s accessibility, ProgrammableWeb currently favors the terminology proposed by Netflix director of edge engineering Daniel Jacobson. Part-way through Netflix’s API journey, the company changed gears and, instead of making its API generally available to all developers, it limited API access to selected partners. Other organizations such as Walgreens and ESPN follow a similar model. Jacobson takes a novel approach to describing API availability. Instead of using “internal vs. external” or “public vs. private” to describe API availability, Jacobson uses "LSUDs" vs. "SSKDs."

LSUDs, otherwise known as Large Sets of (mostly) Unknown Developers, describes the sort of API access whereby the API is both external and public. For the most part, this means, in its most broadly accessible offering, there is no barrier, other than the API provider’s Terms of Service (which may require registration and/or payment), to using an API. Generally speaking, the API provider of such an API offers what’s known as an API portal through which those interested in the API can, in a sort try-before-you-buy mode, explore the API to better understand the degree to which it may satisfy the developer’s needs. This includes the ability to not only view the API’s documentation, it also includes sample code and, in a growing number of cases, an opportunity to sample a mock version of the API through an interactive console.

Generally speaking, most API providers who offer this sort of try-before-you-buy experience are targeting an LSUD. The expectation is that many developers will come and self-service themselves through the API portal. From the API provider’s point of view, it is most often a low-touch environment with almost no barrier to entry.

In contrast, an SSKD is a Small Set of Known Developers. The API itself may or may not be available on the public Internet (aka: “external”), but it may not be generally available to all developers. Instead, it is only available to selected partners or organizations/developers that the API provider approves of. Whereas Netflix originally took an LSUD approach, it pivoted to an SSKD approach. Today, Netflix’s APIs are exclusively available to partners. These are generally well-resourced companies whose offerings are well positioned to expand Netflix’s global footprint without compromise to to the end user experience. Sony, which makes Netflix compatible devices like the Sony Playstation, is one partner. When working with fewer partners, as Netflix does, it can also concentrate its resources on ensuring the best API security practices of those partners

All this said, here are a couple of important footnotes:

API providers can simultaneously take both an LSUD and SSKD approach. In this environment, developers could very easily be coming to the public portal that has been especially provisioned for them. Meanwhile, the API provider can have a separate program of SSKDs -- known developers who get special privileges or that the API provider works much more closely with.

It should be noted that the majority of API providers that ProgrammableWeb is currently adding to its directory also offer publicly viewable documentation, even to developers who have not yet registered to use the API (if such registration is required). Within the API economy, for APIs that are going to be offered for consumption on either an LSUD or SSKD basis, it is regarded as a best practice to offer such documentation as a part of the marketing effort for an API. In an LSUD context, where an API provider is hoping that tens, hundreds, or thousands of anonymous developers will unlock some new innovation using the provider’s API(s), the documentation and associated try-before-you-buy environment plays a very important role in attracting developers.

Likewise, API providers who take an SSKD approach to the market are often looking for qualified partners to help take their business to the next level. Given how any startup could potentially be that next big partner, public documentation plays an important role in business development and partner marketing. When it comes to API providers that target both LSUDs and SSKDs, ProgrammableWeb has observed (in the "wild") API providers that target both communities with a single developer portal as well as API providers that target both communities separately. For example, as can be seen from Trustpilot's developer portal, the API provider offers separate APIs; one for general public consumption (LSUD) and another for consumption by customers (SSKD). Trustpilot's introductory text says:

"Welcome to the documentation for Trustpilot Public and Customer APIs....The Public API provides you access to content available to the public on trustpilot.com. The Customer API provides access to features of our Business product available to merchants using Trustpilot. We use the exact same APIs for building our public website and business product.."

In contrast, Orange, the European-based telecommunications carrier targets two communities as well. But, it does this with separate portals.  For example, in a recent email communication, Orange said its partner.orange.com portal is "the hub for partners, start-ups and developers in order to plug into Orange innovation and develop business collaboration & partnerships." Meanwhile, the company's developer.orange.com portal was billed as "the place for developers to discover our growing portfolio of self-service APIs, and tap into our major platforms and services. This is a dedicated self-service platform.."

It should also be noted, especially given the subject matter of this hearing, that even when an API provider doesn’t offer official documentation for its API(s) (which can sometimes be the case for a variety of reasons including “security by obscurity”), a third party might offer an unofficial form of the documentation. Unofficial API documentation is sometimes an outcome after a third party has reverse-engineered an API without permission from the API provider. Third parties are known to publish such unofficial documentation for general availability on the Internet. A recent example of this involved the APIs for remotely accessing a Tesla automobile.

Furthermore, though not a form of directly documenting APIs, third parties -- open source developers in particular -- are known to independently publicly publish software development kits (SDKs) for accessing APIs. SDKs are language/platform-specific (Apple iOS, Java for Android, client-side Javascript, Ruby, Python, PHP, etc.) API abstractions that take some of the pain out of getting an application to work with an API. To the extent that these SDKs can serve as a proxy to the underlying API(s), the documentation of an SDK is essentially a form of documentation of the underlying API(s).

In the next part -- Part 3 -- of ProgrammableWeb’s series on Understanding the Realities of API Security, ProgrammableWeb editor in chief David Berlind answers the following question posed by the ONC:  How Do You Determine Who Gets Access To Your 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

Comments(2)

Madlyb

LSUD, SSKD...jeez.  Why do we have to make things complicated and honestly obtuse? 

We have been able to perfectly describe our APIs for years with just two attributes and two values for each attribute, environment (Internal/External) and audience(Public/Private).  Evironment is pretty self-explanatory as it simply describes on which network the endpoint resides and therefore to what audience is it accessible.  The second requires a little more context.  Public APIs are available to anyone who registers (and accepts a T&C) and Private is restricted only to our company and few select partners.

I guess there is an argument for describing an API that requires no registration, but we would never offer such an API for both Security and Support reasons.  I guess you could call this Anonymous.

But, you know lets go with something more vague because it sounds cooler.  Whatever.

david_berlind

Hey Madlyb,  thanks for responding.

I think you should go with what works best for you.  LSUD and SSKD came from Daniel Jacobson at Netflix whose views we have learned from (as we have also learned from the success of the company's API program).  We don't disagree with the way you've described APIs. We just think that, like with Netflix, a lot of decision that have to be made can be tied to those two distinctions.