[zzen]

(disclaimer, I'm founder of Apiary, which started apiblueprint.org)

I'm happy that Mulesoft are getting on the "better, human readable API DSL" bandwagon. It's very important.

At Apiary we found that embedding one format (Markdown, for human-readable documentation) into another format (YAML, for structured parseable data) is hard for the consumer, tough for the text editors/IDEs/syntax highlighters and ultimately useless. That's why apiblueprint.org is PURE markdown, that displays well on GitHub, has great syntax-highlighting support in your editor - and is just as parseable (since we ship an MIT-licensed parser with it).

I wish we could've united on a single format, but I guess the stronger will win and a little competition is always good for the end-users.

[auvrw]

> I wish we could've united on a single format, but I guess the stronger will win and a little competition is always good for the end-users.

the (open source) tooling is what makes or breaks adoption of languages like these, and neither of them has much to offer in that regard. apiblueprint has code for node and .net, raml doesn't even list libraries that can parse it. contrast that with json schema: there's an rfc standard and libs that handle validation in almost every widely-used general-purpose language...

... and that's just the bare minimum of tooling i would hope for from a popular standard. i'd be much more psyched to find an equivalent library of <http://www.rexx.com/~dkuhlman/generateDS.html> for jsonschema than i am to see yet another domain specific language with bad/no tooling. a standard without an implementation is nothing more than a suggestion -- and one that is unlikely to be strictly adhered to.

[zzen]

Sure, API Blueprint supports JSON Schema. If you're happy to put in the effort, nothing stops you from using JSON Schema in the blueprint and all the tooling built on top of it.

[auvrw]

but that's my point: there isn't as much library support as there ought be, even for json schema, let alone these newer domain-specific languages that incorperate/extend json schema.

sometimes i think it would make just as much if not sense to define these communication protocols with a bnf grammar (for endpoints and response codes) or to use s-expressions (since json is pretty much just sugared lisp) or some other well-worn-but-adaptable format just because there are already parser generators and scheme interpreters written for every language.

[usarid]

couldn't agree more that it ain't much without tooling -- RAML's been out for only about 24 hours, but open-source tooling is right around the corner (weeks, not months).

[usarid]

Regarding tooling.. check out the video that just went up on http://raml.org (and on Youtube: http://youtu.be/5o_nExedezw)

[usarid]

(disclaimer, I'm from the RAML workgroup -- nice to see you here, Jakub!)

As you know, we carefully considered swagger and blueprint, before embarking on the RAML path. There's a bunch of us who are strong believers in very human-readable API specs, though we also strongly believe in clean API specs that reveal the structure of the API and encourage consistency and reuse -- and we just didn't find that in existing DSLs.

We're actually not finding any issues embedding markdown documentation in RAML at just those points in the spec that need documentation, while letting the spec itself do the talking when more documentation would just be repetitive. That way the structure of the API is manifest.

We also find the spec to be much DRYer in RAML than other ways; less repetitive reading means quicker and better grokking of the API.

I think the point about syntax highlighting in generic editors is debatable, but that's fine -- as you say, we have two different approaches and we'll keep each other on our toes, to the benefit of the community. Apiary's dedication to user experience is an inspiration to us. And just in case, my invitation to you to consider collaborating with us and the other workgroup members on RAML remains very much open.