After the Linux Foundation announced the formation of the Open API Initiative (OAI) in the beginning of November with an impressive list of founding members, API developers had questions about the role OAI would play driving consensus around standards.
Tony Tam, founder of the Swagger project, addressed some of these questions later in November at the API Strategy and Practice Conference in Austin, Texas. InfoQ met Tony at the conference to get in-depth answers to questions we felt our readers would want to ask.
InfoQ: Can you tell us more about your new role at SmartBear and why you recently decided to join them?
Tony Tam: I joined SmartBear to have the opportunity to work full time on Swagger for the first time. I’m responsible for all Swagger products, including professional support, open source, SwaggerHub, and our involvement in the Open API Initiative.
InfoQ: The Open API Initiative (OAI) was recently announced under the Linux Foundation. Can you tell us what it is all about?
Tony: The goal of the OAI is to provide a neutral and open ownership of the thing that makes Swagger work: the specification itself. The OAI was initiated as many large companies have made significant investments on infrastructure that depends on Swagger. And in doing so, they are looking for visibility into the future of the specification and a voice in setting direction.
SmartBear worked with the Linux Foundation and brought in a short list of forward looking companies that understand the value of both an open description and consistent definition for APIs. SmartBear is generously transferring ownership of the Swagger specification to the OAI workgroup.
InfoQ: There has been high interest on Swagger governance after SmartBear took over its sponsorship earlier in 2015. Can you give us some insights on the analysis and decision process that led to this governance structure?
Tony: For all tooling and infrastructure companies, it’s important that they speak a common language to build better tooling and services. They can use Swagger as this common language.
In moving the specification to open governance and getting support from companies like Microsoft, IBM and Google, they will simply be more services described in Swagger for developers to use, with the same common interface and tools.
When choosing the Linux Foundation, we investigated most of the popular modern structures. Given the nature of the OAI (a spec vs. software), the Linux Foundation made the most sense, as they have recent and relevant experience with similar efforts around the Open Container Initiative and others.
InfoQ: What will be the respective roles of the corporate members and the grass-root community? With large corporations directly involved, is there a CORBA risk for the upcoming OAI Specification (Open API Format)?
Tony: I don't think that there is a CORBA risk because the trajectory is already set. If we were building something like Swagger from scratch, it may have been doomed, but the founding members in the workgroup have all seen what has made Swagger successful, which is the community.
To keep the community happy, we need to maintain the core values that Swagger has been built on. We purposely invited non-vendors who are knowledgeable API users into the working group because they are solving immediate business needs with APIs and will help keep the format practical.
InfoQ: After years of competition and maturation, API Blueprint, RAML and Swagger seem to have much more things in common than differences. Do you think it would be technically possible to merge into a single API description language?
Tony: I think that there is definitely technical similarities between the formats and some aspects of them could be converged into one. Philosophically, they are quite different and I don't see that changing.
InfoQ: The Open Container Initiative that launched in June 2015 reunited competing Docker and CoreOS companies around a common container format. Do you encourage Apiary and MuleSoft, the respective sponsors of API Blueprint and RAML to join the OAI?
Tony: Sure, it's open to anyone who wants to join.
InfoQ: Besides describing the API contract, other initiatives such as APIs.json and API Commons attempt to describe other aspects of an API. Do you think they should converge into a common API language under the OAI umbrella?
Tony: It's possible that there should be more formats than just the API description. For example, SwaggerHub uses the apis.json format. Would that be part of the same format? I don't know. We are not looking at making the OAI Spec cover every use case or it may end up looking like a YAML version of WADL.
InfoQ: What is the goal of the Swagger Framework now that the Swagger specification, its core component, has been donated to the OAI?
Tony: With the specification moving to the OAI, Swagger tools will start implementing the specification, and enable developers to interact with those services. The Swagger OSS tools will continue to be fully open source and SmartBear will only grow the support around the community.
InfoQ: Should we now talk about OAI Spec instead of the Swagger specification, or is OAI Spec something that has yet to be defined using the Swagger specification as a starting point?
Tony: The existing Swagger Specification will be transferred as is, and will be owned by the workgroup. The OAI will release the OAI Specification--which will be based on the Swagger Specification--when the technical team is ready. So to answer your question, the OAI Spec will introduce major changes which will differentiate it from the existing Swagger Specification. It will be different.
The Swagger ecosystem of tools, open-source software will continue to be called Swagger and continue on their existing path, being open and neutral. They will support the OAI Specification when it is ready. On Swagger.io, we will continue to promote the best tools in Swagger ecosystem, regardless of who makes them.
InfoQ: What are the latest enhancements that were released by the Swagger Framework, for example on the codegen front? Do all the components now support version 2.0 of the specification?
Tony: The latest things released are a framework for Java that is a Swagger-driven API framework that is called Swagger Inflector which makes the Swagger definition the source of truth for the entire application. That was released at the beginning of November and I believe it is one of the small number of very advanced ways to build APIs from a description without a lot of the repetitive plumbing.
A major update of Swagger Codegen was released at the beginning of November as well that pulled in about 170 community-driven contributions and added support for TypeScript among other changes. The JavaScript client was updated at the end of November and added support for promises and other advanced interceptor patterns. There will be many more releases in the next few weeks of the core tooling.
From the official Swagger projects, we now see about three quarters of the downloads are for version 2.0 of the specification. Most of the tooling supports constructs of version 2.0. There are still community created projects that use older versions and we are still helping creating interoperability tooling. Our philosophy has been that software must be compatible one version back. Even our codegen supports the 1.2 format which is now two years old.
InfoQ: You announced SwaggerHub at the recent API World conference in Santa Clara. Can you tell us more about it and how it relates to the Swagger Framework?
Tony: SwaggerHub is an API lifecycle tool that uses open source Swagger products in a SaaS offering to put APIs at the center of the design process. It is intended for developers, architects, project managers and technical writers to contribute to the design of the API, before the software is actually written.
It integrates with GitHub for the software lifecycle and tools like Swagger Inflector can use it as a runtime source of truth for the API. You'll see private API features coming shortly but we already have over 2k APIs in the system.
InfoQ: There seems to be a continuous resurgence of RPC on the Web, such as gRPC announced by Google earlier this year. How do you analyze this phenomenon?
Tony: I believe that people just want to consume APIs and in many cases don't really care how it happens. Of course, it's more complicated for creating a good API so it can be easily consumed but ultimately it speaks to implement a client and access to the API is the most important factor to adoption and success.
Many SDKs treat APIs effectively like RPC and abstract the underlying protocols from the end-user so in many cases it doesn't matter how RESTful the API is.
I believe a well thought-out RESTful URL structure is an important part of turning a potentially complex remote system into discrete parts as opposed to a single endpoint that processes every type of request, like SOAP services.
REST design forces a practical set of divisions inside an API and when we look at tools like AWS Lambda, they will work best in a REST type structure where small components of business logic can respond to discrete endpoints. So, I do think that REST matters and will continue to matter but my opinion is to the consumer point of view they don't really care. It's more important to the provider.
InfoQ: Do you think that Swagger and REST APIs in general are a good fit for microservices or that more optimized protocols will become necessary?
Tony: Swagger or similar description formats are necessary for a strong microservices framework. I haven't seen many situations where REST is not performant enough. I'm sure they do exist, and in those cases they should use whatever protocol is appropriate but they will still need to describe the APIs whether they use JSON or ProtocolBuffer.
InfoQ: In a recent interview, Daniel Jacobson questioned the value of formal API description languages for ephemeral APIs. Do you agree with him and do see other cases where formally specifying APIs, using Swagger for example, is not desirable?
Tony: If APIs are ephemeral, it is even more important that they are both described and automatically consumable. In environments where they are a lot of services doing discrete amounts of work, it's impossible to constantly be hand crafting client SDKs to consume them.
Rapid versioning or ephemeral services need definition more than anything else because long-living static APIs can survive with static documentation and handcrafted clients.
InfoQ: From your experience, what percentage of developers prefer code-first versus API-first today and how will that percentage evolve in let’s say two to three years?
Tony: I would say it depends on the maturity of the company and the industry. If you look at the sheer number of developers, you would find that most people use code-first.
New projects however, because of tooling, better libraries, and features that make you put the design first, will slowly have developers migrate their process towards specification-first development.
And for at least three Swagger projects now (Swagger Inflector, Swagger Node and Zalando Connexion), you must have a specification for the server to work. That's the way all APIs are going to go. Specification is the source of truth or the DSL that the library uses to connect to endpoints to the business logic.
In the next year, we'll probably have 50% starting with an API specification but because that makes a challenging workflow for servers, I expect that new tools that use the specification for the routing logic will slowly overtake static code generation for servers.
InfoQ: Who should be responsible for designing a private API contract? The provider of the API or its consumer?
Tony: Both. It should be some collaboration. The consumer should be able to give feedback on the provider API so it can improve. My take is that the consumer should drive the use case and the server designer should add practicality. The design process is collaborative from both parties but ultimately it should fulfill the consumer needs first.
Disclaimer: the author of this article works for Restlet, a web API platform provider member of the OAI and supporting several web API languages including Swagger and RAML