October 7th, 2013

SDKs or APIs: What’s the Right Choice for Your Developer Community?

SDK or APIWhen 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.

August 20th, 2013

APIs & Hackathons Solve the Innovator’s Dilemma

HackathonEach and every large enterprise began as a brand-new venture created by a few co-founders. The team was small, nimble and innovative enough to carve out a market leadership position through execution and differentiation. As the company grew from a few co-founders to 500 employees, 5,000 employees or 50,000 employees, its pace of delivering innovation slowed. Large companies such as Apple, Intuit and Facebook have continued to prove that this innovator’s dilemma is avoidable. For the rest of the Fortune 1000 – companies that don’t necessarily have access to the Silicon Valley magic – the trend in recent years has been to launch “innovation labs”.

One of the earliest examples of this was Bell Labs at Lucent, with many other enterprises now following suit, such as:

The question is: How will a small team within a large enterprise drive a cultural shift towards innovation and not get stifled by the old guard, which is simply stuck in old habits and processes? The solutions these innovation labs are bringing back to top executives almost invariably involve APIs and hackathons.

The first step is unlocking data via APIs. When a team of innovators at a large company is trying to achieve something disruptive and market-changing, the team members will need access to data from across the company. If they cannot get access, they will be delayed, get demoralized and often just give up and move on. When a company centralizes its APIs across all backend systems, it enables employees, partners and even external developers to build and innovate.

The companies with innovation labs mentioned above have also set up robust API platforms to enable innovation. Some APIs are only available to employees, some to partner companies and others are open to all software developers. The key concept is that they have removed the deadbolt locks on their data and replaced them with APIs that intelligently free those resources, auto-provisioning access based on who, how and what access is needed.

Opening up APIs enables innovation culture, increasing the pace of product design, creation and execution. Once these technology enablers are in place, enterprises can run internal and external hackathons to make developers aware of and inspired by what is now possible. These fast-paced competitions set goals to take creative ideas and turn them into prototypes or minimum viable products.

Hackathons are designed to help developers quickly try out new ideas and get instant feedback. This is similar to the iterative product development methodology described by Eric Reis in his book Lean Startup.  Some enterprises call it the migration from a linear process such as “waterfall” to more agile “scrum” or “customer-driven development” processes. Similarly, “DevOps” has been used to describe increased collaboration and communication between software development teams and IT operation teams.

This is how smart enterprises now solve the innovator’s dilemma. Product lines are reinvigorated and employees are inspired to be more entrepreneurial and productive.  Customers are getting products that take advantage of new technologies. Enablement through APIs alongside action through hackathons solves the dilemma and seeds continuous and disruptive innovation.

August 9th, 2013

REST Fest 2013 is Coming!

REST Fest 2013It’s that time of year again! REST Fest 2013 is less than two months away (September 19-21) and preparations and are in full swing. Now in its fourth year, REST Fest has become one of my favorite events on the calendar and I’m very much looking forward to being involved with this year’s event.

REST is Just the Beginning
This year the keynote will be delivered by Brian Sletten. And – judging from the title (and my knowledge of Brian’s experience and knowledge) – it will be a great talk. We’re honored that Brian accepted our invitation and looking forward not just to his presentation but also the resulting converstations and explorations that are hallmarks of REST Fest.

Everybody Talks
An important part of REST Fest is the principle that everyone who shows up must give a presentation. The talks are typically quite short: a five-minute “lightning” talk followed by a short Q&A session. There are a few 30-minute  “featured talks”, too. But the basic idea is that we all get to talk about things that are interesting to us and we don’t have to make a big deal about it.

Every year, I probably learn more than 30 new ideas and novel approaches to problem solving and get to talk to the people who are coming up with these great things. REST Fest is a fantastic boost to my creative spirit!

Everybody Listens
The corollary to our key “talk” principle is that we all get to listen, too. And listening is, in my opinion, even more important than speaking. REST Fest attendees come from all sorts of backgrounds, experiences and points of view. The chance to hear how others view the Web space, how others are tackling problems and how others are advancing the practice of services on the Web is always an eye opener.

Less Theory, More Practice
And that leads to another key aspect of the weekend. The focus is on doing, not theorizing. We’re a decidely non-pedantic bunch and are usually much more interested in cool solutions than compelling theories. While it may still be common to think of anything with the REST acronym in the name to be a meeting of pointy-headed geeks, that’s not us. Each year, I get to see actual code solving actual problems in the real world.

We Hack, Too
Every year, we also host a hack day where everyone gets together to work on cool REST-related Web stuff. This year, Erik Mogensen will be leading the day. From what I’ve seen, he’s got some cool ideas in store for us, too.

