Swagger Offers Lightning Quick Connection To Your API

Romin Irani
Jul. 23 2013, 10:00AM EDT

As APIs explode, one of the key metrics to successful API adoption is Time To First Hello World (TTFHW). And one way of getting that done is to providie API Documentation that helps developers get going quickly. But simply listing down your API methods and request/response formats is not going to cut it anymore. This is the age of interactive API documentation where developers can try out your API by exercising the methods and various parameters from right within your Developer Portal.

One of the most popular tools for creating interactive API documentatin is Swagger. Our earlier coverage on Swagger showed how in its own words, Swagger is complete framework for “describing, producing, consuming, and visualizing RESTful web services.” Swagger was launched early this year by Reverb, which was formed by the team that gave us the wonderful Wordnik API.

It is no coincidence that with the rise of public APIs, the language that has been seeing the most traction on client side and making forays into Server side is JavaScript. Providing a JavaScript API to your service has to probably rank among the top items in your product release and swagger-js aims to do exactly that i.e. to make it as quick as possible to connect to an API via JavaScript.

So assuming that you have used Swagger to create a Resource Listing of your APIs on the Server and the API Declarations, the swagger-js client is an intelligent object that performs two simple steps to bring in all that intelligence and enable you to start making calls right away. The swagger-js client as mentioned in the blog, "First, it calls the API and reads the Resource Listing (the list of all APIs on the server). Next, it reads each API Declaration and builds itself. It is able to invoke your API because as part of its build phase, it is able to parse out the API declration and determine "the HTTP method, parameters, response types, content types, etc., " that are needed to make calls. The client is not just limited to retrieving data but also supports API methods that need you to send data.

Given that time to market is decreasing for most organizations and the need for solid code generation based on meta-information, swagger-js is sure to see interesting ways in which developers will use it ranging for a quick way for companies to expose their API, Developers to try out and even Testers to validate an API. The project is FOSS, so you can always reach out and contribute.

Romin Irani Google Developer Expert Cloud 2014. Romin loves learning about new technologies and teaching it to others. Follow me on Google+

Comments