When creating an application programming interface (API) for a service, one of the key decisions any program or product manager will face is how best to meet the needs of their prime target audience: developers. Faced with this decision, you want to make sure your API is easy to use and doesn’t represent a high barrier to entry for your specific developer audience.
Currently, the typical approach is to design an interface that leverages the most common protocol on the Web today: HTTP. This is often labeled a “RESTful” API (referring to Roy Fielding’s architectural model for the World Wide Web) and offered as a one-size-fits-all (OSFA) model for developers to use when building client applications for a service. But this is not always the best approach.
Properly understanding and implementing a raw HTTP interface may be too complex for some segments of your developer community – some of whom are really only interested in your service and not in spending time to build a killer HTTP application for that service. Additionally, a generic HTTP API might end up compromising key performance aspects of your service in order to work best for a wide range of developer communities (the OSFA problem). Even worse, an HTTP-based API may – in the end – result in unfocused client applications built by developers who know more about HTTP than your service.
What We Learned from SOAP
One of the powerful lessons learned from the SOAP community relates to the value of developer tooling. The SOAP Web Service Definition Language (WSDL) is a complex, difficult-to-read document that contains all the important details on building a compliant client application for a service. And developers have a hard time making sense of the document. To solve this problem, the SOAP community helped promote an “accommodation” for developers – the “WSDL” button that is available on many code editors. By simply pressing this button and following a few prompts, developers can easily create API facades for servers or consume WSDL documents to build client applications. The WSDL accommodation makes SOAP programming not only easy, it adds to the usability of SOAP interfaces and lowers the bar for developers wanting to use services on the Web.
What We Lost with HTTP CRUD
The rise of JSON-style HTTP CRUD (Create-Read-Update-Delete) programming interfaces meant the loss of the WSDL accommodation. Developers were expected to hand-craft both the server and client interfaces without the aid of a unifying definition document like SOAP’s WSDL. To make up for this loss, server coding environments like Ruby on Rails introduced helper functions (e.g. “rails new”) designed to generate a great deal of the API facade required in order to publish a service on the Web. Developers could use this accommodation to simplify the interface details and allow them to focus on crafting the internal object and business modeling needed to make the service operational.
Client devs needed to create their own accommodations, too. That’s why we have client-side libraries like ember.js, backbone.js, angular.js and others. Like the developers building servers, client developers needed help handling the basic plumbing for HTTP-based applications, so they could focus on their own object models and business logic.
The bad news is, in this HTTP CRUD world, each and every service has its own unique set of URLs, objects (users, products etc.) and actions (approve, remove, edit, apply etc.). And each API looks like a snowflake among hundreds of other unique interfaces. For example, there are more than 500 unique APIs for supporting shopping services. This can raise the bar for developers and lower the usability of HTTP CRUD APIs.
Adapter APIs
Netflix set out to solve the OSFA problem in 2012 by embracing differences in its developer community and creating a set of targeted “adapter APIs”. These are custom interfaces optimized for selected developer communities. For example, Netflix offers one API for its XBox community and a slightly different API for its PS2 community. In fact, each major device has its own custom API.
What’s interesting about the Netflix approach is that the customized interface accommodations live on the server, not the client. In other words, Netflix has taken on the task of optimizing its interfaces for each community and hosting that optimization on its own servers. A client developer will still be using an HTTP API but it will be one tailored to a specific device – a server-side custom library.
Do SDKs Provide the Answer?
Another way to provide solid accommodations to your HTTP developers is to create software developer kits (SDKs) for your service. Essentially, SDKs provide the same accommodation that WSDL-generated client code does for SOAP interfaces. The good news is that well-designed and executed SDKs can lower the bar for developers and increase service usability.
Recently, Evernote announced that it was taking the SDK approach. One reason for this was Evernote’s decision to use the Apache Thrift message model. The Thrift approach serializes messages using a custom binary format and then ships them across the network using one of a handful of transport protocols (including direct TCP/IP). This is pretty low-level stuff and can easily intimidate some client developers – raising the barrier to entry for Evernote’s API – and this is where creating an SDK is a handy approach. Evernote has committed to building a wide range of language-specific SDKs that clients can download, install and use in their own code. This accommodation lowers the bar when using the Thrift model.
The bad news is that creating SDKs is often a recurring additional expense for your services team. Unlike the WSDL standard, which makes it possible to generate code for a wide range of programming languages from a single published definition file, SDKs usually need to be hand-built for each target programming environment. And selecting target programming languages can turn into a slippery slope. Which languages are most used by your current API consumers? What if the most-used language represents only 30% of your target audience? How many SDKs do you need to build and maintain before you reach a significant portion of your developer community?
The maintenance of SDKs can be substantial, too. How often do you release updates? Fix bugs? Provide new features? Each release can mean added cost to your developer community as they need to open up their own code, integrate the new SDK, run tests and finally re-release their apps to their own target communities. Unless carefully done, this can result in added churn and expense all around – including deployment and download costs for end users. And that can raise the barrier to entry and lower usability.
So What’s a PM to do?
When you start to think about the notion of creating accommodations for target audiences, you have a new metric for assessing the usability and value of your service interface. If you can design an API that is easy for your target audience to use, then you (and your developers) win. If your API is too complex for your audience or relies on a less-used technology, you likely need to include more direct accommodations for your developers.
In some cases, the audience will know how to use SOAP interfaces and will benefit from you offering a WSDL as their accommodation. In other cases, the target audience won’t want/need a SOAP interface and a well-crafted HTTP API (or possibly a set of targeted adapter APIs) will be the right choice. Finally, some target developers will want/need an SDK to handle the protocol details and allow them to focus on their own business logic.
In fact, sometimes the best bet is to offer more than just one of these options in order to reach all your target audiences. Your enterprise partners may prefer a SOAP interface, your mobile devs may prefer a well-design HTTP CRUD API and your business and marketing team may prefer an SDK that exposes only the parts of your service they need to use.
You Own the Interface
The key point in all this is that you own the interface. You can cast your service in many different ways, aimed at several different audiences. You don’t need to stick with a OSFA approach and you don’t have to rule out major technology sectors like SOAP just because a portion of your audience prefers one interface style over another.
By focusing on your target audience and learning their skills and preferences, you can identify key metrics that can drive the selection of the right mix of API styles and accommodations that will help you meet your goals for API reach and usability.
