APIs with Swagger : An Interview with Reverb’s Tony Tam

This series focuses on three key areas of "meta-language" for Web APIs: API Description, API Discovery, and API Profiles. You’ll see articles covering all three of these important trends as well as interviews with some of the key personalities in this fast-moving space.

Tony Tam is a hard man to pin down — as are all busy people. Probably best known as the force behind Swagger, one of the most popular Web API specification frameworks today, Tam is also the founder of Reverb, a content analysis and recommendation company. He helped co-found Wordnik, the world’s largest online English dictionary, and has been involved in several other ventures dating back to his college days at UC Santa Barbara and Santa Clara University. He even holds a patent on building user profiles based on content consumption. Now that Reverb has been acquired by NDN (newsinc.com), Tam is busy in his new role as VP of Emerging Technologies.

It’s been a busy time for the Swagger framework, too. After a flurry of activity from their open working group (started in May of 2014), Swagger 2.0 was officially released in September 2014. Our interview took place in March 2015, less than one year from the start of the 2.0 process and right after Reverb announced that the responsibility for leading the future of the Swagger specification would be handed over to SmartBear, the Massachusetts-based software tools company.

With all this recent activity still fresh in many people’s minds, I started our discussion with a look back to the start of the Swagger framework back in 2009.

Mike Amundsen: It might surprise people that the Swagger API framework was not initially created as a public project but was actually something done internally at Reverb (formerly Wordnik). Can you talk a bit about the earliest days of Swagger?

Tony Tam: Swagger started out as a project to solve real challenges that we were having at the time at Wordnik. We were producing REST APIs to be consumed by our paying customers. Internally, we built a single API interface to our system and wanted to grant permissions to each customer based on our agreement with them. That meant documenting only the operations that they had permission to use. We were also asked to provide native SDKs for them.

Mike: So this was your way of solving the problem of generating lots of custom interfaces and documentation?

Tony: Yes, and I really hate doing the same thing over-and-over. We had the idea to build a generalized JSON model of our REST API that reflected what the caller had permission to use. That became the input for our code generators. And a really clever developer in the office pointed out how we should use that for an interactive documentation UI. That became the Wordnik Developer site. The combination of those two became the idea behind what we later called Swagger.

Mike: So how did Swagger turn into the widely-used public tool so popular today?

Tony: After releasing the interactive UI to http://developer.wordnik.com, we had a whole bunch of interest in the project and eventually open sourced the UI, server integration, and code generator.

It’s roots are in solving real-world challenges. We have obviously evolved the project considerably from it’s humble beginnings but have stuck to some core ideas around defining a solid, predictable model of the API.

Mike: You started working on Swagger in 2009 and Swagger 2.0 was just released in the Fall of 2014. What was the driver for this upgrade and what changes were made to Swagger?

Tony: Well, after a few years you certainly learn what worked and what didn’t. There were some structural aspects which caused a lot of support issues, as well as getting better support for JSON schema that made sense to put into the Swagger specification. We also wanted to make the definition more concise and easier to author in modeling tools.

Mike: So, is "2.0" a breaking change for Swagger users?

Tony: We had released swagger 1.0, 1.1, and 1.2 over the last three years, each with minor improvements upon the original design. This time, we took the opportunity to make a larger change to the spec.

In all versions, however, we have gone to great lengths to make upgrades as easy as possible. Even with all the changes to Swagger 2.0, the server tooling, UI, and code generator templates are compatible. It’s usually just a dependency upgrade to move forward.

Mike: One of the features added in Swagger 2.0 was the ability to define extensions. Why was this added? What are some examples of how extensions have been leveraged by API developers?

Tony: A couple of drivers for this feature.

First, we don’t want to try to stuff every possible feature inside the specification itself. Early on, someone brought up embedding rate-limiting information into the spec. But it would be very difficult to generalize, and would pollute the spec over a feature that possibly many people wouldn’t care about.

Next, one thing we learned through the initial versions of Swagger is that it’s easy to write invalid specifications without a simple and robust validator. We chose to use JSON Schema validations, and even built it directly into Swagger-UI. It is an important part of the tooling to help developers write valid Swagger definitions.

Removing structural constraints from the spec AND having a robust validation tool would be very difficult. We chose to use an extension prefix to give flexibility in the spec so developers can make Swagger even more useful to them. Some extensions may be "promoted" into the next version of Swagger as they make sense.

Mike: The release of Swagger 2.0 seemed to include lots of voices from the community. That means lots of requests for changes and new features. How did you determine what changes went into 2.0?

Tony: The Swagger 2.0 specification contained everything that we thought made sense. It wasn’t driven by a timeline nor a feature set. We listened and received a ton of valuable advice. Ultimately we made decisions based on the core goals of the specification, rather than simply trying to solve everyone’s problems simultaneously. That would have ended with a big ball of mud.

Mike: One of the requested features that didn’t make it into 2.0 was adding support for hypermedia descriptions. But that issue in Github was closed with "not per design." It seems hypermedia is getting more play in API designs, too. Why do you think this didn’t make the 2.0 release? and do you think it might in the future?

Tony: Well that commit message says it all. Swagger isn’t intended for Hypermedia in this version. It may make sense at some point but support for Hypermedia doesn’t actually solve any of the current goals of Swagger. It could be a square peg / round hole problem but I’m not sure right now.

Mike: Although barely five years old, Swagger has a huge following among Web API developers. It seems to have a larger footprint than many other designs such as WSDL, WADL, AtomSvc, and others. Why do you think that is? What is is about Swagger that has helped it become so widespread?

Tony: I think there are some key drivers behind why Swagger has been successful. First, it simply solves common problems. How easily could you show your boss your API? How can you let a customer try it out? The Swagger UI has been instrumental in helping communicate what the API is, and how it works.

