The digital world runs on APIs. As we progress through what will likely become known as the “decade of APIs,” all indicators suggest the API market will continue to grow. The growth we see related to new digital ecosystems, new SaaS platforms, new marketplaces, new as-a-service offerings, and continued digital transformation of heritage organizations, all contribute to one common outcome: more APIs!

The rise of APIs, both inside and outside organizations, is often referred to as API sprawl. It’s a term that has some negative connotations, and with good reason, as it’s normally associated with little concern for planning. The difference between urban sprawl and a developed, thriving, inviting city is planning, foresight, and appropriately applied constraints. In the land of APIs, the same holds true. A proliferation is exactly what we want to see, but with appropriate planning, structure, and governance to ensure benefits can be realized.

API specifications help navigate the potential chaos caused by API sprawl and bring many practical benefits to organizations and teams, regardless of their demographic. Below let’s look at some common benefits that specifications bring, but before we jump in, here’s a quick recap.

What Are API Specifications?

In general terms, a specification is a technical document that tells you how something works. API specifications are no different and have the general advantage of being both human and machine-readable. They are not a new concept. For example, the Web Services Description Language (WSDL) has been around for over two decades.

There are varying specifications in use across the industry. Some of the more popular ones are:

• WSDL: Web Services Description Language is an XML-based interface description language used for describing the functionality offered by a web service. WSDL is often used in combination with SOAP and an XML Schema).
• WADL: Web Application Description Language is an XML description of an HTTP-based web service. It’s often referred to as the REST equivalent to SOAP’s WSDL (although WSDL can also describe REST web services).
• OpenAPI: OpenAPI Specification (OAS) is a specification that defines a standard and language-agnostic interface to HTTP-based APIs. The OAS allows humans and computers to understand the service’s capabilities without access to source code, documentation, or network traffic inspection. Version 2.0 and below of this specification were known as Swagger. Since the donation of the spec and formation of OpenAPI, Swagger represents a rich set of tools used to interact with and implement API specifications.
• RAML: RESTful API Modeling Language is a YAML-based modeling language for describing RESTful APIs.
• API Blueprint is a documentation-oriented web API description language. API Blueprint is essentially a set of semantic assumptions laid on top of the Markdown syntax.
• AsyncAPI is used to describe and document message-driven APIs in a machine-readable format. It’s protocol-agnostic, so you can use it for APIs that work over any protocol (e.g., AMQP, MQTT, WebSockets, Kafka, etc.). It’s often referred to as a sister specification to OpenAPI.
• GraphQL Schema is the specification for GraphQL, a query language and execution engine originally created at Facebook in 2012 for describing the capabilities and requirements of data models for client-server applications.
• JSON Schema is a domain-specific language (DLS) that allows you to annotate and validate JSON documents. It enables the confident and reliable use of the JSON data format in both a machine and human-readable interoperable structure. The primary use is for defining, sharing, and validating JSON data, such as API payloads in OpenAPI and AsyncAPI.

Let’s Talk Benefits!

Note: All benefits below are not universally possible across the specifications listed above. The focus here is predominately based on experiences with OpenAPI and AsyncAPI.

Human and Machine Readable

Modern API specifications have the benefit of being readable by humans and the machines we use to help us produce or consume APIs. One of the biggest challenges when delivering understandable, usable, and useful APIs is ensuring that human stakeholders involved in the process can collaborate, converse, and refine the products being built at the optimal stages in the process. API specifications play a crucial role by being accessible to humans and are increasingly used by architects, product managers, API designers, testers, developers, information security officers, operations, and customer success teams to shape the capabilities across their organizations. The specifications allow cross-functional participation (remember — APIs are not just for IT) and act as the artifact to facilitate validation on whether the API being delivered addresses a given problem space in a manner that aligns with company standards.

The YAML or JSON formats that are catered for by most specifications are very much machine-readable and support interoperability with a plethora of technical tools used through API delivery and consumption.

Drives the API Lifecycle for Producer and Consumer

API specifications do more than just document what an API looks like. A consumer can understand and interact with the remote service with minimal implementation logic. The same is true on the provider side of an API, as stakeholders can communicate more effectively on the value proposition offered by any service.

Figure 1 — Example of how OpenAPI can drive the API Lifecycle

Using an API definition can help power and automate many stops along the API lifecycle. These capabilities include client and server code generation, mocking the implementation, virtualizing common use cases to support better consumer onboarding and test automation, as well as supporting the delivery of first-class documentation to tell the story of the API. This automation potential reduces waste from the development cycles on both the producer and consumer sides of the API.

Figure 1 above illustrates the popular design-first approach to delivering APIs which focuses on iterating toward an approved API contract (e.g., OpenAPI definition for an API) with available documentation and mocks to allow stakeholders to validate that consumer needs are met, the market/business problem is being addressed, and the API is consistent with any established organizational design standards. All these criteria are checked as part of the design phase before implementing the API code.

