Can anyone add practical experience with the API spec tools. This is a new name for me.

I had a look at the websites for each of the three tools the article specifically mentions

    http://raml.org/
    http://swagger.io/
    https://apiblueprint.org/

I get the impression that these are code generating tools built from a specification file.

I have real world experience with two tools which fit that rough description. SOAP and google app-engine end-points.

I would unambiguously describe both as awful. Really horrible experiences with both. They tie your systems to large, and difficult to understand tool sets. SOAP wasn't obviously buggy, but app engine endpoints are unpredictable and the generated code produces some serious awkwardness.

I don't want to slap a label on these tools and dismiss them off-hand.

Anyone used them 'for the win'?

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 or https://apiary.io

[2]: https://github.com/apiaryio/dredd

[3]: https://www.datawire.io/microservices-practitioner-summit-wr...

[4]: https://sendgrid.com/blog/quickly-prototype-apis-apiary/

[5]: https://apimatic.io