The Four Principles of Successful APIs

API programs are growing in popularity among many corporations – both for IT and line of business professionals. Ronnie Mitra of the API Academy at CA Technologies, shares four key principles for delivering API success.

Tags: APIs, CA, developer, integration, programming interface, SOA, SOAP, web APIs,

Ronnie Mitra
director of API design
API Academy

"The business impact of an API program’s quality has raised the stakes for designers"

Over the last few years, APIs (application programming interfaces) that are exposed over the Web have exploded in popularity. These Web APIs have driven the success of many Internet companies, allowed large companies to reach new user bases and have become the hallmark of innovation-driven organizations.


SOA Summit
How SOA and APIs Power the Agile Business
August 21

Companies around the world are launching API programs, but those of us who are tasked with building a new API platform face a difficult challenge. Although a programmatic interface is ostensibly just a technology component, the business impact of an API program’s quality has raised the stakes for designers. In addition, the combination of conflicting technical guidance, the lack of a clear path to success and the emerging nature of this market makes it easy for designers to succumb to a state of analysis paralysis.


Amidst all of these challenges, many technology teams are building successful APIs. How do they do it and what do they do right? While each situation is different, you can improve your own odds of success by adhering to four important principles:


1. Understand the Strategy
Why are you designing an API? This is the first question you’ll need to address if you hope to succeed. Why is your company spending time and money on this work instead of on all of the other work that could be done?


When I talk about APIs with business teams, I focus on five primary motivators: revenue, innovation, reach, growth and intelligence. You and your business team should have a clear understanding of how a Web API will help your business from the onset. Ideally, the success of the API program should be measurable against a business outcome that aligns with the company’s strategy.


Some API designers are lucky enough to have a very clear, defined business purpose. However, you may be challenged with a request to build an API to support a vague objective, such as innovation. In this case, it is helpful to sit down with stakeholders and drive the discussion toward more concrete business goals. Try to find out what success would look like and how it would help the organization with its core business strategy.


Gaining clarity on the business driver for your API will enable you to make better decisions about who you are designing for and what type of interface you should provide for them.


2. Decide Who You Are Really Designing For
Good designers always consider the user’s perspective when designing. This approach results in products that we enjoy using because they help us achieve our goals.


Your API design philosophy should be the same. Your objective should be to help your users become successful in their task of writing a client application. This is easier said than done, but a good first step in the process is understanding who your users are.


For example, try to determine which programming language your users will code in, or what platforms they are likely to deploy applications on. Armed with even this small amount of information allows you to design an interface that fits this particular type of user.


Understanding the business goals for the API is a big step toward gaining this kind of insight. The business motivators will naturally lead you to prioritize a specific segment of developers who will use the API.


For example, a business that wants to increase their consumer reach might focus on producing many high quality mobile applications as quickly as possible. As an API designer, you might in turn focus on developers in boutique mobile development firms coding for the Android and iOS platforms.


Gaining insight into who you are designing for gives you an opportunity to perceive the API from their perspective. With this knowledge you can create an interface vocabulary that is familiar to your audience because you are aware of their existing domain knowledge. You can write code examples and client libraries that are relevant to your target developers because you know which platforms they prefer. You can even validate your design decisions by writing client code in the languages that you know they will use.


But, to truly gain the perspective of your targeted user base, you’ll need to get out of your office and observe how they use your API. No matter how you do it, obtaining observational and experiential data is vital because it will allow you to test the assumptions you’ve made about the developers who will use the API.


3. Start Small and Iterate
The worst time to get user feedback on your API is after you’ve already spent six months designing, building and launching it. At this point it becomes costly to make any major changes, so you probably won’t.


A better approach is to scope the first iteration of the API to a small set of interactions. Ideally, you should be able to identify a few core activities that will help your targeted developers create the types of applications that will result in real value to the business for which they are designing the API. The smaller the scope of this initial release, the greater the opportunity to learn and improve the design.


In the Web application space, lean, agile and incremental philosophies are gaining in popularity because they help product teams test hypotheses and focus on high value functions. But, API designers must deal with a powerful change constraint that limits the degree of experimentation that is possible: any changes to their interface may break every single client application that uses it.


This constraint may lead you to initially take your API to market with a smaller, trusted developer audience that will be open to a reasonable amount of change. Indeed, it is becoming popular for organizations to launch their APIs behind closed doors for a period of time to identify any developer-impacting bugs before opening up access to partners or the general public.


4. Architect for the Long Term with Abstraction
While it is good to make design mistakes in private, some degree of change is inevitable. If you want an API that will stand the test of time, you will need to make sure it remains reliable, secure and evolvable.


Employing a level of abstraction on top of your run-time API can be a great help in meeting future requirements in a stable manner. For example, building an abstraction layer that implements security enforcement, representation of the interface (i.e., what the messages actually look like on the wire) and caching will enable you to change or enhance these components without impacting the core API.


In software design this is called a façade pattern. In enterprise architecture, this is a gateway. No matter what you call it, give strong consideration to using abstraction to give yourself the freedom to make future changes.


It’s All About the Experience
The fundamental goal for an API designer is to create a positive developer experience for the users of the product.


But, SOAP-based interface designers rarely consider this user experience perspective. Historically, SOAP API designers tended to focus on the size of a service catalog and the amount of data that has been exposed. Today, API designers should instead focus on supporting the goals of their target user base and building just enough functionality to support those objectives.


Having empathy for the developers of client applications will result in a higher adoption rate for your API and an increased level of efficiency for your organization. Understanding the core business drivers, identifying high-priority users and taking an incremental approach are essential to creating an API that developers want to use.


Ronnie Mitra is Director of API Design at CA Technologies. As an expert in API architecture and design, and a member of the API Academy, he helps companies conceive and launch successful API projects. Connect with Ronnie at