Introduction

How do organizations get their teams to build consistent, quality APIs? And how do they do so without affecting their teams' autonomy and speed of delivery? It's not an easy task.

Many organizations try to solve this dilemma by choosing a design-first approach for API development and picking OpenAPI as the format for describing their API designs. The idea is that if people use the same format for API design, then they'll design consistent APIs, leading to a better experience for their customers.

But these choices come with challenges of their own. Organizations need education programs to teach people how to use OpenAPI to design APIs. They must also define organization-wide styles and standards for API designers to follow during the design phase. And they need tools and processes to enforce those styles and standards across every API. It's expensive and time consuming to do this, in terms of both setup and in educating teams across the organization. Unfortunately, this is a small part of what's needed to institute a design-first approach at scale.

The barrier to entry for learning how to design APIs with OpenAPI is high, and having to learn how to use OpenAPI in a way that conforms to the organization's styles and standards raises the barrier even higher. What started out as a single choice to use the design-first approach branches out to many other challenges—not just in defining the design process, but in finding ways to make the design process seamlessly flow into the development process and into production. Setting up an API development workflow can cause the opposite of the intended effect: teams feel constrained in their development process and feel burdened by the additional processes and tools.

What if, instead of choosing OpenAPI as the API design tool and having to augment it with tooling, training, and processes to ensure quality and consistency, organizations created a tailored language for API design based on their styles and standards? What if the language captured the conversational language of the organization's API design process and made it easier to garner adoption across all the API teams? What if the language limited the scope of what people had to learn to design APIs and created a more inclusive API design process?

This is the goal of the language-oriented approach to API development.

An overview of the language-oriented approach

The language-oriented approach to API development is an approach that encourages people to create their own language for the way they talk about APIs and to capture that language in a DSL. It aims to help organizations create quality-driven API programs at scale. This approach shifts the focus away from the technical details of API design that general-purpose formats like OpenAPI highlight—the URLs, HTTP methods, and JSON schemas—and shifts the discussions toward the conversational language an organization uses to talk about API designs. This results in an API design process and toolset that is easier for teams to learn and adopt, is better at ensuring API design consistency, and is better at encouraging knowledge sharing across the organization.

The language-oriented approach stands in contrast to the common industry practice of restricting and governing the way people use general-purpose formats like OpenAPI. OpenAPI is a great format, but it's a large specification that allows for a wide range of API design approaches, styles, and patterns. Without applying restrictions, people across an organization will design APIs differently and inconsistently. Organizations combat this by restricting what API designers can put in their OpenAPI documents, which means people have to learn much more than OpenAPI: they also have to learn the organization's styles and standards and how to design OpenAPI documents that align with those styles and standards.

This is challenging—it's a lot to learn to design APIs. And it can limit who can be included in the API design conversation.

The language-oriented approach flips this around. Instead of ensuring quality and consistency by constraining the way people use general-purpose formats like OpenAPI, the language-oriented approach encourages organizations to capture the way they talk about APIs in a tailored API design language. This tailored API design language is what's called a domain-specific language, or DSL. A DSL for API design provides the guidance needed to design a consistent, quality API using the organization's styles and standards. Organizations tailor their DSL to the way they discuss, design, and develop APIs. Organizations can generate general-purpose formats from their DSL based on the organization's standards and guidelines, resulting in OpenAPI documents that are always consistent and conform to the organization's style.

This approach provides the governance needed for teams to create consistent APIs and helps share organizational knowledge about API design. People can learn how to use the DSL—which is a much smaller and more focused language than formats like OpenAPI—and let the organization's DSL tooling deal with the details around the styles and standards that go into an OpenAPI document.

The language-oriented approach does not replace the need for or use of general-purpose formats like OpenAPI. Instead it reorients the design process and shifts it away from these general-purpose formats. We don't need better general-purpose formats; we need DSLs tailored to an organization's practice. With the language-oriented approach, people generate general-purpose formats from their DSL. Formats like OpenAPI are still part of the larger API development lifecycle—they're just not the tool people use to design APIs. Thus, the language-oriented approach aims to improve upon the current approaches, not replace them.

The language-oriented approach makes it easier to do upfront, customer-driven API design. It's an approach that organizations like Amazon, Microsoft, and Stripe use to drive their API programs at scale. Although it comes with its own challenges, the language-oriented approach provides many tangible benefits over the format-oriented approach.

What will we be looking at in this short book?

We need a system for thinking about the design-first approach that goes beyond authoring OpenAPI documents as the first step in the design process. "Design-first" has become synonymous with "OpenAPI-first" in the industry. However, we need approaches that help people think about design-first in the context of an organization's practices and style. This short book describes what the language-oriented approach is, shares more details around the challenges and shortcomings of the format-oriented approaches that use OpenAPI, provides benefits and tradeoffs to the language-oriented approach, and looks at companies and projects that follow or employ this approach.