4 Tips for Creating a Beautifully Designed API with Great UX

Monolithic software that was downloaded onto disconnected systems was once how almost all applications worked. This resulted in a lack of connectivity, communication, and often a duplication of efforts. Today, however, standalone systems are a thing of the past and have given way to connected, distributed systems that share data both up and downstream. But how has this become possible? As outlined in a TechTarget%20in%20a%20controlled%20way.) article, it is primarily through the growth of the API Economy and the integration of “complex software components down into smaller, containerized components called microservices.” The article continues to explain, “the use of microservices make data and services more accessible and flexible. By building a model around APIs, businesses can rapidly scale up. This can be done by accessing third-party services and data or using APIs to transform their own data and services into a platform that encourages others to build upon and use it.”

However, what must be realized is that while APIs can be transformative to how your team designs products and does business, the APIs themselves need to be designed to ensure that they enhance your product and offer beautiful user experiences.

Before we dive into how to design APIs, let’s review what APIs are and how they work.

API stands for an application programming interface. It allows two applications to communicate with one another to access data. Every action you take on your phone or tablet, such as sending cash to a friend, shopping online, checking the weather, or sneaking a peek at the baseball game score, uses an API to access and deliver that information. In simpler terms, let’s use a restaurant as an analogy. When you go to your favorite lunch spot, you sit down, and a server comes to take your order. They then take your order to the kitchen, where the chef reads it, makes your food, lets the server know it’s complete, and then the server brings it to your table. Think of the server as the API making the two-way connection with you and the kitchen, ensuring that the chef sends out what you requested and that you don’t have access to other food in the kitchen that you did not order. In the APIs’ case, it is serving up data instead of your favorite soup and sandwich.

Why APIs

While it might sound like API’s just make the sharing of data more manageable, they do so much more than that. Joining the API economy enables startups to deliver their software faster in three primary ways:

1. APIs provide product customization with proven code. APIs offer all of the feature functionality your team needs quickly, with stable, reliable documented code, and the best part is you don’t have to build it yourself.

2. There is no need to reinvent the wheel. In the age of microservices, you can use the best-of-the-best, proven applications to help you distribute the work and provide the features your customers want, regardless of the technology being used.

3. APIs offer framework flexibility. APIs enable your startup to utilize the tech stack you choose and build in any language or framework. APIs help accelerate the development cycle, a critical factor in a competitive startup landscape.

While API’s are just one part of your product development process, they should not be minimized or considered an afterthought. Think of your API as an agreement between your software, your users, and how they expect to use it with all of their other technology. Ensuring that your API is well designed will provide seamless integration and elevate the UX of your product.

In 2012 John Musser, CEO/Founder of ProgrammableWeb, shared his insights into Five Keys to a Great API. He shared that a great API should be:

• Valuable - He discussed that value can refer to data, service, audience, function, marketplace, or access

• Planned - Here, he discussed the many design options and focusing on the purpose and the user

• Flexible - APIs need to be simple and quickly adopted but also offer choices for more complexity and developer control

• Managed - Some key API factors that need to be managed are security, versioning, monitoring, reporting, and scaling while also measuring performance, developers and apps, quality, and more

• Supported - Ultimately ensuring that developers have a great experience, that a community is built around it, and feedback is integrated into future versions

So, what steps can you take to create a beautifully designed API with great UX?

1. Have A Strategy

Red Hat shares that an effective API program must build on an organization’s overarching corporate strategy and contribute to its objectives. You’ll know you have the makings of a great strategy when you can answer the following three questions in a clear way:

• Why do we want to implement APIs? They remind developers that the API’s value to users is the result of an API call (service request and response) rather than the call itself.

• What concrete outcomes do we want to achieve with these APIs? The “what” refers to what the APIs actually do and what impact they have on the broader business strategy?

• And finally, how do we plan to execute the API program to achieve that? This is all about the execution and includes such questions as:

  • What technology is used to build the APIs?
  • How are the APIs designed?
  • How are the APIs maintained?
  • What resources are available?

2. Tell Me An API Story

It is clear how creating user stories can help your development team focus on the features for your software, but how can writing user stories help you develop your APIs? After all, computers aren’t people. What can help make this process streamlined is to first create a user story for the persona utilizing the system. For example, Mike is a marketing manager who wants to use a marketing automation system to connect to his webinar applications to create leads from webinar attendees. Mike also wants to associate these leads with existing accounts so that the salesperson can follow up on the leads, and lastly, Mike wants to be sure he does not create duplicate accounts or contacts in his marketing automation system. We would then create a system persona - the webinar application. The webinar application persona’s goal is to match leads to the marketing automation system without duplicating account information. Understanding what the human and system personas’ goals are will enable you to focus on what the design priorities should be.

3. Utilize Design Thinking

Wait a minute, you might say, design thinking uses human-centered techniques to solve problems, and I know that it helps me develop relevant software, but APIs are software for computers. It is true that APIs allow communication between computers, but remember, people are still programming at the other end. If you have poor API design, you may be setting yourself up for issues with client-server interactions. This is where design thinking comes in. Working through a series of tighter and tighter iterations helps to identify the API features, functionalities, and documentation needed for the final product. The API Design Thinking phases include:

• Discovery — API design should begin with brainstorming sessions to discuss the needs, problems, and desired outcomes.

• Define — Discovery details then are refined to define specific user needs that can be solved with an API. Problem statements are written outlining users’ needs.

• Ideate — During the ideation stage, solutions to the problem statement are proposed, as is how to best design the API.

• Prototype — Experimental APIs are built that can later be expanded upon in future iterations.

• Test — The experimental API is tested to determine if it meets the initial needs, problems, and desired outcomes. Changes, edits, and additional iterations are made based upon feedback.

4. Be Consistent And Document Everything

APIs are fantastic when they can be utilized by other developers, and other developers like consistency. When your API is called, they want a predictable outcome. This can be achieved by following consistent conventions. Also, provide clear and concise documentation. You cannot expect other developers to read through your code to figure out how to use your API. Even worse is providing incomplete, incorrect, or out of date documentation.

There is no arguing that APIs are invaluable in today’s tech market, and they can often mean the difference between your product being adopted over that of a competitor, but it is crucial to understand the issues that can result from a poorly designed API. These include:

• Increased long-term costs
• System/product downtime
• Scalability and security issues

The End Goal - A Meticulous User Experience

We need to remember that while many often associate UX with beautiful-looking UI, Interaction Design Foundation defines User Experience Design (UXD or UED) as the entire process of acquiring and integrating the product, including design, usability, and function. Your API may “just” be allowing one computer to talk to another. Still, its consistency, intuitiveness, speed, ease of use, and documentation are vital factors that will help your team provide the best UX and create relevant, future-proof software.