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:
- One person driving an editor writing JSON files, which are the Swagger spec for the needed API
- The all three discussed the operations, parameters, while adding them to the JSON, and re-running the swagger spec validator after each meaningful change
- When they were happy with the specs, they loaded the JSON files into the UI through apache installed on a local machine
- After they inspected each API and operation again, they wrote the models in the spec files, and reviewed again to make sure everything was good
- Then they ran the Swagger Codegen and generated a Scalatra (Scala) server from the spec files
- Then they ran the Swagger Codegen and generated an Objective-C client from the spec files
- The server developer went off and wired the server to the business logic
- The front-end guy went and wired the UI to the objective-c library
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.
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.
|API Design, API Development, API Evangelist, Interactive Docs, Swagger, Wordnik|
blog comments powered by Disqus
Latest Blog Posts
- My First Keynote With The Infamous Audrey Watters
- Are You Going To Be At API Days in San Francisco? I Am!
- Updated API History White Paper
- History of APIs - Twilio
- API Providers Guide - API Design
- Box Opens Up Revenue Sharing For API Developers
- History of APIs - Mashery
- A Book API Platform
- History of APIs - del.icio.us
- API Management Using Github
- In The End API Providers Will Only Sell Bandwidth
- The Build-Up To #APIStrat in October
- APIdays Mediterranea Is A Wrap
- Helping EFF Urge The Courts to Block Copyright Claims in Oracle v. Google API Fight
- API Aggregation For Federal Government with FedAPI
- Have You Checked Out Webshell Lately?
- New Features From BaaS Provider AnyPresence
- Signals I Use To Monitor Companies In The API Space
- API Management Using APiphany
- Github Can Be More Than Code
- Quick Demonstration Showing The Benefits of The White House Digital Strategy
- IRS Needs To Use White House Open Data Policy For Guidance
- Dropbox As Your Apps Default File System
- DataSift's Open Source World
- Salesforce Adds Sandbox Templates