Swagger Creator Wants to Build Better SOAP for Web APIs

by Jerome Louvel on Jun 04, 2014 |


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?


Hello stranger!


Get the most out of the InfoQ experience.

Tell us what you think


Email me replies to any of my messages in this thread

"SOAP never caught on" by Jean-Jacques Dubray

really? in the API world, maybe, but in the enterprise, it's nearly 100% SOAP today. So I am not sure what this "never caught on" is about?

I am not a big fan of WS-*, never have, never will be, but the fact and the matter that Swagger exists is a huge validation for what WS-* was trying to be.

... and, transport independence? what a novel idea? why nobody thought of that before?

Re: "SOAP never caught on" by Tony Tam

Outside of the enterprise, most modern apis are not SOAP, they are REST, and once outside of .net & java servers, SOAP services out there approaches zero relevance.

Documenting web service interfaces is not a new idea! Being applied generally to REST has been effective, hence the traction independent of language.

Re: "SOAP never caught on" by Jean-Jacques Dubray

Tony, I like what you do and Swagger makes lots of sense, but I don't think it's fair or constructive to speak like you do. In the end we are just talking about encoding the some semantics in an HTTP request, i.e. a plain text string. Saying that one encoding is better than an other, is as silly as saying spaghetti are much better than tortellini. In the end, it's pretty much a question of taste -> I like JSON over XML, tastes much better, but when it comes to transporting data, it's hard to find a meaningful difference.

In the end REST is reinventing the wheel and it took 7+ years to do so (generated clients, schemas, contract definitions, ...). For some reason people sold REST to the industry because supposedly all this ceremony was not needed...


Perhaps we could stop this rhetoric of us vs them, for a change, and focus on the real questions, including one of them that's still unsolved yet essential ... versioning. One could actually argue that there is a 9th Fallacy to distributed computing: "Code never gets updated"

Re: "SOAP never caught on" by Tony Tam

Ahh I believe we have a misunderstanding. I don't mind JSON vs XML, (and I love both spaghetti and tortellini), the goal is connectivity and understanding. So my goal isn't to say that a particular effort was a waste of time. On the contrary, there are many good things that have come out of previous efforts, and one thing that will help us all immensely is supporting descriptions equally across languages, frameworks, and deployment techniques. That's really what I'm focused on

Really "a better SOAP for web APIs"? by Tammo van Lessen

SOAP is a data protocol for messaging. I think the author meant WSDL, which is the interface description language in the WS-* world. This is what swagger aims to better at, no?

Re: Really "a better SOAP for web APIs"? by Jerome Louvel

Even though Swagger as a framework is indeed more of an alternative to WSDL for web APIs, its creator clearly went beyond this technical aspect by sharing his vision, especially at the end of the interview when he puts Swagger into perspective with HTTP/1.1, WebSockets, CORBA and SOAP initatives.


Email me replies to any of my messages in this thread


Email me replies to any of my messages in this thread

7 Discuss
General Feedback
Privacy policy