OpenAPI Specification

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.

OAS is vendor-neutral and maintained by the OpenAPI Initiative (OAI) under the Linux Foundation. The specification document uses Apache License V2.0.

Discussion

  • What are the benefits of adopting the OpenAPI Specification?
    Benefits of adopting the OpenAPI Specification. Source: Vasudevan 2018.
    Benefits of adopting the OpenAPI Specification. Source: Vasudevan 2018.

    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.

    JSON Schema can describe only the data model. OAS can describe the entire API while also being compatible with JSON Schema.

    OAS is openly developed and released under an open license. It has wide industry support with more than 40 members at the OAI. It's got good documentation and support.

  • 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?
    Visualizing a part of OpenAPI v3.0.1. Source: Lauret 2022.
    Visualizing a part of OpenAPI v3.0.1. Source: Lauret 2022.

    An OpenAPI Document can be in either JSON or YAML format. If an API is specified in multiple files, it's recommended that the root file is named openapi.json or openapi.yaml.

    The document has a hierarchical structure starting from a root object called OpenAPI Object. Fields of this object are openapi, info, jsonSchemaDialect, servers, paths, webhooks, components, security, tags and externalDocs. At least one of paths, components or webhooks must 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 x-.

    Data types in OAS are based on JSON Schema Specification. Examples include integer, number and string. OAS extends some of these with additional formats. Where description field is used, it can be formatted with CommonMark markdown.

  • Could you describe the root-level fields of the OpenAPI Specification?

    We describe briefly the following root-level fields:

    • 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 title, summary, description, termsOfService, license, etc.
    • 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 securitySchemes from 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?
    OpenAPI's paths object. Source: OpenAPI Docs 2022a.
    OpenAPI's paths object. Source: OpenAPI Docs 2022a.

    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 operationId that's case sensitive and must be unique. The Operation Object also includes requestBody that conforms to HTTP 1.1 specification RFC7231. The field responses includes a list of possible responses to the operation's request.

    A Response Object is associated with an HTTP status code (200, 404, etc.) or default. A 200 status response is usually accompanied by the content field that can define multiple Media Type Objects. For example, the API can define response content for both application/json and application/xml. The description field 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?
    Swagger Editor showing YAML source (left) and documentation (right). Source: Swagger 2022.
    Swagger Editor showing YAML source (left) and documentation (right). Source: Swagger 2022.

    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.

    Beginners can study OpenAPI examples published by well-known organizations. Publicly shared OpenAPI documents from SendGrid and GitHub are worth studying.

  • 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.

Milestones

Aug
2011

Swagger 1.0 is released. Tony Tam started working on Swagger back in 2010 while at Wordnik.

Sep
2014

Swagger 2.0 is released.

Mar
2015

SmartBear Software acquires the Swagger Specification.

Nov
2015
Logo of the OpenAPI Initiative. Source: OpenAPI Initiative 2022.
Logo of the OpenAPI Initiative. Source: OpenAPI Initiative 2022.

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.

Jul
2017
OAS 3.0 compared to Swagger 2.0. Source: Adapted from Miller 2016.
OAS 3.0 compared to Swagger 2.0. Source: Adapted from Miller 2016.

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.

Oct
2019

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.).

Feb
2021

OpenAPI Specification 3.1.0 is released. Top-level field webhooks is added. An OpenAPI document must have at least one of the top-level fields paths, components or webhooks. The specification is now fully compatible with JSON Schema 2020-12 draft.

Aug
2021

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 /ready or /healthcheck endpoint. HTTP methods GET (44%), POST (27%) and PUT (15%) are common.

