I've worked with API Blueprint as it seems to have the widest support across API tooling providers, along with a sane syntax. It's really nice to be able to sp

I've worked with API Blueprint as it seems to have the widest support across API tooling providers, along with a sane syntax. It's really nice to be able to spec out a blueprint and then simulate an API [1]. Also being able to run tests on the real API, but based on the API docs which describe expected behavior, has exposed many bugs [2]. I just recently watched the "Microservices Summit" from microservices.com/Datawire [3], and the most-repeated lesson from Netflix, Amazon, and Yelp was to design API-first, not data-first. As engineers we tend to design an API around our data -- but developers have to interact primarily with the API, and then with the data. With API spec tools we can quickly fake an API and try to interact with it, then find out what sucks and rewrite it, all before sinking time into the actual implementation. SendGrid does this, and their API has been a breeze to work with [4]. The last step is to use a client SDK generator like Apimatic [5] -- but that only works if the API actually conforms to the docs. It's probably difficult to get an entrenched codebase to switch to spec, but for any new API I wouldn't do it any other way. [1]: https://github.com/localmed/api-mock https://github.com/localmed/api-mock or https://apiary.io https://apiary.io [2]: https://github.com/apiaryio/dredd https://github.com/apiaryio/dredd [3]: https://www.datawire.io/microservices-practitioner-summit-wrap-up-2/ https://www.datawire.io/microservices-practitioner-summit-wr... [4]: https://sendgrid.com/blog/quickly-prototype-apis-apiary/ https://sendgrid.com/blog/quickly-prototype-apis-apiary/ [5]: https://apimatic.io https://apimatic.io