2023 OWASP API Security Top 10 Best Practices
After four long years since the original…
The OpenAPI Specification (OAS) is a framework used by developers to build applications that interact with REST APIs. The specification defines how to communicate with an API, what information can be requested, and what information can be returned. With OpenAPI, developers can ensure their APIs are consistent with the industry standards and can easily integrate their applications with other services.
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’s 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:
OpenAPI parameters are used by developers to build applications that interact with APIs. It is a specification that defines how to communicate with an API, what information can be requested, and what information can be returned. They allow developers to understand how their application will work before they start coding it. They can also be used by software testers to test APIs before they are released into production environments.
A query parameter is a commonly used parameter type. This is a URL snippet that follows the question marks in the full URL. Query parameter names can have multiple values in their URL. There are no hierarchy components within the URLs. Allowing clients to limit their data requirements would have fewer consequences and would result in an unneeded load on the server. The client could describe the page numbers or offset of page content (limits), e.g.: These variables are defined in the parameter object for OpenAPI definitions.
Paths parameters can help define the location of data that is used by a client.. e.g. a website. Path parameters belong to the hierarchy of a URL, therefore they are sequential. An endpoint can have more than one path parameter. Unlike query parameters, path parameters can be found on the left side of the question mark within a URL. Objects for path parameters are mandatory and must be inserted within the parameter class of the corresponding method.
Header parameters are a set of key-value pairs that can be used to configure the behavior of an API. Header parameters allow for more flexibility in how an API is consumed, which is why they have become so popular in recent years.
Cookie parameters are used by web servers to store information about the user’s session on the server, such as their IP address, browser type, and language.
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.
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.
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 API specifications. It also allows users to assess a third party API against an OpenAPI definition—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.
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:
This enables users to build reliable, adaptable, user-friendly APIs for clients and interact easily with remote services using minimal implementation logic.
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.
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.
When describing HTTP APIs, developing comprehensive documentation, or placing an API in development, it’s important to follow OpenAPI best practices.
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:
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.
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.
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.
Experience the speed, scale, and security that only Noname can provide. You’ll never look at APIs the same way again.