References

  1. Ali, N. 2022. "Consistent API URLs with OpenAPI and Style Guides." Blog, Stoplight, May 31. Accessed 2022-10-29.
  2. Banerjee, S. 2018. "OpenAPI–An eBay Perspective." Tech, eBay, February 27. Accessed 2022-10-29.
  3. Bhattacharjee, A. 2020. "Design Strategy for APIs." UX Planet, October 23. Accessed 2022-11-01.
  4. Brown, K. 2022. "Apply Domain-Driven Design to microservices architecture." IBM Garage Methodology, IBM. Accessed 2022-11-02.
  5. Bulaty, W. 2022. "Three case studies on API-first Development and Consumer-Driven Contracts." Blog, on LinkedIn, January 20. Accessed 2022-10-29.
  6. Desrosiers, J. 2021. "Validating OpenAPI and JSON Schema." Blog, JSON Schema, December 8. Accessed 2022-11-01.
  7. Dudek, S. 2021. "Intruding 5G SA core networks from outside and inside." Blog, Penthertz, December 20. Accessed 2022-11-01.
  8. Gorej, Vladimir. 2021. "How to validate OpenAPI definitions in Swagger Editor using GitHub Actions." Blog, Swagger, March 25. Accessed 2022-10-29.
  9. Lange, K. 2019. "OpenAPI and JSON Schema: When to Use Which." Blog, Stoplight, October 16. Accessed 2022-10-30.
  10. 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.
  11. Lauret, Arnaud. 2022. "OpenAPI Map." API Handyman. Accessed 2022-11-01.
  12. Louvel, J. 2016. "Interview with Tony Tam on the Open API Initiative and Latest Swagger News." InfoQ, January 7. Accessed 2022-10-30.
  13. Mendoza, M. 2020. "How Businesses Can Benefit from OpenAPI Specification." Blog, AltexSoft, July 14. Accessed 2022-10-29.
  14. Miller, D. 2016. "TDC: Structural Improvements: explaining the 3.0 spec, part 2." Blog, OpenAPI Initiative, October 3. Accessed 2022-10-29.
  15. OpenAPI Docs. 2022a. "API Endpoints." The OpenAPI Specification Explained, OpenAPI Initiative. Accessed 2022-10-29.
  16. OpenAPI Initiative. 2019. "Introducing ASC, the API Specifications Conference." Blog, OpenAPI Initiative, May 8. Accessed 2022-10-30.
  17. OpenAPI Initiative. 2021a. "Releases." OAI/OpenAPI-Specification, on GitHub, February 17. Accessed 2022-10-29.
  18. OpenAPI Initiative. 2021b. "OpenAPI Specification v3.1.0." OpenAPI Initiative, The Linux Foundation, February 15. Accessed 2022-10-29.
  19. OpenAPI Initiative. 2022. "FAQ." OpenAPI Initiative, The Linux Foundation, October 22. Accessed 2022-10-29.
  20. OpenAPI.Tools. 2022. "Homepage." OpenAPI.Tools, APIs You Won't Hate. Accessed 2022-11-01.
  21. Pinkham, Ryan. 2018. "A Guide to What’s New in OpenAPI 3.0." Blog, Swagger, April 2. Accessed 2022-10-29.
  22. Ralphson, Mike. 2021. "What We Learned from 200,000 OpenAPI Files." Blog, Postman, August 23. Accessed 2022-10-29.
  23. Stoplight. 2022. "What is OpenAPI? OpenAPI Definition & OpenAPI Standards." Stoplight. Accessed 2022-10-29.
  24. Swagger. 2022. "Editor." Swagger. Accessed 2022-11-01.
  25. Vasudevan, Keshav. 2018. "The Benefits of OpenAPI-Driven API Development." Blog, Swagger, March 15. Accessed 2022-10-29.
  26. Wikipedia. 2022. "OpenAPI Specification." Wikipedia, October 20. Accessed 2022-10-29.
  27. de Montcheuil, Yves. 2015. "In 2016, the need for an API meta-language will crystallize." InfoWorld, December 15. Accessed 2022-10-30.

Further Reading

  1. The OpenAPI Specification Explained
  2. The OpenAPI Specification v3.1.0
  3. OpenAPI Map @ API Handyman
  4. The OpenAPI Initiative
  5. The OpenAPI Specification Repository on GitHub
  6. OpenAPI.Tools

Article Stats

Author-wise Stats for Article Edits

Author
No. of Edits
No. of Chats
DevCoins
Avatar of user arvindpdmn arvindpdmn
5
0
1582
DevCoins due to articles, chats, their likes and article hits are included.
1855
Words
1
Authors
5
Edits
0
Chats
2
Likes
3828
Hits

Cite As

Devopedia. 2022. "OpenAPI Specification." Version 5, November 2. Accessed 2024-06-25. https://devopedia.org/openapi-specification
Contributed by
1 author

Last updated on
2022-11-02 04:15:27
design tools api

See Also