Design-first is a concept that has gained a substantial following in the API development landscape. It promises a range of benefits, from improved user and developer experience to a faster time to market with reduced development cost. For these reasons, design-first supporters often frame it as a silver bullet for the issues facing API development and management.

But not everyone is super confident in design-first approaches. Some technical leaders feel that design-first introduces as many problems as it resolves, leaving many of us to ask: why do design-first at all? Taking to LinkedIn, Kin Lane, the API Evangelist, posed this question:

Is API design-first real? Or are we just dreaming?

The question is a fair one to ask, and the responses were quite illuminating. Today, we will look at where developers stand on this concept via the feedback on this thread, and we’ll present four very clear takeaways on design-first.

It’s Complicated

Many developers believe that design-first, while good in theory, is, on the whole, a complicated topic in reality. Actually getting to the point where design-first is utilized and productive requires a substantial amount of buy-in, and that buy-in has not always been easy to achieve.

Bryan Cross, Enterprise Solutions Engineer at Postman, had this to say:

“I wonder if 100% design first has really been fully realized/normalized in any aspect of Software Development. It’s always been somewhat aspirational, foundering on the reality of schedules, the need to release new features constantly, competition and technical debt.”

This is a very salient point. Much of the problem with design-first comes from the fact that it requires full buy-in at a level that may be unrealistic in practice, especially in a team that is extending and developing an already-set product. In an organization with an entrenched product mindset, adopting any single paradigm is difficult. Advocating for a paradigm that may be at fundamental odds with business logic and approach makes design-first particularly difficult to generate buy-in around.

Some of this complexity may arise from the way design-first as a strategy is sold and internally discussed. Some developers will reject new practices, and this percentage only increases when the core value proposition is unclear. Accordingly, if design-first is to become a reasonable approach, its benefits need to be validated and sold at scale. These include outcomes like improved collaboration, closer fit to business logic, increased clarity, and better user and developer experience.

Key Takeaway: Design-first is not a silver bullet, one-size-fits-all paradigm.

It Hinges on Great Tooling and Standards

Others are decidedly more positive about the design-first concept and see major potential future growth. John Dohoney, Jr., Senior Cloud Solutions Architect at Microsoft, noted that “with tools like Github Co-Pilot, API Code First is starting to look like the way to go.” David Yonan, Customer Success Lead at Solo.io and Founder at FlowStep had a similarly positive view, noting that “[Design-First] is absolutely possible, you just need the right framework, tools and approach.”

The reality of any new technology is that the structure supporting it is critical to long-term success. The telephone is nothing without the wiring systems to transfer the signal, the internet would be nothing without workstations, and so on. In the world of design-first, the tools required to actually govern the development and implementation of projects utilizing the core principles are vital to long-term success and health. Accordingly, immature design-first strategies beg the question: Is the tooling as it currently exists “enough”?

Kin Lane notes that much of this long-term success can be unlocked with effective standards and patterns:

“Applying and reuse of existing standards and patterns is an important aspect of this. Investing in industry standards bodies who are design-first, leveraging government regulation to incentivize change, will definitely play a strong role in top down movements towards design-first.”

As important as the tooling itself is, the standards play a huge role in this. For instance, we all use HTTP/S at scale to facilitate large-scale intercommunication. We all have phones, but it is the specific electrical and telephonic connections that we use to connect countries and territories. Defining the core standards that make up the effective design of an API and then discussing how to use those as the “first” element is critical to making this a value-adding proposition.

Key takeaway: Design-first requires adequate tooling and standards to be worth it.

It Depends on the Environment

Many others felt that the use of design-first comes down largely to the environment. The general sentiment seems to be that design-first does make sense in certain specific situations, with Kin Lane stating:

“Design-first won’t always be the answer in all projects, and its application will vary from industry to industry, enterprise to enterprise, and team to team.”

Imagine for a moment that someone asks you what is a better connection: HDMI or DisplayPort. That question leaves out a lot of context needed for the answer. What system are we connecting from, and what are we connecting it to? What standards are supported? Do we need audio or just video? How many displays are needed?

The answers may vary significantly. Similarly, we should ask for context when evaluating design-first. Is the problem with design-first that it’s a good idea in theory with few practical applications, or is it more accurate to say that design-first is a powerful solution in certain contexts and that selling it as a cure-all misses the mark?

There’s also the team context to consider. Even if the product calls for a design-first approach, the teams implementing it may not be properly set up to reap its benefits. Adriano López Núñez, Solutions Architect at Falabella Financiero, notes this in the following post:

“I think it largely depends on the vision of the team leader’s role, since not everyone has the same concept of the API life cycle, therefore the API-First approach is distorted, added to the imperative need to ‘move fast.'”

Key takeaway: Design-first has major benefits in specific use cases and team structures, but it’s not a panacea.

There is Untapped Potential in Design-First

Many developers feel that design-first is already making major waves and granting huge benefits, and that much of the conversation misses out on these positives. Miguel Quintero, Senior API Designer at Delta, noted:

“It is real. A rollercoaster testing your patience and leadership at every phase of software development.”

Design-first, or API-first, has major benefits but brings with it major complexities and difficulties in application. One interesting point was raised by Bobby Lancaster, Solutions Consultant at ServiceNow, arguing that the resistance to design-first may come from the overfocus on the micro at many API firms:

“It’s real. We’re just not dreaming big enough. I remember our discussions about JCR Licklider and his vision for the Internet: the Intergalactic Computer Network. If you think intergalactically about networking computers, API-first design makes sense.”

There is some merit to this concept. If the ultimate goal of the internet is to be a massive interconnected computer network, then the idea of adopting design-first makes much more sense. Still, the argument could be made that each individual part of such a network still needs to function as its own service (or macro-microservice), and if that’s the case, design-first may be good for the whole but poor for the individual solution.

Key takeaway: Design-first has huge potential upside.

Example of Design-First

Design-first is not limited to theory: there have been several cases where design-first has actually paid off. One concrete example is the work by Maho Pacheco and Renato Marciano at Microsoft, who detailed their development process with design-first via the Microsoft Developer Blog. Their specific environment represents the best-case scenario for a design-first approach: the need for a new product with a set contract handling large amounts of data within a specified framework and structure.

In this case, design-first is a powerful solution. Because a firm contract is needed, and contract adherence over a large amount of data is vital to ongoing success, establishing a design-first approach ensures that the new product functions and scales as expected from day one. The team greatly benefited because this was both a new product and one whose team could shift to a design-first approach. Had the team been working on an established product that did not have a single contract or form and function, design-first could have been more difficult to utilize. If that team had also been ill-structured for this approach, it would have been much more difficult.

Conclusion

Where does design-first stand, with all these various opinions? The reality is that how one feels about design-first has a lot to do with how one views their API in context. Someone just coming into the development process may view design-first as a strong concept because they are at the very start of their development lifecycle — the hurdles are minimal and easily overcome. On the other hand, an enterprise developer may view design-first as a shift with very little benefit, requiring a significant overhaul.

The reality is that they’re both right. Design-first may often be discussed as a one-size-fits-all solution, but the reality is that it’s just one option. And just like a wrench is really only suitable for “wrench things” and a screwdriver is only good for, well, driving screws, design-first has a narrow band of applicability and usefulness which does not establish universal value for all teams and situations.