Setting unrealistic expectations is one of the main risk factors in any IT project, and APIs are no exception. But how can we ensure that we remain realistic without selling ourselves short? And conversely, how can we make an impressive offer without setting ourselves up for failure to deliver?
In this article, we explore the most common expectations external developers have towards API products, and shed light on this crucial aspect of project planning.
Expectations vs. reality
A dissonance between our expectations and our experience can cause dissatisfaction: a software update that brings more bugs than a picnic basket left unattended, documentation that is more cryptic than a cipher, and the list goes on. But how do we come to form those expectations and what factors influence our beliefs?
According to Luoma-aho and Olkkonen, expectations in a business context are ‘mental models that affect the formation of relationships’ between individuals, stakeholders, and organizations, and they can be divided into four categories:
- Value-based expectations ‘indicate an ideal state based on what is valued or wished for’.
- Information-based expectations are based on ‘what is known and what information is available or unavailable’.
- Experience-based expectations are rooted in ‘direct or indirect previous experiences’.
- Personal interest-based expectations are influenced by ‘personal evaluations of gains and assessments based on what is deserved’.
These expectations govern the way we interact with products and services. When we apply these categories to API products, we can gain valuable insights into what developers are looking for, and we can anticipate their needs.
Expectations for API products
As every developer is unique, with varying needs and preferences, it can be challenging to predict what they’re looking for in an API. For instance, seasoned developers might find step-by-step tutorials unnecessary, while hobby developers wouldn’t go near an API without these detailed instructions. Catering to different learning styles, experience levels, budgets, and personal preferences is a delicate balancing act, but keeping these four categories of expectations in mind provides a more comprehensive and well-rounded perspective.
Value-based expectations
Value-based expectations are normative in nature, meaning that they reflect beliefs about how things should be. By representing an ideal state, these expectations also reflect the highest possible standards for any service or product - including APIs. Due to evolving industry benchmarks, users have come to expect high-speed performance, constant reliability, and seamless integration tools as base-level requirements.
In this highly competitive market, providers are constantly raising the bar, and as they do so, expectations also rise to ever higher levels - this phenomenon is called expectation transfer. It is no surprise that nearly 100% uptime has become the industry standard, and many of the major industry leaders maintain the coveted five nines (99.999%), while others follow closely behind. Being transparent about the uptime status of an API builds trust in the product and demonstrates a commitment to long-term reliability. Apart from the uptime outlined in the SLA (service level agreement), speed also matters: a median worldwide latency of 300ms is expected, and some sources even indicate a 90ms limit on API response time.
Information-based expectations
Information-based expectations are of special importance for service providers, as they can directly impact the quality and the quantity of available information. It is also important to note that a lack of information can lead to unrealistic or vague expectations, which, in turn, results in frustration and dissatisfaction. Accurate and up-to-date documentation helps developers navigate the API economy, and it also sets them up for a seamless journey with no unexpected surprises to spoil the experience.
Clear and detailed documentation is a must-have for any API product as it can make or break the integration process. Some of the most sought after content types are:
- Step-by-step tutorials
- Integration guidelines
- Code samples
- Use cases
- FAQs
- Change logs
- Error dictionaries
- History of uptime
However, if the documentation lacks clarity or isn’t regularly updated, it sends a signal that the API provider may not be prioritising the product. This lack of attention can discourage developers from adopting and using the API.
Experience-based expectations
Experience-based expectations can stem from previous encounters with a product or service, but they can also result from reputation and word-of-mouth. When developers are researching APIs, they often turn to forums to see which APIs are in high demand and to gain insight from their peers. Although the stories circulating on developer forums have a life of their own, an outstanding first-hand experience truly solidifies the reputation of an API.
In the initial phase of researching an API, one of the most important trust signals is the community support of an API. Finding proof that other developers actually use it establishes credibility, and makes developers much more likely to adopt it. Developers often dive into forums and online communities to gauge general opinions and see if there are repeated mentions of a certain API. If a well-known member of the community speaks out about an API, it also provides an added boost of credibility.
Providing a delightful developer experience is a crucial priority, but in spite of our best efforts, hiccups can still happen. However, they don’t have to overpower the positives: in fact, they present an opportunity for providers to demonstrate aspects of their service that wouldn’t come to light in ideal conditions. For instance, offering compensation for users’ loss is a generous gesture, and frequent updates about any ongoing efforts to fix the problem could set developers’ minds at ease.
Personal-interest based expectations
This category is perhaps the most difficult to pin down as it refers to beliefs about what is deserved or desired, and it is heavily influenced by personal opinions. In the context of APIs, this could mean certain features that developers hope to see based on their personal preferences, and it can also refer to a quality of service that is expected to match their integration efforts.
Providing reliable support is a great way to empower developers throughout the integration process and to address any issues that arise later on. Documentation is often the first resource developers turn to when they encounter a problem, but some errors require a more personalised solution. Unexpected downtimes and errors may happen down the line, but timely and effective communication can mitigate their negative impact. While documentation is the first step of the journey, ongoing support strengthens developers’ trust and confidence in the API.
Another way to address personal-interest based expectations is to enhance ease of use with features like SDKs and sandbox tryouts. SDKs provide essential resources to make the API adoption process smoother and more efficient, therefore developers might be more likely to choose an API that has an SDK. Sandbox tryouts are another helpful tool for developers to decide if an API is suitable for their purposes - by allowing developers to test the API in a realistic setting, they can make an informed decision and explore the product before purchasing. Most developers are also looking for a seamless tryout experience with a registration process that takes little time and information.
Conclusion
Figuring out the expectations for our APIs can be challenging: there are as many preferences as there are developers, and requirements can also shift based on their project needs or company guidelines. Although there is no one-size-fits-all solution that works for everyone, there are some core elements developers are looking for when they’re researching the perfect API for their next project. By being mindful of the different types of expectations that apply to APIs, we can set ourselves and our developers up for success.
Managing expectations is a difficult tightrope to walk between setting our sights too low and completely overshooting our target. However, by charting and anticipating expectations, we can strike a balance that creates a win-win situation for everyone involved.
We wrote this article with information from in-house desk research, and we based conclusions on the results of recent user research. The Pronovix UX Research team is specialised in finding out how users in a specific situation think and behave, and what they expect. If you feel that you could benefit from user insights, contact us to find out how we could help!
All Pronovix publications are the fruit of a team effort, enabled by the research and collective knowledge of the entire Pronovix team. Our ideas and experiences are greatly shaped by our clients and the communities we participate in.
References
- Choosing the Right API Solution
- How To Decide on an API That Gives Your Team the Best Developer Experience
- Luoma-aho, Vilma & Olkkonen, Laura. (2016). Expectation management. In C. E. Carroll (Ed.) The SAGE Encyclopedia of Corporate Reputation (pp. I:303-306). Thousand Oaks, CA: SAGE.
- Olkkonen, Laura. Stakeholder Expectations: Conceptual Foundations and Empirical Analysis. Jyväskylä: University of Jyväskylä, 2015, 9 p. (Jyväskylä Studies in Humanities).
- Top Expectations for API Products in 2021
- Understanding customer expectations: Types, management tips, and examples
