GlueCon 2013 Notes: Does Your API Have Swagger? – Sumit Sharma, Mulesoft

Does Your API Have Swagger? – Sumit Sharma, Mulesoft Too often we slap on an API and let the consumers suffer Inside-Out API development – over designed, too many abstractions REST APIs can catch you off guard – different semantics, documentation as an afterthought, client libraries vary, versioning issues, input parameters rarely documented and are trial-and-error Time to start thinking APIs First Goals Outside-In rather than Inside-Out Standardize as much as possible Reduce heavy lifting Change your approach (outside-in) Describe the API Set expectations Test your hypothesis Build from the interface (and commit to it) Usability isn’t just for the UI, it is for APIs as well Describe the interface – the model, avail operations, parameters (type, allowed values), input/output models, error responses Set expectations – don’t make them guess Test your hypothesis – prototype and tinker until you find what works best, communicating changes really well Build from the interface – would be nice to have generators for client/server/docs, generate manually There are a variety of standards for API specifications (WADL, Blueprint, Javadocs, etc) Swagger is a spec for declaring an API interface/schema, support auto-generating the spec and code, offers a JSON-based test framework Like a sitemap for your API Getting started – convert/scrape docs into Swagger, manually, runtime analysis Server-side and client-side developers can then work in parallel, once the interface is defined clearly Swagger can get tedious, lacks OAuth2 support (in progress), needs to broaden reach (can’t doc S3 API currently), need a more intuitive UI to help design

James Higginbotham

May 22, 2013 · 2 min read