Why Swagger Makes APIs Easier To Describe and Consume
In the past few months, there have been a few developments that show how the API is abstracting, becoming less complex from a design and consumption point of view. In particular, is the emergence of Swagger, an open standard for describing REST APIs with JSON. At API Days in San Francisco, I sat down to talk with a few API experts to discuss how Swagger is used to create documentation for client and server side code. Joining me were Steve Willmott, founder of 3Scale; Ed Anuff, vice president of public strategy at Apigee; Mike Amundsen of Layer 7 and Kin Lane of API Evangelist. 3Scale, Apigee and Layer 7 are all API management companies.
There have been previous versions of this story before. WADL is an often noted example. Swagger is different in that it was created by a user not a vendor. Wordnik developed Swagger for its own use during the development of developer.wordnik.com and the underlying system.
According to Wordnik it began in early 2010 — the framework being released is currently used by Wordnik’s APIs, which power both internal and external API clients. As noted by Wordnik, Swagger has a declarative resource specification, allowing clients to understand and consume services without knowledge of server implementation or access to the server code.
It has a UI framework for developers and non-developers to interact with the API in a sandbox UI that gives clear insight into how the API responds to parameters and options. Swagger speaks both JSON and XML, with additional formats in the works. The business user, and who the business user is, has changed quite a bit, said Anuff.
You now need to publish for external consumption but to describe the interactions that a mobile app will take. That is not a use case the previous generations of API description languages considered. Business users want to know abou the API calls that are made when a user puts something in a shopping cart.That information can be used to make decisions about popular products people are using. Swagger makes it easier to do.
Apigee is a sponsor of The New Stack.