TIL about RAML, raml.org - on the fence about the idea. Why a new syntax? Looks YAML-ish, is it? Could easily be JSON.
5
3
5
@timbray Looks like WSDL. I don't think formalizing API documentation like this serves much purpose.
5
1
1
@dhh WSDL was deeply broken, no self-consistency. I remember @nelson saying, 15 years ago: “I want a .h file for this HTTP service.” Hm..
1
@timbray Certainly. I don't see how this is any less broken.
1
@dhh Clearly you never actually tried to deal with WSDL; congratulations.
1
1
@timbray Conceptually broken, I mean. Which surely leads to the actual brokeness poor WS-Deathstar operators had to deal with ;)
2
@dhh I kept wondering if there might’ve been something to the API-schema idea. But it was built on shit, XSD & WSDL, so tough to tell.
1
2
Replying to @timbray
@timbray @dhh Fundamental problem, not one tied to the implementation. Out-of-band schema may or may not have anything to do with real life.

Mar 28, 2014 · 8:03 PM UTC

2
1
Replying to @stilkov
@stilkov @timbray @dhh unless of course the schema is part of your CI: github.com/apiaryio/dredd
1
@jakubnesetril @timbray @dhh If you control all the clients, maybe. It’s not about documentation getting out of date, but clients themselves
1
Replying to @stilkov
@stilkov @timbray Heroku chose JSON Schema (json-schema.org/) for that blog.heroku.com/archives/201…