Upon seeing the headline to this article, API experts will likely scratch their heads wondering why the journal of the API economy (ProgrammableWeb) would indirectly suggest that REST and Swagger are comparable to the point that an article about their differences is warranted. Have we lost our marbles?
This article is actually based on emails that we get from readers who are just breaking into the field of application programming interfaces or APIs (see also: What Are APIs and How Do They Work?). As you can imagine, for people who are new to APIs, there’s a lot of popular domain-specific terminology like “REST” and “Swagger” that can be confusing to the point that newcomers might perceive two phrases as being alternatives to one another when in reality, they are no such thing. As questions go, “What’s the difference between REST and Swagger?” is high on the list of questions that have been asked over the years. So, I figured it’s about time that I just publish an answer as a part of API University.
“Swagger” is Obsolete
First, before we get into the differences between REST and Swagger, it’s important to note that “Swagger,” as it applies to APIs that newcomers might think about publishing, is obsolete. It is the ancestor to a more current technology called the OpenAPI Specification (OAS). In other words, Swagger is essentially an old version of OAS. If you’re new to APIs and thinking about building and publishing new APIs, knowing Swagger’s role in the history of OAS is nice to know, but not a blocker to anything you should be doing.
About the only relevance that Swagger should have to your work going forward is how some tools for working with APIs claim support for Swagger when they really mean OAS. However, keep in mind that some vendors have been slow to update their software and so when they say their tools support Swagger, it actually means they haven’t updated their wares since the ancestral days of Swagger and therefore do not support the newer OAS. It takes a keen eye to spot and understand this nuance.
So, What is the Difference Between REST and OAS?
REST (Representational State Transfer) is a network-based software architecture that many networkable APIs — particularly Web APIs — conform to. The REST architectural style is defined in Chapter 5 of Roy Fielding’s dissertation on Architectural Styles and the Design of Network-based Software Architectures.
Over the history of computing, there have been a great many architectural styles of APIs and not all of them are networkable. In other words, whereas an API that depends on network-based software architecture might be thought of as a “networkable API,” there are plenty of other APIs whose architecture is non-networkable. For example, the operating systems like Windows, MacOS, Android, and iOS that run most modern personal computers and smartphones have an API for creating an onscreen window with specific dimensions (height and width) and characteristics (ie: colors). When software interacts with this API (the equivalent of one piece of software “talking” to another), that interaction generally stays within the confines of a single system.
In contrast, when an API is networkable (as is the case with REST APIs), software on one computer can talk to software on another computer over a network. That network could be the local area network that belongs to a business, or the home network in your house, or the Internet.
One very important thing to realize is that there is a long and ongoing history of networkable software architecture. REST is neither the first such architectural style, nor will it be the last. But there are important differences between all of the various styles with newer styles often improving in some way on the older ones.
When one piece of software talks to another over a network, some highly nuanced specifics govern how that conversation gets onto the network, how the conversants understand one another, and how the conversation is ordered and timed. Those nuanced specifics are what set one networkable API architecture apart from another. Versus older architectural styles, the specifics of the REST architectural style — their simplicity, their elegance, and their ability to rely on existing standard networking protocols like the one that makes the World Wide Web work (aka the “Hypertext Transfer Protocol” or “HTTP”) — have made it one of the more enduring and popular architectural styles for networkable APIs. This is one reason that REST APIs are sometimes also called “Web APIs.” Although it is not a requirement, most REST APIs rely on HTTP (the Web’s official protocol) to perform their magic.
APIs that conform to the REST architectural style are also often characterized as being “RESTful.” While this article deliberately stays away from the gory details regarding all the nuanced specifics of the REST architectural style (you can read Fielding’s dissertation for that!), REST purists like to debate the extent to which some APIs truly qualify as RESTful APIs and others do not. In the bigger scheme of things and the longer arc of the API economy, the importance of this debate is over-rated.
Unlike REST, OAS (previously “Swagger”) is not an architectural style. OAS is a de facto standard way to use text to describe the developer-accessible features of a REST API. For example, if the postal code of a customer can be retrieved through an REST API, an OAS-compliant description of that API will show developers how exactly to “call” the API in a way that it properly responds with the zip code that was requested. So, in a nutshell, OAS says “if you’re going to describe all of the specific facilities of an API with text, this is how you should do it.”
The net result is that OAS is considered to be a standard specification for describing REST APIs. One of the great benefits of having such a standard means for describing REST APIs is that it is not just intended for usage by developers to understand how an API works. It is also intended for usage by other software. For example, there are a variety of solutions on the market for testing APIs that can crawl the OAS-compliant description of an API and automatically create a custom suite of API tests for validating the integrity of the API (for more on such tools, see Why and How to Test and Monitor Your APIs). There are also many solutions on the market that can read the same OAS-compliant description and automatically generate developer-friendly API documentation. The list of the various artifacts that can be automatically generated from an OAS-compliant description goes on and will not be covered here in detail.
So, OAS and its predecessor Swagger are highly complimentary to the REST architectural style (which suggests the opposite of the highly loaded question “What’s the difference between REST and Swagger?”). Further to that point: in the same way that OAS is complimentary to the REST architectural style, other API description specifications like the Web Services Description Language (WSDL) are complimentary to other older but still deeply entrenched networkable API architectures like “remote procedure call” or “RPC.”
The most important takeaway from that point is how, throughout the history of computing, there has been an ongoing evolution of architectural styles for APIs. While each has looked to improve on its predecessors, many of these styles have also involved a dedicated complimentary standard for describing the APIs that conform to those styles. For example, where as WSDL applies to RPC-style APIs and OAS applies to REST, two emergent architectural patterns — GraphQL from Facebook and gRPC from Google — both have their own standard means of description.