In last week's editorial, Dr. Dobb's editor Andrew Binstock discussed how APIs, especially for cloud-based services, are providing the new model of component reusability. In this editorial, I'll explain how to design APIs to make them attractive and easy to use for the target developers.
- The Essential Guide to IT Transformation
- Consolidation: The Foundation for IT Business Transformation
- Simple, Effective Patch Management: From Dilemma to Done Deed
- Thwart off Application-Based Security Exploits: Protect Against Zero-Day Attacks, Malware, Advanced Persistent Threats
As APIs grow in popularity, the developer user experience as API consumers will be a significant area of focus. Getting developers to realize the value of an API platform requires sensitivity to the related needs and challenges of technical integrations. By focusing on and understanding developers, an API publisher can drive true engagement and achieve the technology and business goals it has set for its platform. As APIs become more common and developers have access to a growing range of options many of which provide similar benefits API publishers need to differentiate themselves by providing an exceptional developer user experience (or Dev UX).
API Brand Experience
An API will often have its own dedicated portal, which is usually a sub-domain separate from the API publisher's main website. The team that owns this portal is charged with building the API infrastructure, architecture, security, and access mechanisms. These core technical aspects are usually the main focus of an API program; and making it easy to discover and access the API may amount to little more than an afterthought. As more APIs are being offered through Web portals such as http://developer.com, traditional UX research and testing are becoming increasingly applicable to APIs. The major principles of UX can help improve the discoverability and accessibility of an API. For example, by using a Web analytics system on your API portal and combining the data with analytics from your API management system you can begin to get insight into how your API is being received.
Easy API Access
The sign-up form for API access is a critical aspect in determining how developers embrace an API portal. Website forms are often measured by the amount of friction they place on the user, and how often users drop off without completing the sign-up process. Seeing the sign-up form as a place to obtain more information about the developer and their intentions, API publishers often require developers to register with a new account that is just for that single API platform. However, this can often be a roadblock and cause developers to seek other APIs that don't require as much work to get started. One great solution to this is to provide single sign-on via OAuth, Github, LinkedIn, or Facebook identification, which greatly reduce "registration friction." If using Github for sign-on, the API publisher can also profile the developer automatically, obtaining more information about him or her via the Github API.
Easy API Discoverability
Explaining exactly what your API does requires more than simply publishing documentation outlining key methods and parameters. However, members of a team charged with building an API will often become so familiar with their own work that they lose that "fresh eyes" perspective. As such, the methods and parameters available with an API often end up obfuscated by complex documentation and a lack of directed solutions. To make things more challenging, there are really two audiences for an API developers and business development managers. The developers are equipped with REST clients able to test API calls, whereas the business development people want to quickly understand whether the API can be useful to their organization.
As a first initiative to solve this problem, a smart API publisher will often offer an embedded API explorer or console designed to help developers quickly understand what kinds of data or functionality its API provides. Consoles such as Swagger and I/O Docs are very useful for developers who want to explore and understand all that an API has to offer. A new tool from Apiary.io goes one step further and provides actual code samples for multiple programming languages, based on the sample API calls made. An API portal can also seamlessly integrate with Github, for storing and sharing code samples, as well as for tracking bugs or feature requests.
Another increasingly popular approach to optimizing API discoverability is through publishing hypermedia APIs. Effectively, a hypermedia API is self-discovering: The API responds back to the requestor with all available methods and parameters. A hypermedia API can also have an explorer on top to show how it works and make the API more informative for the developer.
APIs for Business Development = Biz Dev 2.0
APIs are increasingly becoming the first point of entry for business development partnerships that require the integration of data or platforms. An integration that would previously have begun with someone picking up the phone to propose a partnership can now be initiated simply by obtaining API access and building a prototype or sample integration. For example, any creator of a Web or mobile app that offers "Sign in with Facebook" is effectively in a business partnership with Facebook. However, only a few of these business partners have ever had actual discussions with Facebook. This shows how quickly business relationships can be implemented when it is easy for developers to access and understand an API.
Traditionally, a business development partnership involved some sort of data integration or data sharing process. Increasingly, APIs are eliminating the need to contact, engage with, and discuss a business partnership. Providing self-service access to an API automates and optimizes the formerly slow and expensive business development process. By combining standard Web UX best practices with Dev UX considerations, such as a console and sandbox APIs for testing, an API will achieve its goals for adoption and integration.
Dependability And Durability
It is essential to build trust around an API ensuring partners commit themselves for the long term. Although conveying this trust is a subtle art, there are several best practices that can make things simpler.
First, although an API is often managed as a separate product from the publisher's core line of business, it is important to maintain the branding, look, feel, and overall style of the organization's main website. Too often, an organization's API portal is given its own unique design. While this can help to differentiate the API as a brand in itself, it can also lead to potential partners perceiving the API as a beta project with an uncertain future.
Second, it is important to provide a clear pricing model for API usage, as well as legal terms of service. If partners are going to invest in an API, they need to be confident of the integration's long-term business viability for cost and legal compliance. Furthermore, they will need to be assured that the API is scalable enough to ensure they will not be cut off or shut down when they become successful. Twitter provides a highly visible example of the backlash that can be unleashed when developers feel misled about an API's viability. The Twitter API will endure the criticism and continue to grow, but Twitter's missteps will cause partners to think twice before relying on its API.
Third, you should help partners to feel like they're part of your API team by providing access to a live status view. This could be a Twitter account or, ideally, a separate Web page showing the health and status of your API. There are numerous uptime-monitoring tools that can be used for this. Being transparent about API status will help you give developers confidence that, if there is a break in service, they will at least get some insight into the situation.
Focusing on the developer user experience will drive success for your API platform. UX experts will advise that improving the developer experience is an iterative process, addressing evolving needs and reacting to that continuous feedback. To get feedback even more quickly, attend hackathons and run developer challenges, as these will help you to iterate quickly and learn what it takes to provide the best Dev UX.
Alex Gaber, is an API Evangelist for Layer 7 Technologies, a company that manages more than 200 APIs, spanning business and government. He is an active member of the hackathon community.