Swagger Introduction - Specification for Describing RESTful APIs
In this four-part blog series we will delve into the realm of REST API specification standard called as Swagger or OpenAPI.
What is Swagger?
Swagger or OpenAPI is a specification for describing RESTful APIs in an implementation language-agnostic manner. The resulting definition is human- and machine-readable. This makes it easy to build tools to generate documentation, client, and server stubs in various languages. Testing utilities can also use the resulting definition to help API consumers get a ‘feel’ of the REST end points before integrating them with other applications. In this first part of the series, we shall take you on a journey back in time, to give you a background on how this specification came to be.
Background of Swagger
Until the year 2000, SOAP, XML-RPC or CORBA were the go-to options to implement web services. These options were complex to build, use, and debug. All this changed after Roy Fielding and his colleagues proposed REST or Representational State Transfer as a set of architectural principles, properties, and constraints, to provide interoperability between systems communicating over the Internet. The idea was to treat business entities as resources on the World Wide Web which can be accessed and manipulated using a protocol that the internet already understood – HTTP.
As adoption of REST gained momentum with eBay, Amazon and Flickr leading the way by exposing REST APIs with online documentation to provide a programmatic way to access their internal data, the developer community felt an increasing need to create standards for defining REST APIs. Any proposed standard had to keep in mind the following goals:
- Describe resource paths
- HTTP methods used to access the resources
- Parameters needed to be supplied to each method (HTTP headers, POST body content, query parameters)
- Multiple data formats (JSON, XML) for incoming and outgoing payloads
- Status and error codes
- Description of all these to generate human readable documentation
An exhaustive list of RESTful API Description Languages/Standards can be seen here.
The First REST Specification Standard
The first attempt for a REST specification standard came from Marc Hadley at Sun Microsystems in 2009. (Marc Hadley is also credited for creating the Jersey framework.) The specification was called WADL – Web API Description Language. It relied on SOAP WSDL-like XML with reliance on XSD to describe API endpoints.
Sample WADL description for the Yahoo News Search application:
<method name="GET" id="search">
<param name="appid" type="xsd:string"
<param name="query" type="xsd:string"
<param name="type" style="query" default="all">
<param name="results" style="query" type="xsd:int" default="10"/>
<param name="start" style="query" type="xsd:int" default="1"/>
<param name="sort" style="query" default="rank">
<param name="language" style="query" type="xsd:string"/>
From WADL to Swagger
The development of WADL lost steam due to its reliance on XML/XSD and takeover of Sun Microsystems by Oracle. In the year 2010, Tony Tam from Reverb created an open-source project to generate interactive API documentation and client SDK generation while working on APIs and tools for Wordnik, a non-profit organization that provides online English dictionary and thesaurus services. It used JSON sent from the API server to provide API documentation in HTML form. This project is now known as Swagger UI.
Around 2013, there were three competing API description languages
- Swagger: Used JSON to describe API contracts
- API BluePrint: Launched by Apiary (Now part of Oracle), It used Markdown style format and provided support for API design, documentation, and mock testing. The format is document-centric.
# Data Structures
## Blog Post (object)
+ id: 42 (number, required)
+ text: Hello World (string)
+ author (Author) - Author of the blog post.
## Author (object)
+ name: Boba Fett
+ email: email@example.com
# Blog Posts [/posts]
## Retrieve All Posts [GET]
+ Response 200 (application/json)
+ Attributes (array[Blog Post])
- RAML: Which stands for RESTful API Modelling Language, uses YAML. Lots of interesting examples are available at here and here. Its design goal was to provide an ability to model large number of APIs.
Swagger gained a lot of community adoption, and many API providers began to use it in their offerings. In March 2015, SmartBear software acquired Swagger specification from Reverb technologies and eventually donated it to the Linux foundation under the OpenAPI Initiative. The Swagger specification was rechristened as OpenAPI specification while SmartBear software continued to develop tools around OpenAPI under the Swagger project umbrella. Apiary which led the BluePrint initiative joined the OpenAPI Initiative in 2016 while MuleSoft, the creators of RAML, joined the OpenAPI initiative in 2017. This has resulted in OpenAPI Specification and Swagger gaining a lot of traction and marking an end to the API Spec wars.
It is now time to end our history lesson and get hands-on experience by using Swagger for a sample set of REST APIs. Come check out our next part of the series here!