Designing APIs for the API economy is different — here is how

Excellent technical API design is not enough for your APIs to succeed in the API economy. You will need to bring the same level of excellence to the business design of your API.

Matthias Biehl Matthias Biehl
Dimensions of API Design

Most API providers spend a lot of time on the technical side of API design and implementation. They create a taxonomy for their domain, pick an architectural style, design the resources, create an OpenAPI specification, devise an API style guide and enforce technical governance of their APIs. They lint their API specs and automatically checking them for style guide conformance. They publish their APIs on a developer portal and provide examples and try-out functionality as well as documentation. In short, they do all the right things to advance their technical API design. 

Despite all of their hard work and good intentions, their APIs don’t always deliver the business results they were expecting. This leaves them frustrated, scratching their heads and concluding that “Sometimes it works, sometimes not, and we don’t know why.” 

I have heard this a lot and if it sounds familiar to you as well, then this blog series may be for you. In the coming weeks, I will be sharing tips and best practices on how to pivot from building technically great APIs, to building APIs for the API economy.  

API design is multi-dimensional

Figure 1: A focus on technical API design, without thinking about the business dimension, leads to an incomplete design

The first step is to understand that designing APIs is actually multidimensional: Sitting right next to the well-known and well-understood dimension of technical API design, there is also the dimension of business API design. That second dimension is what I will focus on in this blog series. (There are also other dimensions of API design, such as the organizational/people-related dimension – but that is a topic for another day.)  

Simply put, good API design makes conscious, intentional design decisions along all relevant dimensions. 

Often, people are so focused on what may seem like the “hard part” – the technical dimension you need to consider to build an API. What they overlook is the need for the business dimension that requires dedicated business design. Why? Because many API initiatives start out with internal APIs where the technical dimension of API design is the one that matters most. While these internal APIs would benefit from considering other dimensions, this technical tunnel vision rarely results in major consequences.  

However, it does start to form a bad habit of judging an API’s value based primarily on technical excellence.  

When teams then move on to create public APIs—and thus become proud participants of the API economy—many organizations continue working primarily with the one-dimensional, technical approach to API design. While the focus on technical API design works more or less for internal APIs – it is doomed to fail when used to compete in the API economy.  

So let’s talk about what we mean by the business API design. It means that the API needs to be technically sound and attractive to conducting business in the API economy.

Figure 2: To create successful APIs for the API Economy, you need to consider both technical and business dimensions of API Design

API design along two dimensions

Even recognizing this dimension of API design is a big step forward. But the order in which you tackle design decisions along these dimensions also matters. Sometimes I see API teams busy designing, developing and deploying an API, and only after the last JIRA task for this API is set to done, they look up and ask: “Now, how can we make money with that?” 

Once the “hard part” is done, it’s no longer easy to go back and align it with your business design. Sadly, it’s often too late. Don’t neglect the business dimension until the very end. Don’t let the business aspect of your API be an afterthought. Don’t let your hard work go to waste.

Figure 3: Business Design of APIs should not be an afterthought

That said, it’s easy to overreact. You may be tempted to say the business design should drive the technical design. Instead, I propose doing a co-design between the technical and business aspects of an API. And that is because there will be dependencies, implications and tradeoffs between design decisions along the two dimensions. As a result of the codesign, technological choices do not limit business and business choices do not ask for unnecessarily complex or infeasible technical designs.

 

Figure 4: Codesign of technical and business aspects

Business design aspects for APIs

Taking this approach requires an equal understanding of the technical and business sides of the equation. The design decisions that need to be taken along the business dimension may be uncharted territory for some API designers, and they might wonder what they need to consider to make the right decisions. The best approach is to ask the right questions to make sure you are building the right solution.  

For each API you design for the API economy, you will need to get clarity on questions such as: 

  • Who is the API consumer? 
  • What tasks need to be done by the API consumer and how can the API help you do these tasks? 
  • What capabilities can we expose in form of an API to help the customers accomplish their tasks? 
  • What is the role of the API in the overall business strategy? Which ecosystems or platforms does it help us to participate in? Which digital supply chain can we participate in? 
  • What is the relationship between our digital product and the API? Is the API the digital product? Is the API a feature of the digital product? In what way does the API make the digital product more attractive? 
  • How do we monetize these APIs and create revenue
  • How can we market the APIs? 

In the next posts in this series on the API economy, I will provide further insights into the above questions, and how their answers can help you build APIs that will solve business problems. Stay tuned.