Swagger Creator Wants to Build Better SOAP for Web APIs

During the recent GlueCon 2014 conference in Colorado, Tony Tam, the creator of Swagger and CEO of Reverb, gave a well attended talk on Swagger APIs for humans (and robots), where he announced the Swagger 2.0 Working Group and an early version of an online code editor offering a dynamic YAML to Swagger UI conversion.

InfoQ had a chance to speak with him during the conference to discuss those news and understand his views on competing web API languages such as RAML and API Blueprint, the need for client SDKs despite technical difficulties and his vision for Swagger future.

Swagger 2.0 Working Group announced

Tony is building a vendor neutral working group with a goal to define and release a version 2.0 of Swagger this summer, including out-of-the-box support for YAML syntax, additional metadata covering SLAs, vendor extensions and more. A new Swagger web site was made available to let interested parties join.

The Swagger 2.0 specification most likely won't be compatible with previous versions, but migration paths will be provided and the whole tool chain upgraded. In addition, a formal JSON Schema will reduce compatibility issues experienced with previous versions of Swagger. Reverb has started to collaborate recently on this front with Tatu Saloranta, the creator of Jackson, the popular JSON library for Java.

Another goal is to provide separate Java and Scala tool chains to better integrate with each programming languages, all based on Mustache code templates. This tool chain will also be optimized to consume less memory and CPU resources. Tony also wants "to make it as easy as possible to write and deploy the Swagger based web APIs, using cloud platforms such as APISpark, AWS, Heroku and so on."

The collaborative work among official members will take place in a Google Group and a GitHub repository. Individual members will be able to submit pull requests as well. Several companies have already joined Reverb and founding member Apigee, including 3Scale, SmartBear and Restlet.

During his talk, Tony also launched an online Swagger editor preview which lets developers write Swagger definitions in YAML (based on version 1.2 of Swagger specifications) and see a dynamically updated Swagger UI.

This component was developed based on AngularJS and Ace code editor, and contributed to the Swagger project by the API management company Apigee. This editor will also be capable of generating server skeletons and client SDKs, all online.

The current state of the Swagger project

Last March 2014, version 1.2 of the Swagger specifications was released and Tony claims that Swagger has the largest and most active community today, with external contributions now exceeding those made by Reverb. Also, Tony points out that, "Swagger is used to do ‘non-hello world' deployments that scale, with an estimated 10 000 production deployments and around 500 000 downloads so far, just for 2014."

According to Tony, Swagger is trying to solve some of the same problems as RAML, WADL or API Blueprint, with a different approach. However, he considers that "the technical format doesn't matter as much as the underlying metamodel. Swagger JSON can, for example, be automatically converted into YAML and the other way around." However, he thinks that "wiki/markdown formats", as used by API Blueprint, "are nice for humans but more difficult to process for machines, and that we need to support both types of users."

During his "API Strategy & Practice" lightning talk at GlueCon 2014, Tony explained that adoption among API developers will make a true difference and set the de facto standard. Jakub Nesetril, the creator of API Blueprint and CEO of Apiary who was also present, later acknowledged in a workshop that Swagger had an edge in term of adoption. A recent InfoQ survey on API documentation also placed Swagger as the most popular solution.

In addition, Tony underlines that Swagger is "the only solution that is open source (Apache 2.0 license) around all aspects, including the specification and all the tooling, and is truly vendor neutral. Swagger is trying to enable connectivity between devices, applications, and services, not own your entire stack with a services play."

Client SDKs are a necessary evil

Earlier at GlueCon, John Sheehan (CEO of RunScope, a web API tooling vendor) gave a talk highlighting the common issues with client SDKs:

1. SDK versions not evolving at the same pace as the API versions.
2. Heterogeneous SDKs relying on different versions of the same dependencies such as JSON or HTTP libraries.
3. Building SDKs for major programming languages is hard, even for bigger players.

As an indirect reply, Tony agreed that "client SDKs are really hard to maintain, you need language experts to write the client SDK templates otherwise it indeed doesn't work and you can't ask your users to write the client SDKs."

However, he thinks that they are nonetheless necessary and gives the example of "AWS [who] does a good job at abstracting away the complexity of their web API (they hide it), but that doesn't work/scale for smaller companies." He also mentions the Reverb for iPhone app (also launched at Gluecon) that uses an auto-generated Objective-C client SDK and says that "building it by hand would have taken literally weeks to months, and slowed the entire iteration process for the API server."

Beyond SOAP and HTTP/1.1

Tony further thinks that "building blocks are services, the software is an aggregator, and Swagger is helping to realize this vision." He also thinks that "SOAP never caught on because many popular languages were left out such as Ruby and Python." In addition, he thinks that "vendor contamination can destroy the adoption of an API specification, citing CORBA as a massive failure due to vendor-specific functionality that broke the spirit."

On the contrary, he points out that Swagger is "framework, language and deployment agnostic." He also thinks that "in the long term, HTTP will be replaced with some other protocols, but no matter what you will use, you still need to describe the services." He describes HTTP/1.1 as "too chatty, with too much overhead and how you would probably never use your database over HTTP when a full-duplex, binary connection is available."

He mentioned an existing Swagger implementation on top of WebSocket or the existence of binary protocols such as Avro, Thrift or ProtoBuf. It will be interesting to see if the upcoming HTTP/2.0 protocol, based on a Google SPDY experiment and including binary serialization and full duplex mode, will work better for performance sensitive web APIs.

In any case, Swagger 2.0 aims to provide a stable API description language that will work equally well even if the underlying protocol used is evolving, in some way a better SOAP for web APIs. Do you think that the Swagger project will be able to deliver on those new ideas? Also, how do you think competing web API languages will react?

Disclaimer: the author of this article works for Restlet, a web API platform provider supporting several web API languages including Swagger.