Next, the specification is simple enough that developers have written integrations across every modern programming language. Instead of, for example, Swagger Inc. being responsible for the entire toolchain, we have literally 10’s of thousands of developers writing different integrations. So coverage across different languages and frameworks is extremely important.

Finally, Swagger simply started out differently. It’s not popular because of a marketing campaign or flashy website covered with logos. It gained "grass-roots" traction from developers.

Mike: As of this writing, it seems the three most commonly-used API description frameworks in use today are Swagger, RAML, and Apiary Blueprint. How do you think Swagger stacks up against these other formats? What factors do you think API developers are using to select one format over another?

Tony: Well I can speak to a number of points. There are definitely differences in the capabilities of the specifications. It’s impossible to support all three specs in a lossless fashion—you can’t simply convert one to another. It’d be like offering a one-size-fits-all car cover to fit both your Porsche and motorhome.

Swagger has the most structure of the different description formats. In the core goals of Swagger is the ability to describe operations and models for strong-typed languages. That means we can provide enough metadata on the API to generate native C++ clients.

Mike: So, is Swagger an "opinionated" format — one that helps developers learn the ‘right way’ to create APIs?

Tony: Swagger does not impose a single workflow on a developer. It doesn’t require top-down or bottom-up coding styles. This can be a decision point with the other formats as they’re quite opinionated on workflow.

I think most developers aren’t going to choose a description format without considering the programming language they’re working with. If you don’t see what you use, you’ll look elsewhere.

Mike: You’ve been quoted saying that, in creating Swagger, you wanted to "avoid the CORBA problem." What is the CORBA problem? And what is it about Swagger that you are doing to avoid that problem?

Tony: From my point of view, the CORBA problem is simply "Design by Committee". You simply cannot have a successful specification if you try to solve everybody’s problems with it. There’s a saying in the design world, "if you take all the beautiful colors and mix them together, you get an ugly grey". Same goes with software designs—when forming a project like Swagger, you need to take a clean, coherent approach to what you want it to do. Once there’s traction, there’s much more room for input, but only after the direction is set.

Mike: What role has SmartBear played in the history of Swagger and why were they selected to lead Swagger at this time?

Tony: SmartBear was one of the first vendors to integrate Swagger into their tooling. We’ve been working together for some time now and, in the API space, they are in the right position to lead Swagger. They will take the right approach to the openness of the spec, tooling, and community. They know that — even for commercial products built on top of Swagger — the industry as a whole benefits from a consistent API model. Having been in the API testing space for so long, they probably have more exposure to API design than any other company.

Mike: Now that Swagger is in the hands of SmartBear, what will your role be in the future of the specification?

Tony: I’m certainly planning on continuing contributing to the project. There will be many more resources and much better support for those who need it. I’m looking to continue work on both the toolchain and the specification.

Mike: Leonard Richardson describes a continuum of standards from Fiat to Personal to Corporate to Open. With the first being just agreed behavior and that last being the results of a standard committee like the W3C, IETF, OASIS, etc. By his measure Swagger started as Personal standard within your company and quickly progressed to a Corporate standard used by a wide range of organizations. Do you see Swagger progressing to an Open Standard any time soon?

Tony: We’re still working on the right governance structure for the Swagger specification. It will be open. The question is how formal the structure will be. I expect that we’ll come to the right conclusion when the analysis is done.

Mike: Is there anything else you’d like to talk about that I haven’t asked yet?

Tony: I think you covered most everything. Thank you for the time.

About the Interviewee

Tony Tam, VP, Emerging Technologies, along with the EVP, Engineering will assist with all technology efforts for NDN. Prior to joining NDN, Tony served as the founder and CEO of Reverb, where he lead development efforts of the site's innovative word navigation system. He is a member of the MongoDB Masters group and leads the Swagger API Framework open-source initiative. Prior to joining Reverb, he was a founder and SVP of Engineering at Think Passenger, a provider of customer collaboration software. Before that, he was lead engineer at Composite Software where he helped develop the company's first- and second-generation query processing engines and led the research and implementation of their patented cost-based federated query optimizer. He also led software development in the bioinformatics group at Galileo Labs, a drug-discovery company based in Silicon Valley.

This series focuses on three key areas of "meta-language" for Web APIs: API Description, API Discovery, and API Profiles. You’ll see articles covering all three of these important trends as well as interviews with some of the key personalities in this fast-moving space.

InfoQ Weekly Newsletter

Join a community of over 250 K senior developers by signing up for our newsletter. If you are based in the EEA, please contact us so we can provide you with the protections afforded to you under EEA protection laws.

InfoQ Weekly Newsletter

Join a community of over 250 K senior developers by signing up for our newsletter. If you are based in the EEA, please contact us so we can provide you with the protections afforded to you under EEA protection laws.

Is your profile up-to-date? Please take a moment to review and update.

Email Address

Note: If updating/changing your email, a validation request will be sent

Company name:

Keep current company name

Update Company name to:

Company role:

Keep current company role

Update company role to:

Company size:

Keep current company Size

Update company size to:

Country/Zone:

Keep current country/zone

Update country/zone to:

State/Province/Region:

Keep current state/province/region

Update state/province/region to:

Subscribe to our newsletter?

Subscribe to our architect newsletter?

Subscribe to our industry email notices?

By subscribing to this email, we may send you content based on your previous topic interests. See our privacy notice for details.

You will be sent an email to validate the new email address. This pop-up will close itself in a few moments.

We notice you're using an ad blocker

We understand why you use ad blockers. However to keep InfoQ free we need your support. InfoQ will not provide your data to third parties without individual opt-in consent. We only work with advertisers relevant to our readers. Please consider whitelisting us.