What is OpenAPI?
Originally known as the Swagger Specification, the OpenAPI Specification (OAS) is a format that can be used to describe, produce, consume, and visualize RESTful web services. It is a specification standard for REST APIs that defines the structure and syntax. Most notably, it is programming language agnostic. This enables both computers and human users to identify and understand service capabilities without requiring additional documentation, accessing source code, or inspecting network traffic. The OAS removes the guesswork from calling services similar to the way that interface descriptions simplify lower-level programming. With OpenAPI, you can quickly discover how the API works. API specifications are typically written in YAML or JSON.
An OpenAPI file describes an API in its entirety, including:
- Endpoints: which are available (/users) and operations on each (GET /users, POST /users)
- Authentication methods
- Operation parameters for each operation (Input and output)
OpenAPI vs Swagger
OpenAPI was part of the Swagger framework until 2016 when it became a separate project. Now it is overseen by an open-source collaboration project of the Linux Foundation called the OpenAPI Initiative. Today, tools such as Swagger can generate documentation, code, and test cases for the OpenAPI specification based on interface files.
To understand the Swagger vs OpenAPI difference, it's necessary to perceive the distinction between the specification, the tools that help to implement the specification, and the users.
OpenAPI is what the specification itself is called. The OpenAPI specification was originally developed by Smartbear Software, who later donated the specification. Now, the OpenAPI Initiative fosters the development of the specification, in a collaborative partnership with over 30 organizations. Smartbear Software, which today leads the development of Swagger tools, is a member of the OpenAPI Initiative, as are Google, Microsoft, CapitalOne, IBM, and other organizations representing different parts of the tech world.
Swagger is a widely used toolset for implementing the OpenAPI specification developed by Smartbear Software. There are a mix of free, open sourced, and commercial Swagger tools which users can deploy at different stages of the API lifecycle. There are also other OpenAPI tools available.
Swagger tools are frequently still perceived as synonymous with the specification since they were developed by the same team in tandem with its creation. But the Swagger tools are not the only available tools for implementing the OpenAPI Specification. A full list of a wide variety of API documentation, design, management, testing, and monitoring tools and solutions that support the latest version of the OpenAPI specification is available on GitHub.
Why use OpenAPI?
There are several important reasons to use the OpenAPI specification. Below we explore some of the more notable reasons developers turn to the OpenAPI standard.
Single point of truth
An OpenAPI definition is machine-readable and serves as the single source of truth for the API. This allows the import of API definitions into clients for manual testing and ensures each piece of the system can be verified against the specification. In larger API deployments, running an API gateway in front of an API implementation allows users to compare incoming and outgoing traffic against the specification. It also allows users to assess third party APIs against OpenAPI definitions—all to reduce the risks of product malfunction.
By using a single file to describe an API, including objects, endpoints, and path, users can convert either a server-side or client-side description into a specific implementation whose code is a product of the description. This reduces misalignment between the back-end-offered API and the client-consumed API.
OpenAPI allows users to automatically generate API clients, to be updated with the latest client changes as needed. Generating API clients out of projects automatically enables them to be managed, integrated, and consumed just as any other third party dependency would be and avoids the need to program typical boilerplate for each project. Once the API is defined, users can build and generate client code for Android, iOS, and most other programming languages in seconds.
Readable, updated documentation
Both YAML and JSON formats are easy to read and modify, and the OpenAPI definition file can be described in both. This means no particular programming language or framework is needed to make or discuss changes.
Neither out-of-date documentation nor missing documentation is acceptable. Because OpenAPI becomes a single point of truth, even API documentation kept solely for internal use is never outdated, as the entire API specification is in a single format which several tools including the documentation generator can automatically process.
OpenAPI is the current de facto industry standard for API definition. This means that any user can access services from an API using this specification without any extra setup, out-of-the-box.
OpenAPI is distinct from other specifications in that:
- It delivers a language agnostic, standard interface for describing RESTful APIs
- It is understandable to human readers and machine readable
- OAS consumers, human or machine, do not need any additional documentation or access to source code or traffic to understand the capabilities of service under development
This enables users to build reliable, adaptable, user-friendly APIs for clients and interact easily with remote services using minimal implementation logic.
Who uses OpenAPI?
Here are some of the industries that benefit tremendously from OpenAPI technology:
OpenAPI technology allows businesses in the eCommerce sector to scale up services rapidly to meet consumer demand. The top eCommerce platforms in the world are favorable to open source designing, which means that implementing the design framework for most eCommerce APIs is typically simple for API designers who use OAS.
APIs in the media industry such as Twitter often use the OpenAPI specification, because it greatly adds to APIs that disseminate information to the public rapidly and efficiently.
Open government generally refers to providing open data through APIs to serve government functions in new ways, or providing open APIs that serve privileged government functions with the right consent. For example, governments might provide taxation information through an API to avoid needing to pay a specialist to prepare their taxes, or offer an open registry of births and deaths. The US government currently offers a catalog of open APIs here online.
When to use OpenAPI
Among the biggest pain points for API developers is inaccurate and outdated documentation. An API that is not well-documented is difficult or impossible to integrate, but many developers write documentation that is not comprehensive, or avoid writing documentation altogether.
OpenAPI solves this problem by making it simple to generate documentation automatically that always matches the changing architecture of the API. It also enables the use of various automated tools, since API descriptions are machine readable. All of this means developers can spend more time coding and less time documenting.
Documentation is the most visible OpenAPI output, but there are numerous other applications. Other OpenAPI examples include setting up testing such as continuous integration using the OpenAPI file that generated the documentation.
OpenAPI best practices
Adopt REST patterns
Don't reinvent the wheel as you write descriptions for your endpoints; look to established conventions that developers are comfortable with and have experienced across many APIs. The easier it will be to integrate with your API the more similar it can be to something developers have seen before.
HTTP APIs often use the Representational State Transfer (REST) architectural style. There are three major API criteria to watch for, although most users don’t adopt the patterns wholesale:
- Organize the API around resources
- Communicate actions using HTTP methods
- Rely on standard HTTP status codes
Create friendly descriptions
Any API definition includes technical details, but should also include many human-readable description and summary fields throughout the definition. For example, endpoints, parameters, and responses within parameters all require a summary of HTTP methods. Blank or useless text in these fields hurts the quality of OpenAPI documentation for the API and obfuscates the context around the expected outputs and inputs and the purpose of each endpoint.
In a RESTful API design approach, the API is organized around resources. Using nouns for those resources is a common naming tactic, and users should choose either singular or plural nouns and stick to it for that API—and all APIs, if feasible. Aim for consistency in naming fields, and consider punctuation and capitalization. Also, choose and stick with a naming convention.
And while meaningless names may work for the API endpoints and the fields in the results and parameters don’t technically need human-readable labels, unwieldy and meaningless API calls are atypical in that it's difficult to remember their purpose long enough to copy them to code. The bottom line is giving users a seamless experience with the API. Predictable names allow developers to make tweaks to code easily, sometimes without reference to documentation.
Continuous integration and delivery
After OpenAPI definitions are created, ideally documentation is generated automatically. As part of their development workflow, many software teams use a continuous integration (CI) pipeline. This allows for automatic testing against changed code in real time. Similarly, teams can deploy the code automatically once they have accepted the changes, either to a staging environment for further testing, or, if the team has adopted continuous delivery (CD) practices, directly to production.
How OpenAPI supports API security
Yes. Noname Security is a Holistic API security solution that protects APIs from authorization issues, data leakage, misuse, abuse, and data corruption without network modifications or agents.
Noname allows users to analyze APIs and user behavior, delivering accurate and actionable vulnerability detection and breach prevention. The system provides unparalleled discovery and classification capabilities, enabling deeper insight into APIs, API inventory, data, users, and third party interactions.
Noname allows you to discover the misconfigurations so common to complex environments, such as configuration flaws, shadow IT and rogue APIs—before attackers exploit and abuse them. In fact, the system allows you to see how your APIs change before users can, to detect and correct flaws as they are created.
Simple to connect and use, learn more about OpenAPI and API Security with Noname Security.