When it comes to making products, successful designers realize that the end user must be the ultimate focus. The user really ought to be considered in every decision that is made. It’s so important, in fact, that the study of User Experience (UX) is a dedicated discipline.

Of course the importance of the user doesn’t apply only to product design — this principle is universally applicable. This includes more abstract applications, like API design. By considering the developer user throughout the design process, the end result is something which is quite frictionless — easy to pick up, and easy to stick with.

So what does it mean to bring usability to the API design table? Depending on timeline, budget, and the current state of the API, different techniques and best practices will be applicable. Start with a few that seem most useful, adding more as the team is able. Ten techniques and methods follow, which can be used to convert developer portal visitors to API consumers, and retain them as active users.

1. Provide a Strong Introduction

The API consumer experience starts before any code is written, during research and planning. This means the experience really starts with the site and documentation. An informative, usable experience can help an API stand out and keep developer users coming back for more.

So, what makes for a good initial experience? A few components are key. An introduction is crucial — this usually comes in the form of an overview section of the docs, or a dedicated getting started guide. This overview should cover important details like what the API actually does, how it functions at a high level, the basics of any mandatory authentication, and supported languages/available SDKs. A demo project the consumer can quickly start with is a nice touch. When it comes to a strong introduction, Braintree has one of the best.

Explaining how the API works and providing example data is part of most documentation, but providing an interactive console or API browser takes things to the next level. An API sandbox provides an opportunity to see how it all works, and to vet the data. Ideally, sandboxes provide both sample and real (personal/authenticated) data.

Microsoft has a great console where sample data is provided, but a personal Microsoft account can be used as well. The various API requests can easily be made and modified, and the returned data is printed on screen in its entirety. Users can get started immediately, which is crucial. Trello also offers an interactive API browser, but requires an account and authenticated token to use it. Additional steps add friction to the API experience.

Microsoft’s API sandbox works with real user data.

Last, a good site will explain the intended usage and API best practices. Make it clear what the API is good for — and what it’s not good for! This is the place to explain why things work the way they do, and to convey to the consumer how to most smoothly integrate their existing codebase with the API. Any tips for improving the end user experience should be provided.

Mailchimp does a nice job with this, providing guidance about authentication, error handling/fault tolerance, and implementation methods to make things faster for the user.

2. Find Our Who Your Developer User Is

When developing an API, keep the developer consumer in mind. Always. The API is developed for their use, so the question that must be asked is “Who is the user, and what do they most need?”

Usable APIs add real value for the API consumer. Take time to research the who they are, and fully understand their unique needs and goals. While the API consumer may be the team developing the API if it’s intended for internal use, this is likely not the case for public APIs.

Once the developer user is identified, features can be created to meet their core needs. This is where Pareto comes into play with his principle — the 80/20 rule. Basically, this rule states that 20% of the work yields 80% of the results. How does this apply to API development? Talk to the target developer consumer, find out exactly what problems they are trying to solve, and start by building small, specific solutions.

By building what the API consumer needs instead of the team guessing what is best, a little bit of code can make a massive impact in terms of API value and usability.

3. Practice Design Consistency

Consistency within the API is crucial for reducing friction. It makes APIs faster to pick up, and to continue using. What does consistency mean for API design? There are a few different ways that the most usable APIs approach it.

The first is consistency within the whole world of development. This means following common practices as they are relevant, such as using standard server codes in a REST API. Going one level deeper, the API should be consistent with the given industry. This means using consistent terminology, and studying existing APIs to ensure compatibility in approach.

Consistency is also implemented at lower levels. As microservices continue to rise in popularity, companies are increasing likely to offer multiple APIs. These APIs must all be consistent as it pertains to things like authentication, naming structure, and data formats.

Once a consumer has a grasp on one API, it should be a breeze to pick up more. This same consistency applies to the individual API as well. The more consistent a single API is, especially as it grows, the less documentation reading and time spent learning is required of the API consumer. Easier to understand APIs are most likely to win out at the end of the day.

4. Provide Usable Documentation

While the best APIs are intuitive and require minimal instruction, documentation is still crucial. Really, documentation can make or break the whole experience. This starts with the UX of the documentation site itself. It doesn’t have to be fancy by any means, but it should at least be useable and readable. Not a natural designer? Get one involved, or use one of the many automated documentation generators.

Design of the site can have an impact on readability, but it’s not the only component — documentation needs to be readable in the first place. As much as possible, stick to plain English and avoid unnecessary jargon. The user base will not all speak the same language. Write simply to ensure a lack of ability to read and comprehend the documentation is not a barrier to entry.

A crucial component of a strong documentation site is a search feature. While new API consumers might actually read through documentation chronologically, active consumers are likely to come looking for a specific piece of information. Good search results give them direct access to whatever it is they need, whereas manual browsing is time-consuming and may deter API consumers.

