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

1 minute read

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