What is Open API? Advantages, Disadvantages & Examples

What is OpenAPI?

According to SmartBear, the parent company of Swagger:

“The OpenAPI Specification (OAS) defines a standard, language-agnostic interface to RESTful APIs which allows both humans and computers to discover and understand the capabilities of the service without access to source code, documentation, or through network traffic inspection.”

That is a mouthful. Let’s break down SmartBear’s description into smaller chunks:

1.“…defines a standard…”:

The OpenAPI specification defines the structure of an API that also describes the API.

2. “…language-agnostic interface to RESTful APIs…”:

• REST APIs use HTTP protocol for data transmission. This protocol allows platforms and systems written in different programming languages to interact.
• OpenAPI deals with RESTful APIs only, not other types of APIs.

3. “…which allows both humans and computers to discover and understand the capabilities of the service…”:

• Humans can read the documentation generated directly from an API’s OAS definition.
• A client understands how it can send requests and how API servers respond to those requests based on the API definition.

4. “…without access to source code, documentation, or through network traffic inspection.”

With OpenAPI, the client application and API server are separated. The API definition of a service defines how clients can interact with it without the need for the client to read its source code.

To summarize, OpenAPI is a RESTful API specification describing APIs that conform to RESTful architecture. A specification provides an interface for letting humans and computers understand an API and how to interact with it.

History of OpenAPI

The origins of OpenAPI start with the engineer Tony Tam of the company Wordnik back in 2009. Tony created a specification (called Swagger at the time) that would describe Wordnik’s online dictionary JSON API.

Swagger underwent several iterations by Tony over the next several years. However, Swagger 2.0 saw an increase in the specification’s adoption and triggered the creation of tools to parse the spec.

In 2015, SmartBear acquired Swagger. SmartBear is the company that currently owns Swagger. The Swagger specification was renamed “OpenAPI” to reflect the new OpenAPI initiative. This renaming is why “Swagger” is confused with the “OpenAPI” standard.

At the time, a group of companies recognized that the industry needed a vendor-neutral and standardized way of describing APIs. The industry needed to provide “best practices” to the industry and oversee updates to OpenAPI over time.

These companies established the OpenAPI Initiative as a governance program under the Linux Foundation that maintains the OpenAPI standard and provides practical guidance. The founding companies that formed the OpenAPI initiative were CapitalOne, PayPal, SmartBear, IBM, 3Scale, Google, Apigee, Intuit, Microsoft, and Restlet. Since then, the number of companies participating in the initiative has grown considerably.

The Technical Steering Committee now manages OpenAPI and continues to release new versions based on community feedback.

Why is OpenAPI a popular standard?

There are several specifications available that describe RESTful APIs. OpenAPI is among the most well-known and widely used. The other two formats used for REST APIs are RAML and API Blueprint. We will cover OpenAPI’s advantages and disadvantages in comparison later. While OpenAPI can be considered the industry standard, in the end, companies often pick the format that best suits their business needs.

So, this begs the question, if there are several formats available to describe REST APIs, why is OpenAPI so special? A key factor for why OpenAPI is so popular is its adoption. More adoption leads to more community support, robust tooling, and more effective governance.

A company may use the OpenAPI specification for its portability and simplicity. OpenAPI is “language-agnostic” and defines a common language for client-server communication. It is highly compatible with systems written in different programming languages. OpenAPI is also highly readable for both humans and computers and has the support of a large, growing community.

Another popular format is RAML, an API modeling language focusing on API definition and design (even though you can design APIs with OpenAPI). RAML’s features may appear to dwarf OpenAPI. It has the advantage of being hierarchical and supporting data model inheritance. However, RAML is not as widely adopted as OpenAPI. While RAML has a dedicated community, it has less community support. RAML has tooling, but there are some indications the latest versions lack the necessary support.

In addition to RAML, API Blueprint is another alternative to OpenAPI. API Blueprint focuses on clear documentation with reliance on markdown format as opposed to JSON (like OpenAPI) or YAML (like OpenAPI and RAML). Because of its low adoption, API Blueprint lacks community support and robust tooling for OpenAPI. Integrating API Blueprint into your entire API lifecycle is difficult because its sole focus is documentation.

In summary, OpenAPI is the most popular standard for describing APIs. While it has disadvantages, OpenAPI will likely grow in adoption while the long-term viability of other specification types is uncertain.

How does OpenAPI Define an API?

Think about a legacy specification document you would read in Microsoft Word (.docx) format. This legacy specification document provides the broad context of a system and describes its components and interactions with other systems.

The structure of legacy specifications often varies. An API specification, like OpenAPI, is strictly structured. If an API specification conforms to another format, like RAML or API Blueprint, the documentation has a structure that adheres to that format.

