Many of today’s most successful and technologically-adept companies view and manage their application programming interfaces, or APIs, as products — not merely as middleware that forges a connection but as software products that let developers leverage data and functionality for new purposes, digital experiences, and business opportunities.
These APIs should be easy to consume and helpful to developers building the digital experiences that partners, customers, and employees are asking for. APIs have been around for decades as a systems integration technology and are not intrinsically useful outside their initial projects. A poorly-documented API that receives no maintenance might only be used once — but enterprises can enjoy ongoing value from APIs that have been designed with reuse and developer experiences, rather than the needs of a single bespoke project, in mind.
Enterprises can make meaningful steps toward such ongoing value by adhering to four key design tenets that call for APIs to be understandable, useful, credible, and available.
Design APIs to be understandable
API designers should consider the expectations of both application developers and the end users who consume those developers’ creations. APIs should be designed in a clear manner to help developers focus on building applications and experiences that will satisfy end users, not on integration minutiae.
Ultimately, the success of an API program and the business goals it is meant to support are largely determined by, if, and how developers consume the enterprise’s APIs.
A RESTful API definition contains key elements like request/reply schemas, query parameters, status codes, URI templates, HTTP verbs, plural nouns for names, versions, and security schemes. However, if these API definitions are confusing or inconsistently used across a given enterprise’s suite of APIs, developers may struggle and many will seek out alternative APIs that are easier to understand.
By approaching API design from a consumer’s perspective, enterprises can hide complexity and reduce confusion. Every developer is looking for APIs that are simple to use.
Tips for Designing Understandable APIs
- Spend a good amount of time with developers who can share their input on API design.
- Consider resource names that are easily matched to the experiences being designed.
- APIs may become useless if developers don’t have documentation to implement them.
- Functions, calls, and names should be easy to remember, not based on proprietary terminologies.
- Data should be organized in a manner that encourages extensibility.
Design APIs to be useful
When APIs don’t function properly, they hold the enterprise back from achieving its vision. However, even when an API works, it doesn’t mean that it’s useful. Imagine a mapping API that returns directions based on landmarks and not street names or an airline booking API that returns information for flights only within the current week.
A functional or easy-to-understand API should not be assumed to be a useful API. In addition to being simple to understand, a useful API should offer a clear value proposition that solves developer needs, and it should be supported by documentation, sample code, and other resources that communicate how developers can leverage the API’s value for their own projects.
Useful APIs should also help businesses to unlock new revenue opportunities and understand the services that customers want. Enterprises that invest in API management capabilities can leverage end-to-end visibility into API traffic and analytics to understand how developers are using APIs, the popularity of various applications built from the APIs, how API usage impacts business growth, if adoption of given APIs portends changes in developer or customer behavior, and how APIs should be iteratively improved to better suit developer needs and business goals. Like virtually all products, APIs that are built from the outside-in, starting with customer needs rather than internal assumptions or limitations, stand a better chance of succeeding.
Tips for Designing Useful APIs
- Evaluate the current portfolio of APIs and assess the value proposition that these APIs offer, including how they might be modified or reused in new ways.
- Use an API management platform for comprehensive insight into API usage, to understand how developers perceive the value of APIs, and to support rapid iteration of APIs as developer needs and business goals change.
- An API’s value proposition should be clear enough that an application developer can look at the API and understand within minutes what it does, why the data or functionality it offers is useful, and how it works.
Design APIs to be credible
Credibility and trust are often the result when an API program successfully creates APIs that are understandable, useful, and secure. When customers and developers trust a company, they become more likely to engage with the business. However, an enterprise will likely struggle to engender trust in its APIs if it does not consistently dedicate energy to supporting developers, understanding the needs of customers, and continuously delivering on promises over time. This is one reason successful API programs manage APIs as products with continuous lifecycles rather than as one-off IT projects with no ongoing owners and inconsistent or non-existant maintenance and security auditing.
Tips for Designing Credible APIs
- APIs must be reliable and should not frustrate API consumers with poor developer experiences.
- API teams should be open and honest with developers to help nurture better relationships.
- API programs should approach APIs as full lifecycle products that require continuous monitoring, maintenance, and improvement.
- API traffic should be continuously monitored and analyzed — an insecure API is not a credible API.
Design APIs to be available
Simply put, APIs can’t be used if they aren’t available. Developers want good experiences, which is a matter not only of how an API is designed but also of how easily they can begin working with the API. It is important that APIs be easily accessible and shared within a centralized environment in which enterprise teams and external developers can find, try, test, and implement them into their digital products. By making APIs available, enterprises can encourage developers to build around their proprietary assets, increasing the reach and pace of innovation for the enterprise overall.
Tips for Designing Accessible APIs
- Centralize access to APIs using a self-service developer portal.
- Use OAuth and other simple on-boarding processes to reduce the barrier to entry while keeping APIs protected.
- Manage and reduce the time it takes developers to reach their first API response.
- Offer sandbox and mocking environments to make APIs more accessible.
Remember: APIs Are Products
APIs are products with users, and like any product, APIs should be designed to give those users a good experience. This perspective can be the difference between an API that serves only a one-off purprose and an API that can be easily reused and that provides ongoing value.
When developers find APIs that are understandable, useful, credible, and available, they are more likely to adopt those APIs and create compelling new digital experiences. In turn, these experiences can help an enterprise build developer communities, satisfy customers, and ultimately fuel business growth.
[Want to learn about the benefits of API management? Check out the 2019 Full Lifecycle API Management Magic Quadrant from Gartner, Inc.]