It’s Easy to Join Us
Just as we cut down on the ceremony surrounding speaking and participating in a conference, we also try to eliminate the ceremony around signing up and showing up for REST Fest. It’s quite easy:

  1. Join our mailing list to see what we’re all about
  2. Drop into the IRC channel to chat us up
  3. Hop onto the GitHub wiki and create your “people page”
  4. Head over to the registration page and reserve your seat for the event

There’s no waiting to see if your talk was accepted; no wondering if what you’re working on would be interesting to some review committee. Just sign up, post your ideas and head down to sunny Greenville, SC for a great weekend.

Need More REST Fest NOW?
Can’t wait for RESTFEst 2013 to get started? Take a look at our Vimeo channel with all the talks from previous years. There’s lots of very cool stuff there.

See you in September!

(Originally published on my personal blog.)

August 2nd, 2013

Getting Mobile Mojo Through App Innovation: The Enterprise View

Mobile MojoAPIs first found their footing among consumer Web sites wanting to transform into platforms. APIs let Web sites foster developer communities that could build apps anchored to their services. Innovative apps would attract new users to the Web site, help keep existing users engaged and –with a little bit of luck – make some money.

APIs Engage Developers, Developers Build Apps, Apps Enable Innovation
This virtuous cycle of APIs and innovation does not have to be limited to consumer Web sites. Enterprises have countless data and application resources distributed across their datacenters. All of these could be opened to internal developers via APIs. Done right, this could drive development innovation. Internal programmers with access to diverse internal information resources could build more compelling mobile and cloud apps, in less time.

Centralize API Discovery Through a Directory
Enablement is the starting point for getting developers building better apps, faster. Apps need data and APIs provide the windows into data, both inside the enterprise and out in cloud. Finding the APIs that front the data sources which enrich mobile apps is no easy task. Back in the days of SOA, service directories emerged as the vehicle for helping developers find software service elements that could be reused and composed into diverse business processes.

An API portal can assume a similar role in providing a centralized point of API discovery and reuse in mobile. An API portal provides the core directory, developer management and developer collaboration features that aid mobile innovation. It presents information on what data resources are available and how these resources can be accessed, along with documentation, code samples and so on, all in a simple Web-based format.

Inside vs. Outside Developers
For some time, vendors have been making API portals available from the cloud, with an eye to aiding the external long-tail developer. But that same technology brought inside the datacenter can also be used by internal developers. While external developers can provide a forum for experimentation and education, the real ROI for most enterprises will occur inside the DMZ. Making internal developers building mobile apps productive and agile will help organizations deliver effective consumer and employee-facing apps faster.
But to do this, the API portal will need to be brought inside the firewall where the enterprise will be able manage internal developers securely. This will increase productivity, which will result in more and richer apps, in less time.

Powering the Internal Developer
Having seen the potential service directories had for organizing internal development efforts, Layer 7 has effectively bridged the lessons of SOA to mobile. The Layer 7 API Portal is unique in that it can support classic SOAP services along with newer REST interfaces and can be deployed 100% inside the datacenter. This enables enterprises to use API portals strategically – not just for powering external developer communities. By placing itself at the center of an internal app-building ecosystem, the Layer 7 API Portal can spur innovation across mobile development teams.

June 10th, 2013

The WADL is Not Enough – Why API Documentation Matters

The WADL is Not EnoughAs I’ve talked about before, in our API documentation tutorial, documenting your API effectively is critical if you care at all about getting the maximum return from your design investment. It doesn’t matter if you are building a private API for a few selected partners or trying to build a company around a public API – poor documentation is going to sink your endeavor every time.

The challenge is that it’s really difficult to find people who are as great at documenting systems as they are at designing them. As a convenient shortcut, many API designers use tooling to auto-generate documentation. This often means exporting machine-readable interface description files like WSDLs and WADLs based on some type of configuration data entered into a development or testing tool. Assets like these are great for driving programmatic components on both the client and server side but they have limited value otherwise.

WSDL files, in particular, are popular in the SOA space because they allow client developers to auto-build proxy classes that can be invoked in the RPC style that is prevalent for SOAP-based integration. This advantage is diminished in the HTTP API world as we have moved away from this document binding style of interface to less structured forms of integration. But even putting this distinction aside, WSDLs have never provided an effective means of documenting SOAP systems and WADLs are no better.

Effective documentation implies effective communication. In the vast majority of situations, a standards-based XML description of your interface is not going to cut it. Application developers need to understand much more than the names and parameters of your API if they hope to build real applications in reasonable time-frames. This means you need to create documentation fit for developers – in other words, documentation built for humans.

Your documentation will act as a navigation system through the complexities of your API. Simply providing a WADL is the equivalent of providing a set of GPS coordinates to a tourist in your city. With the right tools, they may get there eventually but a human-readable map would provide a much richer and simpler experience. If you care about the developer experience for your API, you’ll spend some time and effort writing documentation that works.