Subscribe to the API Design blog or our podcast for more tips from industry experts.
{{cta(‘eb5457b4-4c61-40b2-b4b9-8170965f877d’,’justifycenter’)}}
A good API is like a LEGO block — or so says Matthias Biehl, author and advisor to API-University. When designing your API, the simpler the better.
Building APIs that end-users will love is key to realizing their full value and attaining your business goals. If APIs are designed well, developers will find it easy to integrate them into different use cases and make the most of them. On the other hand, integrating poorly built APIs is frustrating and will hurt your company’s brand.
In most cases, enterprises rush to design, build, and deploy API programs without substantive plans on how to satisfy the needs of the developers who will be consuming them.
On our recent podcast, I interviewed Matthias Biehl, an instructor at API University, a platform that publishes books, courses, and training on APIs.
Here are Matt’s three most impactful takeaways for creating quality APIs that will help you to not only grow your API program, but how to also create APIs that your end-users will love.
1. Implement Secure and Smooth Identity Verification
“So, OAuth 2.1 is basically a collection of all the best practices that have been collected out there in the field. And they are now in one consistent standard and one consistent document for you to read up. I think that’s a good place to start.” — Matthias Biehl
Implementing robust authentication measures is a good way to control the type of users who can access your API. In the early days of API development, a personal secret key was all we had. Currently, the introduction of the OAuth open authorization protocol has greatly transformed how users are authenticated when accessing APIs.
Specifically, OpenID Connect, which is a simple identity layer created atop the OAuth 2.0 protocol, is prevalently used to power smooth and secure login and signup experiences when using APIs. With a simple click of a button, a user can securely authorize a third-party application to access their account—instead of having to spelunk through a developer portal, as is the case with API keys.
OpenID Connect commonly uses JSON web tokens (JWTs) to provide secure account-level access authentication. Since JWTs are difficult to revoke before their expiration time, reference tokens (also called opaque tokens) are normally used in cases where the access tokens need to be revoked before they expire.
Additionally, the Proof Key Code Exchange (PKCE), which is another OAuth 2.0 extension, is also commonly used nowadays to provide more secure authorization. It’s a key that ensures the authorization code is not intercepted by a malicious application that has crept into the same computer. It enables the code authorization flow to be completed securely.
Matt also emphasizes that there is no need to try to reinvent the wheel in the security space. If a tried-and-tested solution that has taken care of all the loopholes exists, such as the OAuth protocol, it’s better to use it instead of trying to create something from scratch.
2. Build for Ease of Use
“You should design your APIs for the absence of complexity.” — Matthias Biehl
Building APIs that are easy to use paves the way for their success. If your exposed product is problematic to consume, users will give it a wide berth. Using jargon, domain-based concepts, or incoherent descriptions will make your API difficult to understand.
Matt adds that if your APIs are connectable and portable, developers can easily integrate with them—just like anyone can easily connect interlocking Lego blocks together. Also, if you have a consistent API portfolio, whereby all of your APIs behave in the same way, developers will find them predictable and intuitive. It’ll reduce the need to search the documentation looking for ways to implement the APIs.
You should also include an API style guide to help everyone at your organization adhere to basic API design patterns and conventions. It’s a good way to ensure consistency across your suite of APIs, reducing friction in your team, and enhancing the consumption of your APIs. You can start by taking a style guide from an established company and adapting it for your use case.
3. Keep the Customer in Mind
“As soon as you have an expert in a certain domain that you need to design a good API, you should counterbalance it with another stakeholder who represents the customer’s point of view. And it’s all about a little bit of empathy with the future user of your API and counterbalancing. The expertise is very helpful.” — Matthias Biehl
The needs and preferences of your target consumers should be a priority when you are building an API. It’s vital to have a team in your organization with a customer-centric mindset. They’ll help you put yourself in the shoes of customers and understand their requirements.
That’s what will assist you in designing an API program that reflects the ever-changing demands of the marketplace. People who understand how your API works, and also understand the marketplace requirements, can speak the right language to enhance the consumption of your API.
Before releasing full-blown APIs, you can start by finding out what really works for the customers. Matt calls it using the “hunting” or the “fishing” approach.
If you go hunting, you can look for partners that need your APIs and give them the APIs to try out.
If you go fishing, you can release partially built or mock APIs and allow developers to try them out. Eventually, you can use the feedback and adoption analysis results to design a good API product that will meet the needs of your target audience.
Design and Deliver Great APIs
Building outstanding API programs that will make developers happy is not a walk in the park. Delivering performant and resilient APIs requires doing the right thing at all times—from the initial design to final deployment and management.
If you expose a bad API, it can be among your organization’s greatest liabilities—you’ll need to provide constant customer support that can impair your organization’s capacity to move forward.
Matt affirms that it’s also important to align the company’s strategy with the API’s strategy. If the right backing is given and APIs are viewed as significant assets within the organization, it can greatly enhance their growth. With executive support, your organization can prioritize developer experience investments that make APIs easier to consume.
To learn more about building quality APIs, subscribe to our podcast.
