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:

<?xml version="1.0"?>

<application xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"

xsi:schemaLocation="http://wadl.dev.java.net/2009/02 wadl.xsd"

xmlns:tns="urn:yahoo:yn"

xmlns:xsd="http://www.w3.org/2001/XMLSchema"

xmlns:yn="urn:yahoo:yn"

xmlns:ya="urn:yahoo:api"

xmlns="http://wadl.dev.java.net/2009/02">

<include

href="NewsSearchResponse.xsd"/>

<include

href="Error.xsd"/>

</grammars>

<param name="appid" type="xsd:string"

style="query" required="true"/>

<param name="query" type="xsd:string"

style="query" required="true"/>

</param>

</param>

</request>

<representation mediaType="application/xml"

element="yn:ResultSet"/>

</response>

<representation mediaType="application/xml"

element="ya:Error"/>

</response>

</method>

</resource>

</resources>

</application>

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.

Example:

# 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: fett@intergalactic.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!