Services and applications expose interfaces that we call APIs. Every service can define its APIs in any way it wants provided those APIs are properly documented. However, there are benefits in following a standard to define or describe an API. This is exactly where the OpenAPI Specification (OAS) becomes relevant.
OAS defines the rules, syntax and semantics for describing a RESTful API. OAS is language-agnostic, that is, it can be used for writing code in any programming language. It's in a format that can be read by both humans and machines. It's self-contained: no additional source code or documentation is required to understand an API specified in OAS.
What are the benefits of adopting the OpenAPI Specification?
OAS enables higher efficiency, better collaboration, stable implementation and faster time to market. It makes APIs reusable and maintainable. More people can understand an OAS-based API definition since OAS provides a common vocabulary. Multiple teams can work in parallel since OAS enables a shared understanding of the APIs. Downstream service integration, continuous delivery and application security are further areas improved by OAS.
Because OAS is machine-readable, many tools exist to automatically validate, implement, test, mock or document APIs. Errors can be caught early even before any code is written. Moreover, client and server implementations can be generated automatically. This is commonly called the API-first approach whereby APIs are defined first. This is contrary to the traditional code-first approach.
Could you share some case studies of OpenAPI?
Two places where OAS has become important are eCommerce platforms (eg. eBay) and the media industry (eg. Twitter). This has led to faster innovation. In banking, OAS has improved API security. At eBay, a transformer service enabled their customers to migrate from legacy contracts to OpenAPI contracts.
One eCommerce company migrated from a monolithic to a microservices architecture. OAS enabled them to generate API mocks from the API specifications and conduct many API acceptance tests. As a result, fewer end-to-end tests sufficed. In another company, API mocks served as reference for real implementations.
OAS integrates with and helps in CI/CD pipelines. For example, changes to the API specification can be automatically validated using GitHub Actions. If the validation succeeds, the pull request can be automatically merged.
An API specification in OAS can be defined by someone and implemented by someone else. For example, 3GPP defined the 5G Core Network APIs using OAS. These APIs will then be implemented by various industry vendors. Network elements can come from different vendors and yet interwork more easily. Off-the-shelf tools have been used to test implementations and discover vulnerabilities.
Could you give a technical overview of the OpenAPI Specification?
The document has a hierarchical structure starting from a root object called OpenAPI Object. Fields of this object are
externalDocs. At least one of
webhooksmust be present. All field names (at the root level or otherwise) are case sensitive unless otherwise stated. Fields are either fixed or patterned with regex. At any level, the specification can be extended with a patterned field that starts with
Data types in OAS are based on JSON Schema Specification. Examples include
string. OAS extends some of these with additional formats. Where
descriptionfield is used, it can be formatted with CommonMark markdown.
Could you describe the root-level fields of the OpenAPI Specification?
openapi: Specifies the OAS version number. This is a string of the form major.minor.patch.
info: Contains metadata on the API. Its fields include
jsonSchemaDialect: Sets the default dialect such as JSON Schema 2020-12.
servers: One or more Server Objects, each containing at least a URL. If omitted, defaults to a Server Object with URL
paths: One or more Path Objects. Each Path Object represents an API endpoint along with operations permitted on it.
webhooks: Webhooks are called by the API provider and may be implement by the consumer.
components: Contains all reusable objects. Definitions here are generally referenced (using
$ref) elsewhere in the document.
security: Specifies security mechanisms across the API but individual operations can override this. Reuses
securitySchemesfrom Components Object.
tags: Tags provide a way to organize operations on endpoints. Operations may be defined without tags or use tags not defined at the root level.
externalDocs: One or more URLs to external documentation.
How can API endpoints be specified in OpenAPI?
In OAS, API endpoints are called Paths. Each Path Object is an endpoint and must start with
/character. This is appended to a server URL to obtain a full endpoint URL. RESTful HTTP methods (get, post, delete, etc.) are defined as Operation Objects within a Path Item Object.
Each Operation Object has the field
operationIdthat's case sensitive and must be unique. The Operation Object also includes
requestBodythat conforms to HTTP 1.1 specification RFC7231. The field
responsesincludes a list of possible responses to the operation's request.
A Response Object is associated with an HTTP status code (200, 404, etc.) or
200status response is usually accompanied by the
contentfield that can define multiple Media Type Objects. For example, the API can define response content for both
descriptionfield of a Response Object is mandatory and is meant to give API consumers a useful message to complement the HTTP status code.
What tools are available within the OpenAPI ecosystem?
The company SmartBear continues to market products under the name of Swagger. Its online Swagger Editor is a useful tool to write API specification. It comes with an example called Petstore. The editor validates the specification and updates the documentation almost in real time. Developers can make API calls from the browser provided there's a hosted server implementation of the API. The editor's menu also has links to generate client and server code.
OpenAPI.Tools has a curated list of many tools that work with OAS. There are tools that take code and generate OAS; turn OAS into client SDKs, server or mock server implementations; generate documentation; validate data; exercise requests and validate the responses; offer user-friendly GUIs for editing/viewing OAS; and more. If writing in JSON or YAML is not preferred, Domain-Specific Languages (DSLs) are also available. CUE is an example.
The OAI maintains another list of OpenAPI tools.
What are some best practices when using OpenAPI?
Beyond OpenAPI, many of the best practices we mention here are applicable for general API design. Developers should adopt an API-first approach rather than code-first approach. This helps multiple teams to work in parallel and efficiently, particularly when their apps are composed of microservices.
Both producers and consumers must get involved. In fact, APIs should be consumer-driven rather than producers defining them from just the data model. This can be extended to consumer-driven contract testing. This can catch breaking changes early.
Adopt a style guide for your APIs. This could describe the naming convention such as using lowercase for server URLs or kebab-case for paths. This could prohibit using HTTP method names in paths. In any case, all these rules can be specified formally and used during validation.
What are some limitations or criticisms of OpenAPI?
In November 2021, four years after OAS 3.0's release, it was observed that many APIs were still using Swagger 2.0. Many tools that supported Swagger 2.0 have not migrated to the newer specification. This has led developers to continue with the older specification. The name change has also caused confusion. Swagger UI still exists and its only the Swagger Specification that has become OAS.
OAS requires some learning curve and adjustments to workflows. For example, end-to-end testing must make way to consumer-driven contract testing. In one case study, many developers in the team didn't understand the new workflows even 12 months after the change.
There's a danger that developers might treat OAS as a magic bullet. OAS is not a shortcut to understanding an API. Techniques such as design thinking and domain-driven design are still relevant in creating great APIs.
SmartBear and a few other companies announce the formation of the OpenAPI Initiative (OAI). It's formed as an open source project under the Linux Foundation. In December, the Swagger Specification is donated to the OAI. The idea is to standardize and bring formalism to how APIs are described. While Swagger, RAML and API Blueprint are available to describe APIs, OAI aims to bring out a single open specification that covers all use cases.
OpenAPI Specification 3.0.0 is released, the first release of the specification from the OAI. Version identifier uses semantic versioning. Multiple servers (aliases) are supported but can be overridden by a Path Item Object. Reusable definitions are organized under the Components Object. Parameters can be complex types. Increased reusability, content negotiation, enhanced security, updated parameters, improved examples, links, and callback descriptions are some features this release brings.
At Vancouver, Canada, the first API Specifications Conference (ASC) is organized by the OpenAPI Initiative. This conference has its origins in APIStrat, an API conference organized for many years by 3Scale. In 2017 and 2018, the OpenAPI Initiative hosted APIStrat that now becomes ASC. ASC welcomes participation from other communities (AsyncAPI, gRPC, GraphQL, OData, etc.).
Postman publishes an analysis of nearly 200,000 OpenAPI documents downloaded from various sources. Most documents in this study use the older 2.0 specifications. They find that most of them don't include license information. About 21% fail validation. About 2% include a
/status endpoint while 4% include a
/healthcheck endpoint. HTTP methods GET (44%), POST (27%) and PUT (15%) are common.
- Ali, N. 2022. "Consistent API URLs with OpenAPI and Style Guides." Blog, Stoplight, May 31. Accessed 2022-10-29.
- Banerjee, S. 2018. "OpenAPI–An eBay Perspective." Tech, eBay, February 27. Accessed 2022-10-29.
- Bhattacharjee, A. 2020. "Design Strategy for APIs." UX Planet, October 23. Accessed 2022-11-01.
- Brown, K. 2022. "Apply Domain-Driven Design to microservices architecture." IBM Garage Methodology, IBM. Accessed 2022-11-02.
- Bulaty, W. 2022. "Three case studies on API-first Development and Consumer-Driven Contracts." Blog, on LinkedIn, January 20. Accessed 2022-10-29.
- Desrosiers, J. 2021. "Validating OpenAPI and JSON Schema." Blog, JSON Schema, December 8. Accessed 2022-11-01.
- Dudek, S. 2021. "Intruding 5G SA core networks from outside and inside." Blog, Penthertz, December 20. Accessed 2022-11-01.
- Gorej, Vladimir. 2021. "How to validate OpenAPI definitions in Swagger Editor using GitHub Actions." Blog, Swagger, March 25. Accessed 2022-10-29.
- Lange, K. 2019. "OpenAPI and JSON Schema: When to Use Which." Blog, Stoplight, October 16. Accessed 2022-10-30.
- Lauret, Arnaud. 2021. "We need to talk: OpenAPI 3 is 4 years old, but Swagger 2 is still predominant." API Handyman, November 10. Accessed 2022-10-29.
- Lauret, Arnaud. 2022. "OpenAPI Map." API Handyman. Accessed 2022-11-01.
- Louvel, J. 2016. "Interview with Tony Tam on the Open API Initiative and Latest Swagger News." InfoQ, January 7. Accessed 2022-10-30.
- Mendoza, M. 2020. "How Businesses Can Benefit from OpenAPI Specification." Blog, AltexSoft, July 14. Accessed 2022-10-29.
- Miller, D. 2016. "TDC: Structural Improvements: explaining the 3.0 spec, part 2." Blog, OpenAPI Initiative, October 3. Accessed 2022-10-29.
- OpenAPI Docs. 2022a. "API Endpoints." The OpenAPI Specification Explained, OpenAPI Initiative. Accessed 2022-10-29.
- OpenAPI Initiative. 2019. "Introducing ASC, the API Specifications Conference." Blog, OpenAPI Initiative, May 8. Accessed 2022-10-30.
- OpenAPI Initiative. 2021a. "Releases." OAI/OpenAPI-Specification, on GitHub, February 17. Accessed 2022-10-29.
- OpenAPI Initiative. 2021b. "OpenAPI Specification v3.1.0." OpenAPI Initiative, The Linux Foundation, February 15. Accessed 2022-10-29.
- OpenAPI Initiative. 2022. "FAQ." OpenAPI Initiative, The Linux Foundation, October 22. Accessed 2022-10-29.
- OpenAPI.Tools. 2022. "Homepage." OpenAPI.Tools, APIs You Won't Hate. Accessed 2022-11-01.
- Pinkham, Ryan. 2018. "A Guide to What’s New in OpenAPI 3.0." Blog, Swagger, April 2. Accessed 2022-10-29.
- Ralphson, Mike. 2021. "What We Learned from 200,000 OpenAPI Files." Blog, Postman, August 23. Accessed 2022-10-29.
- Stoplight. 2022. "What is OpenAPI? OpenAPI Definition & OpenAPI Standards." Stoplight. Accessed 2022-10-29.
- Swagger. 2022. "Editor." Swagger. Accessed 2022-11-01.
- Vasudevan, Keshav. 2018. "The Benefits of OpenAPI-Driven API Development." Blog, Swagger, March 15. Accessed 2022-10-29.
- Wikipedia. 2022. "OpenAPI Specification." Wikipedia, October 20. Accessed 2022-10-29.
- de Montcheuil, Yves. 2015. "In 2016, the need for an API meta-language will crystallize." InfoWorld, December 15. Accessed 2022-10-30.