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