Why deliberate API design supports a great developer experience

According to a recent Nordic APIs statistics roundup, over 90% of developers are using APIs, and they spend nearly 30% of their time coding APIs. This clearly illustrates how important APIs have become for businesses but also how much impact they have on the workload of IT professionals.

A great API needs to be complemented by a great developer experience – the experience a developer has when using the API. Most organizations have learned to value the deliberate design of end user experiences in mobile apps and websites, but few apply the same concepts of user experience design on their API products. Yet the most impactful API programs are those that build APIs as products with a focus on maximum productivity for developers. This is why deliberate API design, with upfront planning and understanding of how APIs will be consumed, is becoming increasingly important.

What problems does API design solve?

Traditional API development practices start with implementing business requirements in code and then generating the API specification and documentation from that code. It’s called a code-first approach to building APIs.

Code-first API development is quick and well supported by many developer frameworks, but it has its downsides:

1. The main focus is on the functionality of the API, which is important, but how the API will be consumed tends to be an afterthought. Too often the belief is that using a standard – for example OpenAPI or GraphQL – solves this for you, but the truth it it does not.
2. API specifications are the foundation for very rich documentation and a great developer experience. What is in the API specification is surfaced directly in developer portals. Unfortunately generated specifications are often limited to the bare necessities.
3. Consumers of the API should wait for the implementation to finish to get the completed API specification, which impacts time to market. Without deliberate upfront planning and design, you run a significant risk of expectation mismatches which leads to costly rework.

Deliberate API design helps you to tackle these challenges. With a design-first approach, you iteratively describe the API in a way that both humans and computers can understand – before you write any code. Every stakeholder participates in the API design to create the API specification that satisfies the business requirement in a way that works for everyone.

What do API design tools bring to the table?

API design tools come in different shapes and forms. webMethods API Management is a full life cycle API management solution and includes API design features. In recent years, we’ve seen new specialized API tools enter the market that focus on specific stages in the API life cycle and complement API management solutions. Some of these tools focus specifically on API design. Options range from simple text editors over IDE extensions to robust collaboration platforms like Stoplight and SwaggerHub, which offer an enterprise-grade API design solution built around the OpenAPI standard.

Whatever API design solution you choose to use, it should help you tackle the following challenges and remedy all the downsides you would experience with a code-first approach:

1. Design and prototype APIs and their documentation faster, preferably with a visual no-code editor.
2. Avoid duplication and ensure consistency of schemas, requests and responses across all of your APIs.
3. Ensure high-quality design by enforcing style and content rules.
4. Validate the developer experience – before implementation – with mock servers and live previews.

Depending on the size of your team and organization, you’ll likely have additional requirements such as single sign-on, version control, CICD integration and more. You will want to take these into account as well when you evaluate API design tools.

What’s next?

We have designed webMethods API Management to be an open platform that enables collaboration throughout the API life cycle. It is regarded by analysts as a leader in full life cycle API management. If you’d like to explore how you can use API design tools with webMethods API Management, you can read up on two examples on our Tech Community: