In this four part blog series we will delve into the realm of REST API specification standard called as Swagger or OpenAPI (http://swagger.io) 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 would like to take you on a journey back in time, to give you a background on how this specification came to be. 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, internet already understands : 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, developer community felt an increasing need to create standards for defining REST APIs. Any proposed standard had to keep 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 https://en.wikipedia.org/wiki/Overview_of_RESTful_API_Description_Languages. We will talk about some important ones: First attempt for a REST specification standard came from Marc Hadley at Sun Microsystems. Marc Hadley is also credited for creating the Jersey framework. The specification was called WADL – Web API Description Language https://www.w3.org/Submission/wadl/ . It relied on SOAP WSDL like XML with reliance on XSD to describe API endpoints Sample WADL description for the Yahoo News Search application (https://www.w3.org/Submission/wadl/):

<?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">

    <grammars>

     <include

       href="NewsSearchResponse.xsd"/>

     <include

       href="Error.xsd"/>

   </grammars>

   <resources base="http://api.search.yahoo.com/NewsSearchService/V1/">

     <resource path="newsSearch">

       <method name="GET" id="search">

         <request>

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

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

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

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

           <param name="type" style="query" default="all">

             <option value="all"/>

             <option value="any"/>

             <option value="phrase"/>

           </param>

           <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">

             <option value="rank"/>

             <option value="date"/>

           </param>

           <param name="language" style="query" type="xsd:string"/>

         </request>

         <response status="200">

           <representation mediaType="application/xml"

             element="yn:ResultSet"/>

         </response>

         <response status="400">

           <representation mediaType="application/xml"

             element="ya:Error"/>

         </response>

       </method>

     </resource>

   </resources>

</application>

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 nonprofit 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 http://swagger.io/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 available at https://github.com/raml-apis and https://github.com/mulesoft/api-console/tree/master/dist/examples. 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 started to use it in their offerings.  In March 2015, SmartBear software acquired Swagger specification from Reverb technologies and eventually donated it to Linux foundation under the Open API Initiative. Swagger specification was rechristened as OpenAPI specification while SmartBear software continued to develop tools around OpenAPI under the Swagger project umbrella.  Apiary which lead the BluPrint initiative joined OpenAPI Initiative in 2016 while MuleSoft, creators of RAML joined OpenAPI initiative in 2017. This has resulted in OpenAPI Specification and Swagger gaining a lot of traction and marking an end of API Spec WARs. It is now time to move out of the History lesson and get our hands dirty by using Swagger for a sample set of REST APIs. See you there! References: http://swagger.io/mulesoft-joins-the-openapi-initiative/ http://swagger.io/specification/ https://apiblueprint.org/ http://raml.org/ http://apiux.com/2013/04/09/rest-metadata-formats/