Subscribe to the API Design blog or our podcast for more tips from industry experts.
{{cta(‘eb5457b4-4c61-40b2-b4b9-8170965f877d’,’justifycenter’)}}
APIs are the great business enablers and value differentiators of our time. They are critical in empowering businesses to supercharge their capabilities and compete effectively in this digital age.
I always say that APIs are responsible for about 83% of the Internet traffic.
However, about 75% to 90% of the digital transformations within companies fail. One of the reasons for this massive failure is poor developer experience, which results in inefficient integrations. A poorly crafted API program makes it difficult for developers to realize goals on behalf of their end-users.
On our recent podcast, we interviewed Steve Sfartz, a Principal API Architect at Cisco, about ways you can create a positive experience for developers consuming your APIs.
Here are Steve’s four main ways of delivering a great developer experience with APIs.
1. Consistency, Consistency, Consistency
“Consistency: I think we need it more today than in the past.” — Steve Sfartz
The importance of consistency in your API ecosystem cannot be emphasized enough. Building consistency throughout your APIs will make your exposed services easier to consume and devoid of complexities.
Inconsistencies across your API design can leave even the most experienced developers confused and frustrated. A perpetual cycle of incorrect assumptions and failed API calls can dampen developers’ enthusiasm and cause them to look elsewhere for smooth integrations.
Steve emphasized that consistency is particularly required in a DevOps environment, where multiple related technologies are used in development.
Some areas you can enforce consistency include naming endpoints, choice of casing style used, and error handling. Furthermore, with an automatic API styling tool, such as Spectral, you can effortlessly drive consistency throughout your APIs.
2. Build Standards Early
“At Cisco, we started moving forward. We have a dynamic team that is really very active with gRPC [an open source framework]. We are working with that team to establish standards early for gRPC APIs. It helps us to learn from that team and become ready to ship APIs with that style.” — Steve Sfartz
REST is loved for its great simplicity. However, other emerging API design styles, such as gRPC and GraphQL, could also become popular in the near future.
So, you should invest in developing standards that allow you to use these new styles smoothly, instead of being caught off guard.
If you wait until the new styles become mainstream, you may not have sufficient time to fine-tune your implementation strategy. Developing standards later may also be costlier.
3. Implement a Scoring System
“The scoring system is what really matters because it allows you to unlock your engineering team.” — Steve Sfartz
A scoring system will help you gauge the performance of your APIs, especially whether they are providing the intended value to developers.
You can use internal tools to measure if you’re delivering a great developer experience. The tools will help you determine what really matters to your developers. For example, you can measure how long it takes for an average developer to get started consuming your API; that is, Time to First Hello World.
When creating a scoring system, you should understand the needs of the community and establish guidelines within your organization that will address those needs. For example, if users like a certain API architectural style, you can set guidelines that ensure they integrate with that style comfortably.
It’s also important to involve your internal API development team in implementing the scoring system. Since they have hands-on experience in how the API works, their feedback and input will help you create a system that works best for your organization.
4. Enforce Good Documentation
“We’re seeing more reasons to have great developer documentation.” —Adam Duvander, fellow podcast host and principal consultant at EveryDeveloper
An API initiative is only as good as its provided documentation. If the documentation is bad, it’ll complicate integration, leading to a poor developer experience.
Your documentation should be simple, yet comprehensive enough to enable developers to integrate the API into their various use cases without experiencing programming hitches.
Incoherent and inconsistent documentation will push developers away from your API, but if it’s well-explained, your team will spend less time answering support questions and onboarding new users.
It’s important to think about the domain you’re addressing when creating your documentation. Using industry-specific naming conventions and common terminology can boost your API’s consumption rate, instead of jargon.
You should also include a way to test your APIs. Developers are the main drivers for business purchase decisions. If they try your API and find it difficult to use, they’ll not recommend its purchase.
I often say, “It’s always the developer who tries, and the business buys. And if both sides aren’t right, it ain’t going to happen.”
Build Rich Developer Experience Into APIs
Optimizing the developer experience throughout the lifecycle of your API is essential for its success. If you do not create a positive experience, many developers will find it difficult to use, resulting in decreased adoption of your services and products.
Developers will go for an API program that they enjoy consuming. Similarly, by building a rich experience, you can empower them to create useful digital experiences and applications that end-users enjoy using.
Developer experience is the key to ensuring your API program sees the light of day. So, give it the seriousness it deserves.