Last (and this goes back to a good first impression), make sure that the documentation includes interactive code samples whenever possible, preferably in multiple languages. Allow API queries to be tweaked, for example, and show what an actual API response might look like.

5. Use Smart & Intuitive Naming Conventions

The naming conventions utilized in an API can have a broad impact as it pertains to API consumption, and on-going use. Standardized naming conventions are a boon for consistency, a crucial part of a good API experience.

When it comes to naming, keep a few things in mind. First, KISS, or ‘Keep It Simple Stupid’. Use the simplest names for the most common concepts, and save the long names for the one-off functions. Also, make sure names are intuitive and related to the functionality.

As much as possible, the role of the API call should be clear from the name alone. Finally, names should be predictable based on the industry. If every related tool or API calls something an apple, don’t call it an orange.

6. Allow the API Consumer to Control Returned Data

With the rise of tools like GraphQL, this concept is becoming increasingly common. Essentially, the point is to give the API consumer the ability to access all desired data with as few API calls as possible. The consumer ultimately knows what they want from the API. Making it easy to acquire the necessary data is a sure-fire way to improve API adoption rates, as well as the number of ongoing users.

7. Ensure Errors are Meaningful

Too often, APIs return very basic error messages, without a useful structure or any usable information. Especially when a developer is first implementing an API, errors can occur quite frequently. If they’re unhelpful or unclear it’s discouraging to the user, and this can lead to high drop-off rates.

For more on errors read: Best Practices For API Error Handling

To make good error messages, start by providing a plain-text description of the problem. While computers execute APIs and the applications, there’s still a person at the other end of things writing the code. There should be some sort of helpful explanation of why the error is happening, and preferably a link to the relevant documentation or support article.

Speaking of, the best documentation sites provide a section dedicated to errors. Ideally, this includes a list of all the errors, as well as information about why they happened and how best to resolve them.

Crucially, errors should also be recoverable. This means a few things, like consistently named and structured error messages. The errors also need programmatic options for access, in addition to the human-centric text. This is most commonly done via error codes, but the approach should be determined based on the needs of the specific API (and of course included in the error documentation).

8. Support Various Libraries & Data Formats

For implementation, API consumers want what they want — and that’s usually a lot of different things. As much as possible, API developers should provide official libraries in various languages and frameworks.

Not having an officially supported library in the language of their choice can be a massive hurdle for consumers and will stop many from using the API. Community-developed libraries are great, especially early in the game, but nothing beats the official one in terms of building trust.

Variety is also important for the API data which is returned to the developer user. If possible, allow them to select the format (e.g. XML, JSON, or plain-text) which best suits their needs. This can vary wildly amongst different use cases, and is challenging to anticipate. More variety here makes the API useable out of the box for many more consumers.

9. Always Accept Feedback

The API consumer knows what they need, so why not allow them to share their opinions easily? Their feedback can highlight common errors, misunderstood concepts, and frequent implementation issues. It’s also quite helpful when determining a roadmap for additional API development. When it comes to soliciting feedback on new features or massive API changes, it’s best to wait a couple of weeks. Humans can be rather resistant to change (e.g. the uproar at every new version of iOS), but after a few weeks they adjust and the feedback becomes much more useful.

Feedback can be gathered in many ways — it’s important to just start collecting feedback versus procrastinating the implementation of a complicated feedback widget. Email, social media, a contact form, or a dedicated service with tools like polls, are all valid. Whatever the medium, feature it prominently on the documentation site and try to stay open to all opinions.

10. Do Real User Testing

While this might seem like a pipe dream, especially for smaller startups, nothing points out API issues faster than live, in-person user testing. Big companies might go the hackathon route, and this is a great option if resources allow. In reality though, the 80/20 rule very much applies to usability testing. Simply bringing in 3–5 developer users with bribes like a free lunch, or a free year of the service, can uncover 80% of the issues in an afternoon. The remaining 20% is probably pretty one-off issues which are quite specific to individual use cases — not the user base as a whole.

When testing, come up with a couple of challenges to solve with the API, in increasing order of difficulty. If testers encounter insurmountable issues, have an API developer work with them to understand the issue, and talk through the process for solving it. Preferably, these conversations should be recorded for the whole team to review. After the specified amount of time, review the implementation. Solicit feedback about challenges, strong points, the documentation, and so on. It’s also helpful to get the developer user to talk about their personal experience and impressions as a whole, as well as discussing how the tested API compares to others they might use.

In Conclusion

To develop a truly frictionless API — one which is easy to find, adopt, and continue to utilize — the API consumer is the key component. Solicit their feedback, and try to see from their perspective while developing the API. The developer user knows what they need, so give it to them and the chances of success for the API will greatly improve.