Design-first is not the only approach to API delivery. The consistent use of specifications, albeit at different phases of the lifecycle, still brings the ability to assert governance, quality, and developer experience (DX) checks to ensure the published API is as discoverable and usable as possible. In a code-first approach, the specification document is generally created through code annotations or crafted at the point of registering within a gateway. Once available, it can be used to generate tests and execute assertions to ensure the API meets the governance and quality gates required. A third mechanism that can be applied to existing APIs is to generate the specification based on the traffic hitting existing endpoints. This reverse engineering technique is useful for understanding the quality and compliance of existing APIs and helps plan effective actions for bringing such APIs into a more standardized lifecycle.

Supports the API-First Mindset

Combining the human-readable element of API specifications, together with the ability to leverage them to drive the lifecycle of an API, supports any organization looking to implement an API-first strategy. API specifications act as a reference point for the most crucial facet of API-first — the people involved. They afford the ability to remain customer-focused and sufficiently decoupled from implementation aspects of delivery.

In simple terms, this allows enterprises to apply the appropriate guardrails to ensure maximum developer experience for consumers while ensuring sufficient optionality for the teams producing the APIs. Technology stacks and tooling choices need not be consistently universal within an organization, and this flexibility is one of the critical factors when it comes to changing minds, hearts, processes, architectures, and design standards to mature into an API-first company.

Improving Developer Experience Matters

As competition in the API market reaches a boiling point, the DX is crucial. We build APIs to be consumed, and it’s still a human who discovers, evaluates, onboards, and integrates an API to help them solve a problem.

Well-designed APIs with familiar specifications can leverage a rich ecosystem of tools to reduce the consumer’s Time to First Hello World. This can speed up the ingestion of the API value into the customer value chain.

Providers that approach the curation of APIs using specifications to produce consistent brand-aware products with excellent documentation and virtualization empower companies to reduce delivery waste and speed up their time-to-market. Perhaps more importantly, it can make a company’s APIs stand out from the crowd in today’s busy API marketplaces.

Supports Modern Composable Business Models

Organizations are striving to build more robust digital experiences in a predictable and faster cadence. As such, the concept of composable business models is gaining popularity. This approach promotes customer-centered flexibility and adaptability and aims to ensure a common understanding across an organization of how business value is positioned, composed, and ultimately offered. The value can be exposed both externally and internally. Achieving such an organizational strategy requires many ingredients, but microservices, APIs, and a well-thought-out API strategy are foundational elements that must be established before taking such loftier steps.

The role API specifications play at an organization level cannot be understated, as their ability to hydrate various tools plays a vital role in affording the ability for organizations to discover, catalog, govern, and manage their composable assets. Ultimately, a composable architecture would enable a company the ability to discover all the company’s API capabilities, promote their reuse in a modular way, choreograph or orchestrate them into new applications (or API products), and execute toward measurable business outcomes.

If you can’t discover your APIs, how can you promote their reuse? How can you ensure they are secure? How can you validate they meet developer experience needs? How can you confirm they align with your API standards?

Powering Industry Standards

API specifications are also being leveraged across various industries to drive consistent standards and adoption. Within financial services, OpenAPI is used extensively for providers implementing the Payment Services Directive 2 (PSD2) standard within the European Union, and similar approaches are evident across other jurisdictions.

The concept of “Open Insurance” is also gaining momentum. Although no uniform definition yet exists, industry working groups like The Open Insurance Think Tank (OPIN) have published a first version of an API specification to unify how the insurance industry defines and describes APIs.

In the travel sector, OpenTravel is shaping how APIs are delivered across the abundance of providers in the travel industry to unlock interoperability to provide a better overarching experience for end consumers.

Yet another example is Open Referral, which uses OpenAPI to provide definitions to share, find, and use information about health, human, and social services at a municipal, city, or county level, not to mention the use of OpenAPI for the FHIR specification within healthcare.

While the above is not an exhaustive list, it highlights that specifications are playing an increasingly important role in shaping the landscape across many industry verticals.

Conclusion: Use API Specifications for your APIs

API specifications provide an essential framework for achieving governance and interoperability goals across teams, organizations, and industries. Their human and machine-readable nature allows them to speak a common language earlier in delivery cycles and prevents stakeholders from becoming distracted by the underlying technology. Specifications empower providers to work as a team, collaborate effectively, and help address change management and the evolution of their products. Specifications provide the mechanism to quantify the scope of change, making it easier to understand if any proposed change will break the contract advertised to consumers.

The use of specifications is increasing, and even more crucially, specifications and the communities chartered with their evolution are not standing still. As an example, new versions of JSON Schema, OpenAPI, and AsyncAPI continue to evolve to meet the needs of the modern digital world. With this increasing move toward open standards, the OpenAPI Initiative (OAI) has created several special interest groups (SIGs) which focus on the usage, adoption, and potential enhancement of the OpenAPI Specification (OAS) as well as other specifications for specific industries, such as finance and travel.

The benefits above are a zoomed-out view of the higher-level advantages that API specifications bring to the table. As most organizations find significant challenges with standardizing and governing their API delivery approach, it should be clear that specifications enable automation and resiliency opportunities across the lifecycle. They are fundamental to achieving consistency for consumers, providing the safety to address technology debt without breaking upstream dependencies, enabling better oversight on security across API surface area, and unlocking improved team productivity — all while saving on over-collaboration.

For more insights, register now open for API Specifications Conference 2022.