What makes a great API?
Global Kinetic Discovery Team
API design has more to do with user interface design than programming.
— Arnaud Lauret, The Design of Web APIs
From the wheel to the modernist skyscraper to the iPhone, the best designs are easy to grasp, simple to use, and never limited to a single use case… possibly excluding the toaster.
A couple of weeks ago, we wrote about the need to productize application programming interfaces (APIs). Today, we look at three related characteristics of a great API product: accessibility, simplicity, and standardization.
Reliability and security are both non-negotiable too, but since our focus in this blog series is on API productization, you’ll forgive us if we concentrate on user experience instead of performance. SmartBear’s annual survey of the API community has found that API developers consistently rate performance as the top measure of an API’s success, while API consumers overwhelmingly choose ease of use, followed by accurate documentation.
Accessibility is an important characteristic of great APIs
How do we shorten the technical gap analysis phase for the prospective user and as such fast-track the buying decision?
— Global Kinetic Discovery Team
Time is a critical factor in driving adoption and use of any API. Specifically, the time it takes for the prospective user to get their heads around the product: to experiment, understand, and find some early success. Some have put forward Time to First Call as an important key performance indicator.
Malcolm Gladwell said it takes 10,000 hours of practice for just about anyone to master anything, but he wasn’t thinking about your API. Great APIs are intuitive and easy to use. Prospective customers don’t have to complete hours of training or read pages of technical documentation to get started. If they do, if it takes too long to get there (three minutes by some estimates!), they’ll probably move on.
Only the very largest organizations can afford to think that just by building it, users will come – or that, once they’re there, they’ll stay. There are 24,689 APIs listed on ProgrammableWeb’s API Directory. That’s a lot of competition.
Start with documentation
How do you help prospective users get to know your API? Concise, well organized, and up to date documentation remains essential. This is one of the first places developers look to understand what a particular API does, whether or not it will meet their needs, and what the necessary inputs are. And users won’t appreciate formats that are difficult to search, bookmark, share, or copy and paste (sorry, that’s you, Mr PDF).
They’ll want to see typical usage scenarios, a list of available methods and accepted parameters, as well as code examples for all product features. As we mentioned above, accurate and detailed documentation follows only ease of use as the most important characteristic of an API in users’ minds.
For its 2021 State of Software Quality: API, SmartBear asked what their top five most important things were in API documentation itself. Examples were chosen by 65 percent of respondents, followed by status and errors (55 percent), authentications (54 percent), HTTP requests (47 percent), and parameters (46 percent).
Documentation should be approached as an integral part of the offering and product development lifecycle. There are many tools to generate accurate documentation in line with development. Global Kinetic’s API designers use Swagger together with our in-house documentation standards and style guide to produce consistently readable, navigable material.
Where possible, show rather than tell
How do we enable self-service integration and minimize the cost / time to revenue when onboarding new customers?
— Global Kinetic Discovery Team
You know what though? Most developers will want to jump right in, and you want to make that as easy as possible for them to do. Just as good documentation rests on excellent structure, so do APIs benefit from well-considered design that adheres to predetermined design specifications and guidelines and conforms to widely adopted industry standards.
Design-oriented developers aim to take maximum advantage of affordance – a term that shifts in meaning between disciplines, authors, and decades but is used in the design world for our perception of something’s possible use based on its perceived and actual properties. These are the clues designers put down to aid the discoverability of an object or element of an interface. In other words, to reduce the time it takes to get to know the product.
“When affordances are taken advantage of, the user knows what to do just by looking: no picture, label, or instruction needed,” says Donald A. Norman in The Psychology of Everyday Things. Trails of clues like these ensure that APIs are easy to navigate simply by virtue of their design. But to craft an experience like that – to develop an API that is as independently consumable as possible – takes care and a deep understanding of the prospective customer’s context: their capabilities, experience, and goals.
If you’ve spent time gaining that knowledge before coding, your API will likely provide a superior user experience – and offer better performance, scalability, and security too. That’s why Global Kinetic takes a strictly design-first approach to API development.
Which brings us to the API sandbox
How do we ensure approachability through the design and implementation of developer portals with Day One access to a use-case–driven, full lifecycle developer sandbox?
— Global Kinetic Discovery Team
API sandboxes emulate the behavior of production APIs. More than just demos, these testing environments are like a free trial and an essential part of any API product strategy. As any of the big names in e-commerce will tell you, a try-before-you-buy sales and marketing strategy helps build trust and ultimately drives sales. Allowing prospective customers to test your APIs before making a purchase, without risk or financial outlay, has the same effect.
Sandboxes’ benefits extend beyond onboarding too. Developers can continue to test integrations without the additional cost of “live” API requests and support calls, or the frustration of potential blocking/throttling of their API requests. At a deeper level, the independence that a sandbox affords them to experiment helps speed innovation and project progress.
The pursuit of simplicity is an element of all great APIs
It is important to emphasize the value of simplicity and elegance, for complexity has a way of compounding difficulties and as we have seen, creating mistakes. My definition of elegance is the achievement of a given functionality with a minimum of mechanism and a maximum of clarity.
— Fernando J. Corbató, “On Building Systems That Will Fail”, 1990 Turing Award presentation
Your customer has a problem to solve and it shouldn’t be your API. They probably don’t have time to diligently explore its delicate and manifold mysteries, and there is no real reason that they should. It can be tempting to add more of everything in pursuit of greater utility, but users are frequently more appreciative of a pared down experience. That doesn’t mean you’ve stripped out useful functionality, but that you have consciously worked from the definition stage onwards to prune away the unnecessary and mask complexity.
Ronnie Mistra, a co-founder of the API Academy and senior director of technology at Publicis Sapient, says that the API designer’s job is to manage complexity – and specifically to improve learnability, boost usability, and reduce confusion. It isn’t easy, and it again requires a laser sharp focus on the user’s problem. Donald A. Norman again:
“Complexity can be tamed, but it requires considerable effort to do it well. Decreasing the number of buttons and displays is not the solution. The solution is to understand the total system, to design it in a way that allows all the pieces fit nicely together, so that initial learning as well as usage are both optimal. Years ago, Larry Tesler, then a vice president of Apple, argued that the total complexity of a system is a constant: as you make the person’s interaction simpler, the hidden complexity behind the scenes increases. Make one part of the system simpler, said Tesler, and the rest of the system gets more complex. This principle is known today as ‘Tesler’s law of the conservation of complexity’. Tesler described it as a tradeoff: making things easier for the user means making it more difficult for the designer or engineer.”
― Donald A. Norman, Living with Complexity
Interrogate the need for anything. Cut the required number of user actions to the minimum. (“Try very hard to delete the part or process,” as Elon Musk has said.) Strive for modularity and composability. Automate what you can. Ensure that only essential data are exchanged. Patterns help make sense of complexity, and hence…
Great APIs are internally consistent and follow industry standards
A sure-fire way to turn user developers off is to diverge from industry best practices. Respondents to SmartBear’s latest survey gave standardization as the most important technology challenge in the API space (52 percent to security’s 40 percent and scalability’s 36 percent) – and previous years’ results suggest the sense of urgency in this regard is growing.
System- and ecosystem-wide standardization and internal consistency make a huge difference in efficiency, security, and interoperability. They vastly improve the onboarding process and save time in development. We are all, by now, pretty good at finding our way around new user interfaces. They follow predictable patterns and use concepts and design elements with which we have become familiar. Ensuring that your API has a similarly predictable structure smooths the user journey. Consistency also goes a long way to ensuring backward compatibility when you update your API.
Too few API portfolios demonstrate a fully consistent approach to naming, error messages, and code patterns. Many do not follow widely recognized global standards. Quality can be poor. There are reasons for this, many of them understandable. We discussed some a couple of weeks ago. In Europe, part of the problem is also that financial institutions – some of the leading users of APIs – saw little value in developing quality APIs in the lead-up to PSD2. The regulation did not seem to most institutions to be in their commercial interests. (There was also no EU standard for how they should look, something that PSD3 is set to address.)
That has changed, of course. Banks and other organizations of all shapes and sizes have come to recognize the benefits of data sharing and have launched API portals to manage API product development, security, as well as marketing. Many of them have worked with specialists to fast-track API productization, so that they can meet market needs faster and more reliably than they might have alone.
Looking to build out your API strategy? Contact Global Kinetic – we can do this for you.