Going back to how OpenAPI defines an API, you will often hear “specification” and “definition” used synonymously. An API specification “defines” an API. When reading an API specification, you learn about the kinds of requests you can send and the responses you expect to receive back from the API. In addition, the specification describes the available options that affect the information returned. Like a legacy specification, you learn about a system, its components, and its interactions.

Another difference between legacy specifications and API specifications is that API specifications are dynamic. Whenever the underlying source code of an API changes, the documentation updates. Legacy specification documents require manually updating Word documents whenever the system changes.

OpenAPI Format

Before understanding the structure of an OpenAPI specification, you must understand the format of an OpenAPI document. Unlike legacy specifications written in Word, OpenAPI’s format is JSON. While discussing the nuances of JSON is out of scope for this blog post, think of JSON as a way of representing the data of an API as key-value pairs.

For example, in legacy specifications, you would write the title of a specification (including the name of the system) using a Title style on the cover page. To write the title of an OpenAPI spec, on the other hand, you would write the title as a JSON key-value pair.

Now, think about all the information about an API. Its methods, operations, responses, etc. Imagine all these properties documented in a series of these key-value pairs that follow the OpenAPI structure.

Note: While JSON is the standard format for OpenAPI, It is possible to represent OpenAPI in simpler YAML (an acronym that stands for YAML ain’t markup language).

Data Types

As a JSON object, the OpenAPI spec supports data types defined in the broader JSON Schema Specification. Primitives include integers, numbers, booleans, and strings. You may declare the format of a data type using the modifier property format. For example, you may declare an integer as int32 or int64 format, a number as a float or double, or a string as binary, data, date-time, or password format. OpenAPI also supports models (objects) defined in the broader JSON specification as schema objects.

It is important to note that JSON is the primary format REST APIs use to send and receive information.

Structure

So far, we understand that:

• An OpenAPI spec is a JSON object.
• The properties of an API are a set of key-value pairs.
• Values are data types defined by the broader JSON specification.

Now, it is time to discuss OpenAPI’s structure.

As mentioned before, an OpenAPI document is strictly structured. Objects or arrays of objects group related key-value pairs. The high-level objects of an OpenAPI spec are like the chapters in a legacy specification document.

Below is an OpenAPI template with collapsed sections to show the overall structure. Every section has properties, or key-value pairs, that provide metadata about the API.

The top level of OpenAPI, indicated by the first sets of brackets { }, is called the “document object” because it contains all OpenAPI properties.

While OpenAPI documents must conform to a basic structure, OpenAPI offers some flexibility. Some of the high-level sections are required, while others are not. You will notice OpenAPI specs for different APIs may look slightly different.

An OpenAPI document may contain the following sections:

• Openapi – A required field defining the OpenAPI spec version of the API. Tools use the version number to parse the OpenAPI spec to generate documentation, for example.
• Info – A required field containing metadata. Tooling can leverage metadata in different ways.
• Servers – An array of server objects. Each server object contains the connection details to a server. This object contains the URL to the server host and a description of the server.
• Paths – A required object that contains the relative paths to the separate endpoints of the API. A given path has available operations for interacting with the API such as POST, GET, PUT, or DELETE.
• Components – an object that contains reusable schemas for request bodies, response schemas, and security schemes. Schemas in this section are referenced in certain parts of the spec, like the path object, using the $ref tag.
• Security – an object that declares the type of security scheme authorizing requests. A security object is defined globally or overridden by individual operations (security scheme override).
• Tags – an object containing metadata. Tools that parse the spec can leverage this object. For example, you can specify the order you would like each API resource to display in your API documentation (rather than in alphabetical order).
• ExternalDocs – an object that provides links to additional documentation. You may use this object to add a link to your user guides.

Also, check out our blog on API documentation checklist & FinTech API

Schemas

At the bottom of your API documentation, there is typically a Schemas section that corresponds to the schemas described in the components section of the API definition.

This section is a quick glossary for when the reader needs to view general schemas in the broader context of the API (not their use in particular operations). Schemas are objects that contain properties/metadata.

The following schemas section for the Swagger Petstore shows spec-wide schemas. Order is a schema representing an order placed for a pet in the Swagger Petstore. Each order has its metadata, including its Id, the date it was shipped, and the order status.

OpenAPI Strengths

OpenAPI has the following advantages:

• Clear documentation – OpenAPI is known for its easily readable documentation for humans and computers.
• Language-agnostic – Clients can interact with API servers without knowing the implementation of the server. Other formats like API Blueprint require third-party code on the server and do not provide any of this code for you.
• Governance – The OpenAPI initiative maintains the OpenAPI standard and is moderated by industry leaders.
• Wide adoption – OpenAPI is the most popular format for describing REST APIs. The extent of its adoption indicates that OpenAPI is here for the long run. A specification, like API Blueprint, suffers from a lack of adoption.
• Robust tools – Being the most widely supported format, there is now a proliferation of tools that leverage OpenAPI for generating documentation, testing, etc. Other specifications lack OpenAPI’s support and maintenance for tooling.

