{"API Evangelist"}

Generate API Server, Docs and Client Code Using Swagger

We all have our own approaches to API design and development, many of which will never see the light of day. In the API space we hear a lot about API management and API success stories, but not much about the process of designing, developing and initial deployment of APIs. I just had a little taste of how the Wordnik team approaches it, using Swagger.

Often when you hear about Swagger in the industry, you hear about the UI portion. You know the sexy interactive documentation that is fast becoming a standard with APIs, but it’s just the tip of the iceberg--there is a whole lot more power to Swagger, than just interactive docs.

“The heart of Swagger is the specification, and from that, cool shit can get done!”, say Tony Tam Wordnik CEO and technical co-founder.

To demonstrate, Tony walked me through Wordnik’s approach to designing, developming and deploying a new API driven iPad app, using a team of 3:

The process took 2.5 hours in total, from API to interface--a technique they call interface-driven development, which focuses on modeling the perfect interface for the problem they are trying to solve using an API.

To solve this particular problem, they needed a scala server for the back-end. they could have just as easily generated a Node.JS server, a Rails Sinatra server or any other based upon simple mustache templates. Additionally they could generate JavaScript, Scala, PHP or Python clients, but for this project they only needed Objective-C.

The Wordnik approach to API design and development using Swagger is interesting. For me, it demonstrates that a clean API spec should not be an afterthought, and a means by which you generate interactive API documentation, or when API discovery becomes an issue. Your entire design, development and management process should center around a meaningful API spec, which will then allow you to deploy your API server, interactive documentation, client code, while also providing API discovery.