It’s common knowledge that APIs (Application Programming Interfaces) are the key building blocks of modern day applications. However, building applications API-first forces us to address design challenges before they require costly refactoring. This means that if we’re to truly adopt a design-first approach to API development, we must identify the essential components required to make it possible. If we don’t, we'll fail to realize all of its benefits.
In this blog post, we’ll discuss those necessary elements. Whether you’re a product manager or technologist, if you’re involved in designing and building APIs — or products that use APIs — what follows should give you a greater understanding of what the design-first approach to APIs actually requires.
The tl;dr on design thinking
Since the late 1950s, prominent institutions such as IDEO, MIT and Stanford have formalized the practice of design thinking.
In most descriptions, design thinking is a mindset. It encourages us to use divergent and convergent thinking to solve “wicked problems.” Wicked problems, according to IDEO, are “problems with many interdependent factors making them seem impossible to solve.” Design thinking prescribes an iterative approach to problem-solving, aligning well with Agile principles in software development. Applying these principles can help us to solve the problems we need to solve most in a manner that ensures the delivery of value.
The tl;dr on API design
API design is the process of establishing business use-case requirements, non-functional requirements (NFRs), protocols and methods to inform API development and ensure that it can realize value. Establishing the design using a design-first approach takes precedent before writing any code.
API ecosystem : The quest for developer enablement
An effective API ecosystem consists of many different assets and techniques that must be developed and curated. When done properly, they should help to align the transformation efforts related to people, processes and technology.
In summary, good API design helps us to deliver business value through quality API products. The “design-first” approach is a flavor of the API-first approach, which requires a deliberate effort to build an ecosystem that facilitates the effective design and delivery of APIs.
Why should I apply design thinking principles to API design?
Applying design thinking principles to API design forces us to focus on developer challenges during the process. What are their challenges? What do they need to be able to do their jobs effectively?
API products need to be feasible, viable and desirable. Design thinking helps us build solutions that meet these constraints.
Now, how does this actually work?
Understand the problem without any preconceptions. Go straight to the source for user motivations and pain points. Be a learner and reflect on what you’re learning with your target user group. Identify and address any gaps in your knowledge.
Synthesize your learnings and observations and challenge assumptions while isolating the problem that needs to be solved. This means addressing data integration needs for APIs, perhaps to the level of the business domain or subdomain.
Generate some plausible solutions, logically group them and narrow them down to a set of hypotheses for testing. This may mean types of API products available in the API product space such as resource endpoints, webhooks and SDKs.
When prototyping, be clear in how you express your design intent. Start with lo-fi prototypes and engage users early for valuable feedback. Then, iterate on the prototype and continue to enhance its fidelity based on what you find out.
Although testing, in various forms, should be a part of every phase of the design thinking process, it can also merit its own stage. This is because it presents itself as a gateway between the evolution of the design from a prototype to a product-market fit API.
That's great! But how do I do this?
As mentioned, design thinking is an approach and not a framework. However, there is nevertheless a way to actually DO design thinking when designing API products. Activities related to this approach will help ensure that they deliver a remarkable developer experience while realizing cost reductions and increased revenue.
Here are some basic actionable principles:
Maintain an “outside-in” focus. For example, make sure the API consumer is always front of mind.
Test assumptions regularly.
Engage with early adopters to gain valuable insights on early API prototypes.
Involve various stakeholder perspectives during the API design process.
Shift left on security concerns and identify requirements early in the API design process.
Observe, monitor and reflect on API usage and feedback data.
Evolve the API product by testing early prototypes and gaining consumer feedback.
Develop and evolve a monetization strategy for API products based on learnings derived from collaboration with early adopters.
In other words…
APIs are at the heart of many modern product offerings. We must engage in API design to ensure that we deliver customer value in a secure and scalable manner. Furthermore, we need to engage in design BEFORE any development work starts on the API product itself — this is a challenging task. Unchecked assumptions can find their way into requirements and specifications, leading to costly corrections during the development process. Design thinking can help us address customer needs with API products by better engaging with the problem, aligning perspectives with customers and iteratively building prototype solutions that help us achieve successful product-market fit.
Disclaimer: The statements and opinions expressed in this article are those of the author(s) and do not necessarily reflect the positions of Thoughtworks.