OpenAPI Weaknesses

Each specification type has its strengths and weaknesses. Here, we will focus on the disadvantages of OpenAPI compared to its closest rival, RAML.

Less useful for API design and planning

You can take a “spec-first” approach to design an API based on OpenAPI. This approach involves writing the OpenAPI spec for an API “by hand” or using a design tool. Using this approach, you design an API’s spec and then use the spec as a “contract” when building the API. The opposite of “spec-first” is to use OpenAPI to generate documentation without using it as a design tool.

While the “spec-first” approach has many advantages, OpenAPI usually does not come before API development.

The hierarchical structure of RAML may lend itself more to being a design and planning tool. As such, RAML may support the “spec-first” approach more than REST. In the end, RAML is marketed as a “data modeling” and API “description” tool, whereas Swagger is the latter. RAML’s hierarchical model is discussed more in the next section.

Not Hierarchical

One of the core concepts for API definition standards like OpenAPI and RAML is the ability to create data objects and relate them together. OpenAPI uses schemas for this purpose and supports JSON’s built-in data types. RAML uses a type system to save associated properties and promote reuse across the spec. It also supports the same built-in data types as OpenAPI.

OpenAPI does not have a “true” hierarchical structure. What do you want out of a hierarchical structure that describes your API? Ideally, you want a system for associating your data models that is:

• easily readable/understandable
• allows for defining relationships amongst data models using inheritance
• reduces repetition of shared properties
• maximizes code re-usability

RAML’s type system lends itself to being a more hierarchical system than REST. According to RAML’s Readme on GitHub, RAML’s use of “resource types and traits minimizes the repetition in a RESTful API design and promotes consistency within and across APIs.” We will discuss RAML’s type system in more detail next.

Does not support data model inheritance

RAML’s object types can inherit other object types. While OpenAPI schemas can “reference” schemas, it does not technically support inheritance as RAML does. I say “technically” because you can link one schema to another using a schema reference (the $ref tag). However, RAML goes a step further. You can establish relationships between data models and avoid the repetition of shared properties. With OpenAPI, schemas are not associated with one another in a hierarchical way like with RAML. RAML types have “true” inheritance, where you can establish parent-child relationships between data models.

Not a “visual” tool

RAML’s use of types as data models makes it more visual and easily readable than OpenAPI. You can easily see the relationship between types and their shared properties.

RAML, as a more visual tool, promotes long-term planning for things like mock server responses, API consoles, and more. It may be also to anticipate and plan for future API improvements using RAML.

Lack of Support for Other Architectures

OpenAPI only can describe RESTful APIs. RAML has the added benefit of supporting other architectures besides REST, such as RPC or SOAP, as long as they use the HTTP protocol. RAML’s flexibility allows you to use it as a documentation tool for architectures besides REST.

OpenAPI Example – Swagger Petstore

The best way to learn OpenAPI is to take a hands-on approach. Certain tools allow you to edit OpenAPI specs and then generate API documentation. The Swagger Petstore specification is an example of an OpenAPI document.

SwaggerUI is a tool that parses an API definition to generate documentation. SwaggerUI has a browser-based editor (shown below). You can experiment with the SwaggerUI editor here: https://editor.swagger.io/

On the left-side panel, the OpenAPI specification in YAML format is visible. Whenever you make changes to the spec, those changes generate new documentation in the right-side panel. The right-side panel is the Swagger document generated directly from the OpenAPI spec for the Petstore (left-side panel). For example, changing the description of a path causes the Swagger document to refresh with the new changes.

If you look at Swagger’s OpenAPI spec on the left, you will see all the sections described in this blog article, including openapi, info, servers, paths, components, tags, etc.

Swagger generates an error when you deviate from the OpenAPI structure or enter something invalid. Swagger’s error handling reinforces the concept that you must adhere to the OpenAPI format for documentation to display correctly. Once you become familiar with the Swagger Petstore, you can paste the specification for another API into the Swagger Editor to see how its information displays in SwaggerUI.

In summary, Swagger Editor is a great way to become familiar with how to write API definitions and how tools parse the spec to generate documentation.

Read more:  6 Best API Documentation Tools for 2023 & What is API Developer Portal with Best Practices & Examples

Further Reading

For more in-depth documentation on the OpenAPI standard, read the official SmartBear documentation for OpenAPI: https://swagger.io/specification/.

Also, check out our guide to launch public API

Ready to take your API documentation to the next level? Book a demo with Document360 today!

Book A Demo