Clarity Jul 7, 2026 The Benefits of Clarity in API Design While discussing my API Design Matters independent consulting, a potential client was presenting API needs in a business domain where I don’t have domain expertise, only cursory knowledge. However, I noted that previously, I have built robust API programs in two very different domains where I did not have extensive domain expertise (analytics at SAS; digital banking at Apiture). There are key API architectures, design patterns and governance practices that are domain-independent, and solid API security fundamentals are critical and applicable across domains. Central to the success of both API programs was that of Clarity. Cone of the most unrecognized benefits of designing good APIs is that a good API design process results in clarity. A well-designed API—and critically, the business process that leads to good APIs—brings clarity to participants and everything the API touches. Clarity benefits the APIs, its consumers… and the business that is producing the API. The Role of Clarity in Align, Define, Design, and Refine Phases of API Delivery In James Higginbotham’s excellent book, Principles of Web API Design: Delivering Value with APIs and Microservices, James introduced the main phases of successful API design: Align, Define, Design, and Refine. The Align phase is the critical business process that brings stakeholders together to understand the underlying business problem and the desired outcomes of the API. The tech team building the API must align with the business stakeholders who want them to build an API. What I have found over many tears (sorry, over many years) is that this process of aligning on the business case requires clarity. Moreover, that process itself helps bring about that business clarity. Often, stakeholders on the Product team understand the business domain, the end users and their problems, the market opportunities, regulations, and business objectives. The people on the Engineering side understand software, programming languages, frameworks, protocols, architecture, validation, code maintenance, build pipelines, DevSecOps, and technology tradeoffs around performance and quality and velocity. For these diverse audiences to succeed in understanding an API’s needs and design, they must communicate with clarity. Clarity in Business Thinking When done well (and I have seen it done very well at Apiture), reaching clarity yields huge benefits: not just in clean API design, but in truly understanding the business’ capabilities and offerings and its market differentiation. In order to capture a business and it’s business value in an API, one must bring clarity. The truly hard work of good API design is that reduction of business processes and flows and tasks into a codified expression of what the business does and how it delivers value, then translating and capturing that in an API. Often, that clarity arises as a result of communicating needs and requirements and excising that which is not needed. Judicious pruning of features and data that are holdovers from legacy systems helps focus thought and API design into the core nuggets of what is truly necessary and beneficial, and what is distraction. The clarity removes distractions and helps teams focus on the core essence of the problem. The Elevator Speech In business formation or when launching new initiatives, we’re often called upon to give “the elevator speech”. By constraining us to a short timeframe (such as a minute or two you might have in a elevator ride), one must be concise and deliver with clarity, or the opportunity is lost. If the audience (decision maker) cannot grasp the core essence of the idea after the elevator speech, the initiative may never be approved. The same is true for a good API. Without clarity, the API design process can easily go off the rails and implement the wrong API. (Good feedback loops can help prevent that early in the process.) However, if the API is not grounded in strong conceptual integrity, where the intent and purpose of the API is not clear and concise and easily held in someone’s mind, the potential consumers of the API may pass it over and look for other offerings. Or, a team may end up building a new API that duplicates the unclear APIs’ function, not knowing what is already there and available because its description lacks clarity. Modes of Thinking The participants in the API design process are often diverse and employ different modes of thinking. The Engineering team may think in terms of software design, services, SOLID principles like single-responsibility principle or bounded contexts, and how something may be implemented. The Product team thinks in terms of the end user and how the user experiences the product over time. Thus, the Product Owner may prefer to use UI mocks to express ideas to socialize them with others, or to validate the UX design with the end users to validate design decisions. That is appropriate, since the end user should be isolated from back-end software and architecture decisions. While there is great value in tools like Figma or Miro or using an AI assistant to create mockups or User Experience demos or proofs of concept, I find such tools to be lacking: they often show what something looks like, but they rarely capture intent and desired outcomes for other stakeholders (i.e. the API design team). Thus, I prefer clarity in framing user stories or jobs to be done. I think that rigor in that mode of thinking brings clarity, and it results in clear articulation of capabilities, behavior, and outcomes that can inform both UX design and API design. For an deeper exploration of this, see a webinar I recorded with Ashley Willard, Apiture’s Director of Product Design, Designing the Ultimate Banking Experience. A Clear Takeaway A good API Design Process uses Clarity to achieve many success factors: Good API Design, Good Developer Experience, Good UX Design, but most importantly, Clear Understanding and Communication of Business Value. Win-win-win-win. Join the discussion